邮件本地化

Lingo.dev 的 CLI 和本地化 API 支持两种邮件本地化方式：一种是在构建阶段翻译模板文件，产出按语言区域区分的模板；另一种是在发送前于运行时翻译内容。两种方式都会经过已配置的本地化引擎，并自动套用术语表规则、品牌语气和模型选择。

选择适合你的方案#

方案	适用场景	工作方式
构建阶段（CLI）	模板文件：react-email、MJML、HTML	翻译仓库中的文件，并部署按语言区域区分的模板
运行时（API）	动态内容、由 ESP 渲染的模板	发送前调用本地化 API，再将翻译后的内容传给你的邮件服务提供商

该怎么选？

如果你的邮件模板以文件形式保存在代码仓库中（HTML、MJML 或 React 组件），请选择构建阶段方案。如果邮件内容是动态生成的，或存放在邮件服务提供商中，则请选择运行时方案。

前置条件#

每一次翻译都会经过一个本地化引擎——也就是决定使用哪种 LLM 模型、术语表、品牌语气和指令的配置。先在 Lingo.dev 控制台中创建一个引擎，并生成一个 API 密钥。

构建阶段本地化#

CLI 可直接翻译邮件模板文件。配置一个与你模板格式匹配的 bucket，运行 CLI 后，即可在源模板旁生成按语言区域区分的模板文件。

react-email 模板本质上是可渲染为 HTML 的 React 组件。你可以借助 react-i18next 等 i18n 库，将可翻译字符串提取到 JSON 资源文件中，再用 CLI 翻译这些 JSON 文件。

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["emails/locales/[locale].json"]
    }
  }
}

渲染时，将语言区域传入邮件组件并加载对应的 JSON 文件。react-email 的 render() 函数会生成可直接发送的对应语言区域 HTML。

使用以下命令运行翻译：

bash

npx lingo.dev@latest run

运行时本地化#

当邮件内容是动态的——例如个性化通知、用户生成内容摘要，或存储在 CMS 中的营销文案——应在发送前于运行时完成翻译。这一方案建立在 Translation API 指南所介绍的模式之上。

javascript

async function sendLocalizedEmail(userId, templateId, content) {
  const user = await db.users.findById(userId);

  const response = await fetch("https://api.lingo.dev/process/localize", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.LINGODOTDEV_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      engineId: "eng_abc123",
      sourceLocale: "en",
      targetLocale: user.locale,
      data: {
        subject: content.subject,
        preheader: content.preheader,
        body: content.body,
      },
    }),
  });

  const { data } = await response.json();

  await emailProvider.send({
    to: user.email,
    subject: data.subject,
    html: renderTemplate(templateId, data),
  });
}

最佳实践#

场景	建议
邮件主题	尽量控制在 50 个字符以内。使用术语表锁定品牌名称，避免被翻译。
预览文案	应与正文分开翻译——邮件客户端会单独展示这部分内容。
品牌语气	在本地化引擎中为不同语言区域分别配置语气。例如，日语营销邮件所需的语域就与德语不同。
RTL 语言	针对阿拉伯语、希伯来语和波斯语，请在邮件客户端中测试渲染结果。不同客户端对 HTML `dir="rtl"` 的处理方式并不一致。
键锁定	对于不应翻译的 URL、产品名称和法律标识符，请使用锁定键。

下一步#