Localize emails

Translate the subject, preheader, and body together, then render a complete message with the recipient's locale and template values.

An email starts before the reader opens it. Its subject and preheader make a promise that the body, button, and substituted values need to fulfill in the same language. Keep those pieces together in the translation source, then render them with the same recipient locale.

For recurring transactional templates, translate catalogs before sending. The sender can load an accepted catalog and render the message without waiting for new generation. Runtime translation is useful when the content cannot be prepared in advance; that alternative needs an explicit failure and delivery policy, covered below.

Separate wording from recipient and delivery data #

Create emails/locales/en.json with copy such as:

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."
}

The template supplies name, orderNumber, days, and the tracking URL. Keeping recipient data out of the translation source avoids regenerating the same message for every order and sending private values unnecessarily. If personal data affects wording, confirm it is authorized for the translation service before submitting it.

Use placeholder syntax compatible with the existing renderer. JSON translation does not choose a template language. Supply context for the recipient relationship, delivery promise, and required legal wording. In this example, “will arrive” expresses a promise that must not become a mere possibility through a stylistic change.

Translate the catalog #

From the project root, initialize the current 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

Link the intended organization and localization engine. The first backfill produces emails/locales/es.json; a plain first push can save a baseline without translating missing targets. Wait for actual completion and inspect the subject, preheader, body, and placeholder names before using the target.

For React Email, load catalog strings and pass them into the existing components. For MJML, substitute copy through the project's template layer before compiling HTML; the CLI does not read .mjml files. Both renderers still own layout, escaping, and links.

Translate plain HTML templates #

If your templates are plain HTML files, the CLI translates them directly. Add a pattern with the source locale in the path, such as emails/en/*.html, and each target becomes its own file, such as emails/es/order-shipped.html. The HTML format patches translated text and supported attributes into a copy of the source, leaves links and untouched markup as written, and protects {{...}} template tokens.

Render a complete local message before sending #

Use the application's existing preview renderer with the same safe values for source and target. A minimal Node fixture can also verify a plain-text version without sending email. Save this as a temporary preview-email.mjs in the project root:

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");

Run node preview-email.mjs en and node preview-email.mjs es, then compare the two saved previews. This fixture supports only simple named placeholders; it does not implement ICU, plural selection, HTML escaping, or email delivery. Use the production template renderer for those responsibilities. Format dates and numbers in the recipient's locale before passing them into messages where the template expects formatted values.

Render the HTML and plain-text alternatives with long and empty values as well. Check that the preheader is visible in the intended place, the button reaches the authorized tracking URL, and legal identifiers and unsubscribe behavior remain intact. Inspect supported clients, mobile truncation, longer labels, and right-to-left layout where required. Subject-length recommendations cannot replace viewing the actual client.

If the content needs runtime translation #

Keep credentials and translation calls on the server. Submit the message fields as an inline JSON document, start the job, and download the completed target before rendering the email. Queue this work ahead of delivery so the sender can wait for translation and any configured review.

Record the source and target locales, content revision, and localization engine configuration for the request. Handle rejection separately from work accepted and later failed. Validate required subject and body fields and placeholder compatibility before rendering. If the selected workflow waits for review, the sending process must respect that state.

Decide what delivery does when translation fails or remains pending: retry later, use a reviewed fallback, or withhold the message. After validation, pass the accepted content to your existing email service for sending.

Keep approved copy with the template revision #

For later source changes, use lingo push --wait, then repeat the rendered comparison. Keep the catalog, template, accepted targets, and CLI lockfile together. Save existing corrections before refreshing. To detect target edits made after submission, omit --wait and inspect lingo pull --dry-run before retrieval. See Preserve reviewed translations for conflict handling.

When a source promise changes, review the corresponding target messages before switching the sender to that revision. Plan a multilingual release covers that delivery decision across locales.