电子邮件本地化
将主题、预览文字和正文一并翻译,再结合收件人的语言区域和模板变量值,渲染出完整邮件。
邮件在读者打开之前,就已经开始传递信息。主题和预览文字作出的承诺,需要正文、按钮和替换后的变量值以同一种语言兑现。将这些内容放在同一份翻译源文件中,再按同一收件人语言区域渲染。
对于反复使用的事务性邮件模板,请在发送前完成文案目录的翻译。发送程序可以加载已接受的文案目录并渲染邮件,无需等待新内容生成。如果内容无法提前准备,可以使用运行时翻译;但这种方式需要明确的失败处理和投递策略,下文会详细说明。
将文案与收件人数据、投递数据分开 #
创建 emails/locales/en.json,写入如下文案:
{
"subject": "Your order is on its way",
"preheader": "Track delivery for order {orderNumber}.",
"heading": "Your order has shipped",
"body": "Hello {name}, your order will arrive within {days} business days.",
"cta": "Track your order",
"footer": "You received this message because you placed an order."
}模板提供 name、orderNumber、days 和追踪 URL。不在翻译源文件中包含收件人数据,既能避免为每笔订单重新生成相同的邮件,也能避免不必要地发送隐私数据。如果个人数据会影响措辞,请在提交前确认已获准将其提供给翻译服务。
使用与现有渲染器兼容的占位符语法。JSON 翻译不会替你选择模板语言。请提供收件人与发件方的关系、投递承诺和必需法律措辞等上下文。在这个示例中,“将会送达”是一项承诺,不能因为调整表达风格而变成“可能送达”。
翻译文案目录 #
在项目根目录中初始化当前版本的 CLI:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'emails/locales/en.json' --yes
lingo link
lingo push --backfill-missing --wait关联要使用的组织和本地化引擎。首次回填会生成 emails/locales/es.json;如果首次只执行普通推送,可能仅保存基线,而不翻译缺失的目标内容。请等待翻译确实完成,并在使用目标内容前检查主题、预览文字、正文和占位符名称。
使用 React Email 时,加载文案目录中的字符串,并传入现有组件。使用 MJML 时,在编译 HTML 前通过项目的模板层替换文案;CLI 不会读取 .mjml 文件。布局、转义和链接仍由这两种渲染器负责。
翻译纯 HTML 模板 #
如果模板是纯 HTML 文件,CLI 可以直接翻译。添加一个路径中包含源语言区域的匹配模式,例如 emails/en/*.html,每个目标语言区域都会生成独立文件,例如 emails/es/order-shipped.html。HTML 格式会将翻译后的文本和受支持的属性写入源文件副本,原样保留链接和未改动的标记,并保护 {{...}} 模板标记。
发送前渲染完整的本地化邮件 #
使用应用现有的预览渲染器,为源内容和目标内容传入相同的安全值。也可以用一个最简 Node 测试脚本,在不发送邮件的情况下验证纯文本版本。将其保存为项目根目录下的临时文件 preview-email.mjs:
import { readFile, writeFile } from "node:fs/promises";
const locale = process.argv[2] ?? "es";
if (!["en", "es"].includes(locale)) {
throw new Error("Unsupported preview locale");
}
const messages = JSON.parse(await readFile(`emails/locales/${locale}.json`, "utf8"));
const values = { name: "Alexandra Example", orderNumber: "EXAMPLE-42", days: 3 };
const trackingUrl = "https://example.com/orders/EXAMPLE-42";
function message(key) {
if (typeof messages[key] !== "string" || messages[key].length === 0) {
throw new Error(`Missing message: ${key}`);
}
return messages[key].replace(/\{(\w+)\}/g, (_, name) => {
if (!Object.hasOwn(values, name)) {
throw new Error(`Unknown placeholder: ${name}`);
}
return String(values[name]);
});
}
const preview = {
subject: message("subject"),
preheader: message("preheader"),
text: [message("heading"), message("body"), `${message("cta")}: ${trackingUrl}`, message("footer")].join("\n\n"),
};
await writeFile(`email-preview-${locale}.json`, JSON.stringify(preview, null, 2) + "\n");运行 node preview-email.mjs en 和 node preview-email.mjs es,然后比较保存的两份预览。这个测试脚本只支持简单的命名占位符,不实现 ICU、复数形式选择、HTML 转义或邮件投递。这些功能请交由生产环境的模板渲染器处理。如果模板要求传入已格式化的值,请先按收件人的语言区域格式化日期和数字,再传入邮件。
还应使用长值和空值渲染 HTML 与纯文本版本。检查预览文字是否出现在预期位置、按钮是否指向已授权的追踪 URL,以及法律标识和退订功能是否保持完整。检查受支持的客户端、移动端截断情况、较长的标签,以及需要时的从右到左布局。主题长度建议不能替代在实际客户端中查看邮件。
如果内容需要运行时翻译 #
将凭据和翻译调用保留在服务器端。以内联 JSON 文档的形式提交邮件字段,启动任务,并在渲染邮件前下载已完成的目标内容。提前将这项工作加入队列,让发送程序在投递前等待翻译及所有已配置的审核完成。
记录此次请求的源语言区域、目标语言区域、内容修订版本和本地化引擎配置。请求被拒绝与任务已接受但随后失败,应分别处理。渲染前,验证必需的主题和正文字段,并检查占位符兼容性。如果所选工作流需要等待审核,发送流程必须遵循这一状态。
明确翻译失败或仍在等待时如何处理投递:稍后重试、使用已审核的备用内容,或暂不发送邮件。验证通过后,将已接受的内容交给现有邮件服务发送。
将已批准的文案与模板修订版本一同保存 #
后续源内容发生变化时,使用 lingo push --wait,然后再次比较渲染结果。将文案目录、模板、已接受的目标内容和 CLI Lockfile 一同保存。刷新前,先保存已有的修正。若要检测提交后对目标内容所作的修改,请省略 --wait,并在获取前检查 lingo pull --dry-run。有关冲突处理,请参阅保留已审核的翻译。
源内容中的承诺发生变化时,请先审核相应的目标邮件,再将发送程序切换到该修订版本。规划多语言发布介绍了如何针对不同语言区域作出这一投递决策。