Как локализовать письма

Переведите тему, прехедер и основной текст вместе, затем сформируйте готовое письмо с учётом локали получателя и значений шаблона.

Письмо начинает работать ещё до того, как его откроют. Тема и прехедер дают обещание, которому должны соответствовать основной текст, кнопка и подставленные значения — всё на одном языке. Храните эти части вместе в исходнике для перевода, а затем формируйте письмо с одной и той же локалью получателя.

Для регулярных транзакционных писем переводите каталоги до отправки. Так сервис отправки сможет загрузить принятый каталог и сформировать письмо, не дожидаясь новой генерации. Перевод во время выполнения пригодится, если контент нельзя подготовить заранее. Для этого варианта нужны чёткие правила обработки сбоев и доставки — о них ниже.

Отделите текст от данных получателя и доставки #

Создайте emails/locales/en.json с таким текстом:

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:

sh
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 в корне проекта:

javascript
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 перед получением результатов. О том, как разрешать конфликты, см. в разделе Как сохранить проверенные переводы.

Если обещание в исходнике изменилось, проверьте соответствующие переводы писем, прежде чем переключать сервис отправки на новую версию. В разделе Как спланировать многоязычный релиз описано, как принять это решение об отправке для разных локалей.