Localize e-mails
Traduza o assunto, o pré-cabeçalho e o corpo em conjunto. Depois, renderize a mensagem completa com o idioma do destinatário e os valores do modelo.
Um e-mail começa antes mesmo de ser aberto. O assunto e o pré-cabeçalho fazem uma promessa que o corpo, o botão e os valores inseridos precisam cumprir no mesmo idioma. Mantenha esses elementos juntos no conteúdo de origem da tradução e renderize todos com o mesmo idioma do destinatário.
Para modelos transacionais recorrentes, traduza os catálogos antes do envio. Assim, o sistema de envio pode carregar um catálogo aceito e renderizar 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 com antecedência; essa alternativa exige uma política explícita para falhas e entrega, detalhada abaixo.
Separe o texto dos dados do destinatário e da entrega #
Crie emails/locales/en.json com textos como:
{
"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 a URL de rastreamento. Manter os dados do destinatário fora do conteúdo de origem da tradução evita gerar a mesma mensagem novamente para cada pedido e enviar dados privados sem necessidade. Se dados pessoais influenciarem a redação, confirme se o envio deles ao serviço de tradução está autorizado antes de enviá-los.
Use uma sintaxe de placeholders compatível com o renderizador existente. Traduzir JSON não determina a linguagem de modelos a ser usada. Forneça contexto sobre a relação com o destinatário, a promessa de entrega e a redação jurídica obrigatória. Neste exemplo, “vai chegar” expressa uma promessa que não pode virar uma mera possibilidade por uma mudança de estilo.
Traduza o catálogo #
Na raiz do projeto, inicialize a CLI atual:
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 --waitVincule a organização e a engine de localização que você pretende usar. O primeiro preenchimento retroativo gera emails/locales/es.json; um primeiro envio simples pode salvar uma versão de referência sem traduzir os conteúdos de destino ausentes. Aguarde a conclusão de fato e confira o assunto, o pré-cabeçalho, o corpo e os nomes dos placeholders antes de usar a tradução de destino.
Para React Email, carregue os textos do catálogo e passe-os para os componentes existentes. Para MJML, insira os textos usando a camada de modelos do projeto antes de compilar o HTML; a CLI não lê arquivos .mjml. Nos dois casos, os renderizadores continuam responsáveis pelo layout, pelo escape de caracteres e pelos links.
Traduza modelos em HTML puro #
Se os modelos forem arquivos HTML puros, a CLI os traduz diretamente. Adicione um padrão com o idioma de origem no caminho, como emails/en/*.html, e cada destino terá seu próprio arquivo, como emails/es/order-shipped.html. O formato HTML aplica o texto traduzido e os atributos compatíveis a uma cópia do original, preserva os links e a marcação não modificada como foram escritos e protege os tokens de modelo {{...}}.
Renderize uma mensagem localizada completa antes do envio #
Use o renderizador de pré-visualização já existente no aplicativo 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. Salve esse teste como um preview-email.mjs temporário na raiz do projeto:
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 salvas. Esse teste aceita apenas placeholders simples nomeados; não implementa ICU, seleção de plural, escape de HTML nem entrega de e-mails. Use o renderizador de modelos de produção para essas tarefas. Formate datas e números conforme o idioma do destinatário antes de passá-los para mensagens em que o modelo espera valores formatados.
Renderize também as versões em HTML e em texto simples com valores longos e vazios. Verifique se o pré-cabeçalho aparece no local esperado, se o botão leva à URL de rastreamento autorizada e se os identificadores legais e o funcionamento do cancelamento de inscrição permanecem intactos. Confira a exibição nos clientes de e-mail compatíveis, os cortes de texto em dispositivos móveis, os rótulos mais longos e o layout da direita para a esquerda, quando necessário. Recomendações sobre o tamanho 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 no corpo da solicitação, inicie a tarefa e baixe a tradução de destino concluída antes de renderizar o e-mail. Coloque esse trabalho na fila antes da entrega para que o sistema de envio possa aguardar a tradução e qualquer revisão configurada.
Registre os idiomas de origem e de destino, a revisão do conteúdo e a configuração da engine de localização usados na solicitação. Trate as rejeições separadamente das tarefas aceitas que falharem depois. Valide os campos obrigatórios de assunto e corpo e a compatibilidade dos placeholders antes de renderizar. Se o workflow selecionado aguardar revisão, o processo de envio deverá respeitar esse estado.
Defina o que fazer com a entrega quando a tradução falhar ou continuar pendente: tentar novamente mais tarde, usar uma alternativa revisada ou suspender o envio da mensagem. Após a validação, encaminhe o conteúdo aceito ao serviço de e-mail que você já usa para realizar o envio.
Mantenha o texto aprovado junto à revisão do modelo #
Para alterações posteriores no conteúdo de origem, use lingo push --wait e repita a comparação das versões renderizadas. Mantenha juntos o catálogo, o modelo, as traduções de destino aceitas e o Lockfile da CLI. Salve as correções existentes antes de atualizar. Para detectar edições nas traduções de destino feitas após o envio, omita --wait e confira lingo pull --dry-run antes de baixar os arquivos. Consulte Preserve as traduções revisadas para saber como lidar com conflitos.
Quando uma promessa no conteúdo de origem mudar, revise as mensagens de destino correspondentes antes de configurar o sistema de envio para usar essa revisão. Planeje um lançamento multilíngue aborda essa decisão de entrega nos diferentes idiomas.