Localiser les e-mails
Traduisez ensemble l’objet, le pré-en-tête et le corps, puis générez un message complet dans la langue du destinataire, avec les valeurs du modèle.
Un e-mail commence avant même son ouverture. Son objet et son pré-en-tête font une promesse que le corps, le bouton et les valeurs insérées doivent tenir dans la même langue. Regroupez ces éléments dans la source de traduction, puis générez leur rendu dans la langue du destinataire.
Pour les modèles transactionnels récurrents, traduisez les catalogues avant l’envoi. Le système d’envoi peut ainsi charger un catalogue accepté et générer le message sans attendre une nouvelle génération. La traduction à l’exécution est utile lorsque le contenu ne peut pas être préparé à l’avance ; cette option nécessite une politique explicite de gestion des échecs et d’envoi, détaillée ci-dessous.
Séparer le texte des données du destinataire et de livraison #
Créez emails/locales/en.json avec un texte comme celui-ci :
{
"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."
}Le modèle fournit name, orderNumber, days et l’URL de suivi. Garder les données du destinataire hors de la source de traduction évite de régénérer le même message pour chaque commande et de transmettre inutilement des valeurs privées. Si des données personnelles influencent la formulation, vérifiez que leur transmission au service de traduction est autorisée avant de les soumettre.
Utilisez une syntaxe de variables compatible avec le moteur de rendu existant. La traduction de fichiers JSON n’impose aucun langage de modèles. Précisez le contexte : relation avec le destinataire, promesse de livraison et mentions légales requises. Dans cet exemple, « arrivera » exprime une promesse qu’un changement de style ne doit pas transformer en simple possibilité.
Traduire le catalogue #
Depuis la racine du projet, initialisez la CLI actuelle :
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 --waitAssociez l’organisation et le moteur de localisation souhaités. Le premier remplissage rétroactif produit emails/locales/es.json ; un simple premier envoi peut enregistrer un état de référence sans traduire les cibles manquantes. Attendez que le traitement soit réellement terminé, puis vérifiez l’objet, le pré-en-tête, le corps et les noms des variables avant d’utiliser la cible.
Avec React Email, chargez les chaînes du catalogue et transmettez-les aux composants existants. Avec MJML, insérez le texte via la couche de modèles du projet avant de compiler le HTML ; la CLI ne lit pas les fichiers .mjml. Dans les deux cas, le moteur de rendu reste responsable de la mise en page, de l’échappement et des liens.
Traduire des modèles HTML simples #
Si vos modèles sont de simples fichiers HTML, la CLI les traduit directement. Ajoutez un motif dont le chemin contient la langue source, par exemple emails/en/*.html : chaque cible devient alors un fichier distinct, comme emails/es/order-shipped.html. Le format HTML insère le texte traduit et les attributs pris en charge dans une copie de la source, conserve tels quels les liens et le balisage non modifié, et protège les jetons de modèle {{...}}.
Générer un message localisé complet avant l’envoi #
Utilisez le moteur de rendu des aperçus déjà présent dans l’application, avec les mêmes valeurs sûres pour la source et la cible. Un script de test Node minimal permet aussi de vérifier une version en texte brut sans envoyer d’e-mail. Enregistrez-le dans un fichier temporaire preview-email.mjs à la racine du projet :
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");Exécutez node preview-email.mjs en et node preview-email.mjs es, puis comparez les deux aperçus enregistrés. Ce script de test ne prend en charge que les variables nommées simples ; il ne gère ni ICU, ni la sélection des formes plurielles, ni l’échappement HTML, ni l’envoi d’e-mails. Confiez ces tâches au moteur de rendu des modèles utilisé en production. Formatez les dates et les nombres selon la langue du destinataire avant de les transmettre aux messages dont le modèle attend des valeurs formatées.
Générez également les versions HTML et texte brut avec des valeurs longues et des valeurs vides. Vérifiez que le pré-en-tête apparaît à l’endroit prévu, que le bouton mène à l’URL de suivi autorisée et que les identifiants légaux et le fonctionnement du désabonnement restent intacts. Vérifiez le rendu dans les clients de messagerie pris en charge, la troncature sur mobile, les libellés plus longs et, si nécessaire, la mise en page de droite à gauche. Les recommandations sur la longueur de l’objet ne remplacent pas une vérification dans le client de messagerie réel.
Si le contenu nécessite une traduction à l’exécution #
Gardez les identifiants et les appels de traduction côté serveur. Soumettez les champs du message sous forme de document JSON intégré, lancez la tâche, puis téléchargez la cible terminée avant de générer l’e-mail. Mettez ce travail en file d’attente en amont de l’envoi pour que le système d’envoi puisse attendre la traduction et toute relecture configurée.
Consignez, pour chaque requête, les langues source et cible, la révision du contenu et la configuration du moteur de localisation. Traitez les rejets séparément des tâches acceptées qui échouent par la suite. Validez les champs obligatoires de l’objet et du corps, ainsi que la compatibilité des variables, avant le rendu. Si le workflow sélectionné attend une relecture, le processus d’envoi doit respecter cet état.
Définissez la marche à suivre si la traduction échoue ou reste en attente : réessayer plus tard, utiliser une version de secours relue ou ne pas envoyer le message. Après validation, transmettez le contenu accepté à votre service de messagerie existant pour l’envoi.
Conserver le texte approuvé avec la révision du modèle #
Pour les modifications ultérieures de la source, utilisez lingo push --wait, puis comparez à nouveau les rendus. Conservez ensemble le catalogue, le modèle, les cibles acceptées et le Lockfile de la CLI. Enregistrez les corrections existantes avant l’actualisation. Pour détecter les modifications apportées aux cibles après la soumission, omettez --wait et inspectez lingo pull --dry-run avant la récupération. Consultez Préserver les traductions relues pour savoir comment gérer les conflits.
Lorsqu’une promesse formulée dans la source change, relisez les messages cibles correspondants avant de faire passer le système d’envoi à cette révision. Planifier une sortie multilingue aborde cette décision d’envoi pour les différentes langues.