Emails Localization

The Lingo.dev CLI and localization API support two patterns for email localization: translate template files at build time to ship per-locale templates, or translate content at runtime before sending. Both run through a configured localization engine with glossary rules, brand voice, and model selection applied automatically.

Choose Your Approach#

Prerequisites#

Every translation runs through a localization engine - the configuration that determines which LLM model, glossary, brand voice, and instructions apply. Create one in the Lingo.dev dashboard, then install and authenticate the CLI:

npm install -g @lingo.dev/cli
lingo login

The CLI requires Node 22+. In CI, set LINGO_API_KEY instead of running lingo login.

Build-Time Localization#

The CLI translates email content from JSON resource files. Extract your translatable copy into JSON, point the CLI at it, and get per-locale files alongside your source.

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [{ "pattern": "emails/locales/en.json" }]
}

lingo push --backfill-missing   # first run / new locale
lingo push                      # delta on later runs

To retrieve results from the last push run at any point, use lingo pull. To verify translations are up to date without writing changes (for example in CI), use lingo check.

Runtime Localization#

When email content is dynamic - personalized notifications, user-generated content summaries, or marketing copy stored in a CMS - translate it at runtime before sending. This builds on the pattern described in the Translation API guide.

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),
  });
}

Best Practices#

Next Steps#