Localiza correos electrónicos
Traduce el asunto, el preencabezado y el cuerpo en conjunto; luego genera un mensaje completo con el idioma del destinatario y los valores de la plantilla.
Un correo electrónico empieza antes de que alguien lo abra. El asunto y el preencabezado hacen una promesa que el cuerpo, el botón y los valores insertados deben cumplir en el mismo idioma. Mantén todos esos elementos juntos en el contenido que envías a traducir y luego genera el mensaje en el idioma del destinatario.
Para las plantillas transaccionales que usas de forma recurrente, traduce los catálogos antes del envío. El sistema de envío puede cargar un catálogo aceptado y generar el mensaje sin esperar a que se genere contenido nuevo. La traducción en tiempo de ejecución resulta útil cuando el contenido no se puede preparar con anticipación; esta alternativa requiere una política explícita para gestionar los errores y la entrega, como se explica más adelante.
Separa el texto de los datos del destinatario y de la entrega #
Crea emails/locales/en.json con textos como estos:
{
"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."
}La plantilla proporciona name, orderNumber, days y la URL de seguimiento. Mantener los datos del destinatario fuera del contenido que envías a traducir evita generar de nuevo el mismo mensaje para cada pedido y enviar valores privados sin necesidad. Si los datos personales influyen en la redacción, confirma que esté autorizado enviarlos al servicio de traducción antes de hacerlo.
Usa una sintaxis de marcadores de posición compatible con el sistema de renderizado existente. La traducción de JSON no determina el lenguaje de plantillas. Proporciona contexto sobre la relación con el destinatario, la promesa de entrega y el texto legal requerido. En este ejemplo, “llegará” expresa una promesa que un cambio de estilo no debe convertir en una simple posibilidad.
Traduce el catálogo #
Desde la raíz del proyecto, inicializa la CLI actual:
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 --waitVincula la organización y el motor de localización que quieras usar. La primera traducción de los contenidos pendientes genera emails/locales/es.json; un primer envío sin opciones adicionales puede guardar una versión de referencia sin traducir los destinos faltantes. Espera a que el proceso haya terminado y revisa el asunto, el preencabezado, el cuerpo y los nombres de los marcadores de posición antes de usar la traducción de destino.
Con React Email, carga las cadenas del catálogo y pásalas a los componentes existentes. Con MJML, sustituye el texto mediante la capa de plantillas del proyecto antes de compilar el HTML; la CLI no lee archivos .mjml. Ambos sistemas de renderizado siguen a cargo del diseño, el escape de caracteres y los enlaces.
Traduce plantillas HTML simples #
Si tus plantillas son archivos HTML simples, la CLI los traduce directamente. Agrega un patrón que incluya el idioma de origen en la ruta, como emails/en/*.html, y cada destino tendrá su propio archivo, como emails/es/order-shipped.html. El formato HTML inserta el texto traducido y los atributos compatibles en una copia del original, conserva los enlaces y el marcado que no se modifica tal como están escritos, y protege los tokens de plantilla {{...}}.
Genera un mensaje localizado completo antes de enviarlo #
Usa el sistema de renderizado de vistas previas que ya tiene la aplicación, con los mismos valores seguros para el origen y el destino. Un archivo de prueba mínimo de Node también permite verificar una versión de texto sin formato sin enviar correos electrónicos. Guárdalo como un preview-email.mjs temporal en la raíz del proyecto:
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");Ejecuta node preview-email.mjs en y node preview-email.mjs es y luego compara las dos vistas previas guardadas. Este archivo de prueba solo admite marcadores de posición simples con nombre; no implementa ICU, selección de plurales, escape de HTML ni envío de correos electrónicos. Usa el sistema de renderizado de plantillas de producción para esas tareas. Da formato a las fechas y los números según el idioma del destinatario antes de pasarlos a mensajes cuya plantilla espere valores con formato.
Genera también las versiones en HTML y texto sin formato con valores largos y vacíos. Verifica que el preencabezado se vea en el lugar previsto, que el botón lleve a la URL de seguimiento autorizada y que los identificadores legales y el funcionamiento de la cancelación de suscripción se mantengan intactos. Revisa los clientes de correo compatibles, los recortes de texto en dispositivos móviles, las etiquetas más largas y el diseño de derecha a izquierda cuando corresponda. Las recomendaciones sobre la longitud del asunto no reemplazan la revisión en el cliente de correo real.
Si el contenido necesita traducción en tiempo de ejecución #
Mantén las credenciales y las llamadas de traducción en el servidor. Envía los campos del mensaje como un documento JSON en línea, inicia la tarea y descarga la traducción de destino completa antes de generar el correo electrónico. Pon este trabajo en cola antes de la entrega para que el sistema de envío pueda esperar a que se completen la traducción y cualquier revisión configurada.
Registra los idiomas de origen y destino, la revisión del contenido y la configuración del motor de localización para la solicitud. Gestiona por separado las solicitudes rechazadas y las tareas que se aceptan, pero fallan después. Valida los campos obligatorios de asunto y cuerpo, así como la compatibilidad de los marcadores de posición, antes de generar el mensaje. Si el flujo de trabajo seleccionado queda a la espera de una revisión, el proceso de envío debe respetar ese estado.
Define qué hará el proceso de entrega si la traducción falla o sigue pendiente: reintentar más tarde, usar una alternativa revisada o retener el mensaje. Después de validar el contenido aceptado, pásalo a tu servicio de correo electrónico existente para enviarlo.
Conserva el texto aprobado junto con la revisión de la plantilla #
Cuando haya cambios posteriores en el contenido de origen, usa lingo push --wait y repite la comparación de los mensajes generados. Mantén juntos el catálogo, la plantilla, las traducciones de destino aceptadas y el Lockfile de la CLI. Guarda las correcciones existentes antes de actualizar. Para detectar cambios en las traducciones de destino realizados después del envío, omite --wait y revisa lingo pull --dry-run antes de recuperarlas. Consulta Conserva las traducciones revisadas para saber cómo gestionar los conflictos.
Cuando cambie una promesa en el contenido de origen, revisa los mensajes de destino correspondientes antes de configurar el sistema de envío para usar esa revisión. Planifica un lanzamiento multilingüe aborda esta decisión de entrega para los distintos idiomas.