Localização de e-mails

A CLI e a API de localização do Lingo.dev oferecem duas abordagens para localização de e-mails: traduzir arquivos de template no build para publicar templates por idioma, ou traduzir o conteúdo em tempo de execução antes do envio. Em ambos os casos, tudo passa por um engine de localização configurado, com regras de glossário, voz da marca e seleção de modelo aplicadas automaticamente.

Escolha sua abordagem#

Pré-requisitos#

Cada tradução passa por um engine de localização — a configuração que define qual modelo de LLM, glossário, voz da marca e regras serão aplicados. Crie um no painel da Lingo.dev e, em seguida, instale e autentique a CLI:

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

A CLI requer Node 22+. Em CI, defina LINGO_API_KEY em vez de executar lingo login.

Localização em build-time#

A CLI traduz conteúdo de e-mail a partir de arquivos de recurso JSON. Extraia o conteúdo traduzível para JSON, aponte a CLI para ele e gere arquivos por idioma ao lado dos arquivos de origem.

{
  "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

Para recuperar os resultados da última execução de push a qualquer momento, use lingo pull. Para verificar se as traduções estão atualizadas sem gravar alterações (por exemplo, em CI), use lingo check.

Localização em runtime#

Quando o conteúdo do e-mail é dinâmico — como notificações personalizadas, resumos de conteúdo gerado por usuários ou texto de marketing armazenado em um CMS — traduza tudo em tempo de execução antes do envio. Isso segue o padrão descrito no guia da API de Tradução.

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

Boas práticas#

Próximos passos#