Как локализовать письма
Переведите тему, прехедер и основной текст вместе, затем сформируйте готовое письмо с учётом локали получателя и значений шаблона.
Письмо начинает работать ещё до того, как его откроют. Тема и прехедер дают обещание, которому должны соответствовать основной текст, кнопка и подставленные значения — всё на одном языке. Храните эти части вместе в исходнике для перевода, а затем формируйте письмо с одной и той же локалью получателя.
Для регулярных транзакционных писем переводите каталоги до отправки. Так сервис отправки сможет загрузить принятый каталог и сформировать письмо, не дожидаясь новой генерации. Перевод во время выполнения пригодится, если контент нельзя подготовить заранее. Для этого варианта нужны чёткие правила обработки сбоев и доставки — о них ниже.
Отделите текст от данных получателя и доставки #
Создайте 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. Обычный первый push может сохранить исходное состояние без перевода для недостающих целевых локалей. Дождитесь полного завершения и проверьте тему, прехедер, основной текст и имена плейсхолдеров, прежде чем использовать перевод.
Для 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, затем снова сравните сформированные версии. Храните каталог, шаблон, принятые переводы и Lockfile CLI вместе. Перед обновлением сохраните существующие исправления. Чтобы обнаружить правки переводов, внесённые после отправки задания, не указывайте --wait и проверьте lingo pull --dry-run перед получением результатов. О том, как разрешать конфликты, см. в разделе Как сохранить проверенные переводы.
Если обещание в исходнике изменилось, проверьте соответствующие переводы писем, прежде чем переключать сервис отправки на новую версию. В разделе Как спланировать многоязычный релиз описано, как принять это решение об отправке для разных локалей.