Localização de emails

A CLI e a API de localização do Lingo.dev suportam dois modelos para a localização de emails: traduzir ficheiros de template no momento do build para publicar templates por idioma, ou traduzir conteúdo em runtime antes do envio. Em ambos os casos, tudo passa por um motor de localização configurado, com regras de glossário, voz da marca e seleção de modelo aplicadas automaticamente.

Escolha a abordagem certa#

Pré-requisitos#

Cada tradução passa por um motor de localização — a configuração que define que modelo de LLM, glossário, voz da marca e regras se aplicam. Crie um no painel da Lingo.dev e, depois, 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 email a partir de ficheiros de recursos JSON. Extraia o texto traduzível para JSON, aponte a CLI para esse ficheiro e obtenha ficheiros por idioma lado a lado com o ficheiro 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 obter os resultados da última execução de push em qualquer altura, use lingo pull. Para verificar se as traduções estão atualizadas sem escrever alterações (por exemplo, em CI), use lingo check.

Localização em runtime#

Quando o conteúdo do email é dinâmico — notificações personalizadas, resumos de conteúdo gerado pelo utilizador ou copy de marketing armazenada num CMS — traduza-o em runtime antes do envio. Isto 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#