Localizar e-mails

Traduza o assunto, o pré-cabeçalho e o corpo em conjunto e, depois, gere uma mensagem completa com o idioma do destinatário e os valores do modelo.

Um e-mail começa antes de o destinatário o abrir. O assunto e o pré-cabeçalho fazem uma promessa que o corpo, o botão e os valores inseridos têm de cumprir no mesmo idioma. Mantenha estes elementos juntos no conteúdo de origem da tradução e gere-os depois no mesmo idioma do destinatário.

Para modelos transacionais recorrentes, traduza os catálogos antes do envio. O sistema de envio pode carregar um catálogo aceite e gerar a mensagem sem esperar por uma nova geração. A tradução em tempo de execução é útil quando não é possível preparar o conteúdo antecipadamente; esta alternativa exige uma política explícita para lidar com falhas e com a entrega, descrita abaixo.

Separar o texto dos dados do destinatário e da entrega #

Crie emails/locales/en.json com texto como o seguinte:

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

O modelo fornece name, orderNumber, days e o URL de seguimento. Manter os dados do destinatário fora do conteúdo de origem da tradução evita gerar novamente a mesma mensagem para cada encomenda e enviar dados privados sem necessidade. Se os dados pessoais influenciarem a redação, confirme que a sua utilização pelo serviço de tradução está autorizada antes de os enviar.

Utilize uma sintaxe de marcadores de posição compatível com o sistema de renderização existente. A tradução de JSON não determina a linguagem dos modelos. Forneça contexto sobre a relação com o destinatário, a promessa de entrega e a redação legal obrigatória. Neste exemplo, «vai chegar» expressa uma promessa que não pode passar a ser uma mera possibilidade por uma questão de estilo.

Traduzir o catálogo #

Na raiz do projeto, inicialize a CLI atual:

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

Associe a organização e o motor de localização pretendidos. O primeiro preenchimento das traduções em falta produz emails/locales/es.json; um primeiro envio simples pode guardar uma versão de referência sem traduzir os destinos em falta. Aguarde até o processo estar efetivamente concluído e verifique o assunto, o pré-cabeçalho, o corpo e os nomes dos marcadores de posição antes de utilizar a tradução de destino.

Para React Email, carregue os textos do catálogo e passe-os aos componentes existentes. Para MJML, substitua o texto através da camada de modelos do projeto antes de compilar o HTML; a CLI não lê ficheiros .mjml. Em ambos os casos, os sistemas de renderização continuam a ser responsáveis pela disposição, pelo escape de caracteres e pelas ligações.

Traduzir modelos em HTML simples #

Se os seus modelos forem ficheiros HTML simples, a CLI traduz-os diretamente. Adicione um padrão que inclua o idioma de origem no caminho, como emails/en/*.html, e cada idioma de destino terá o seu próprio ficheiro, como emails/es/order-shipped.html. O formato HTML aplica o texto traduzido e os atributos suportados a uma cópia da origem, mantém as ligações e a marcação não alterada tal como foram escritas e protege os elementos de modelo {{...}}.

Gerar uma mensagem localizada completa antes do envio #

Utilize o sistema de pré-visualização existente na aplicação com os mesmos valores seguros para a origem e o destino. Um teste mínimo em Node também permite verificar uma versão em texto simples sem enviar e-mails. Guarde-o temporariamente como preview-email.mjs na raiz do projeto:

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

Execute node preview-email.mjs en e node preview-email.mjs es e compare as duas pré-visualizações guardadas. Este teste suporta apenas marcadores de posição simples com nome; não implementa ICU, seleção de plurais, escape de HTML nem entrega de e-mails. Utilize o sistema de renderização de modelos em produção para essas tarefas. Formate as datas e os números de acordo com o idioma do destinatário antes de os passar às mensagens cujos modelos esperam valores já formatados.

Gere também as versões em HTML e texto simples com valores longos e vazios. Verifique se o pré-cabeçalho está visível no local previsto, se o botão abre o URL de seguimento autorizado e se os identificadores legais e o funcionamento do cancelamento da subscrição se mantêm intactos. Verifique a apresentação nos clientes de e-mail suportados, o truncamento em dispositivos móveis, as etiquetas mais longas e a disposição da direita para a esquerda, quando necessária. As recomendações sobre o comprimento do assunto não substituem a visualização no cliente de e-mail real.

Se o conteúdo precisar de tradução em tempo de execução #

Mantenha as credenciais e as chamadas de tradução no servidor. Envie os campos da mensagem como um documento JSON incorporado, inicie a tarefa e transfira a tradução de destino concluída antes de gerar o e-mail. Coloque este trabalho em fila antes da entrega, para que o sistema de envio possa aguardar a tradução e qualquer revisão configurada.

Registe os idiomas de origem e de destino, a revisão do conteúdo e a configuração do motor de localização associados ao pedido. Trate as rejeições separadamente dos trabalhos aceites que falhem mais tarde. Valide os campos obrigatórios de assunto e corpo e a compatibilidade dos marcadores de posição antes de gerar a mensagem. Se o workflow selecionado ficar a aguardar revisão, o processo de envio tem de respeitar esse estado.

Defina o que fazer com a entrega quando a tradução falhar ou continuar pendente: tentar novamente mais tarde, utilizar uma alternativa revista ou não enviar a mensagem. Após a validação, passe o conteúdo aceite ao serviço de e-mail que já utiliza para efetuar o envio.

Manter o texto aprovado com a revisão do modelo #

Para alterações posteriores ao conteúdo de origem, utilize lingo push --wait e repita a comparação das versões geradas. Mantenha juntos o catálogo, o modelo, as traduções de destino aceites e o Lockfile da CLI. Guarde as correções existentes antes de atualizar. Para detetar alterações às traduções de destino feitas após o envio, omita --wait e verifique lingo pull --dry-run antes de as obter. Consulte Preservar traduções revistas para saber como lidar com conflitos.

Quando uma promessa no conteúdo de origem mudar, reveja as mensagens de destino correspondentes antes de configurar o sistema de envio para utilizar essa revisão. Planear um lançamento multilingue aborda esta decisão de entrega nos vários idiomas.