E-Mails lokalisieren

Übersetze Betreff, Preheader und Nachrichtentext gemeinsam und rendere anschließend eine vollständige Nachricht mit der Empfängersprache und den Vorlagenwerten.

Eine E-Mail wirkt schon, bevor sie geöffnet wird. Betreff und Preheader geben ein Versprechen, das Nachrichtentext, Button und eingesetzte Werte in derselben Sprache einlösen müssen. Halte diese Bestandteile in der Übersetzungsquelle zusammen und rendere sie anschließend in derselben Empfängersprache.

Übersetze bei wiederkehrenden Transaktionsvorlagen die Kataloge vor dem Versand. Der Versandprozess kann einen akzeptierten Katalog laden und die Nachricht rendern, ohne auf eine erneute Generierung zu warten. Eine Übersetzung zur Laufzeit ist sinnvoll, wenn sich die Inhalte nicht im Voraus vorbereiten lassen. Dafür brauchst du klare Regeln für Fehlerfälle und die Zustellung, wie weiter unten beschrieben.

Formulierungen von Empfänger- und Zustelldaten trennen #

Erstelle emails/locales/en.json mit Texten wie diesen:

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

Die Vorlage liefert name, orderNumber, days und die Tracking-URL. Halte Empfängerdaten aus der Übersetzungsquelle heraus: So muss dieselbe Nachricht nicht für jede Bestellung neu generiert werden, und private Werte werden nicht unnötig übermittelt. Falls personenbezogene Daten die Formulierung beeinflussen, stelle vor der Übermittlung sicher, dass sie für die Verarbeitung durch den Übersetzungsdienst freigegeben sind.

Verwende eine Platzhaltersyntax, die mit dem vorhandenen Renderer kompatibel ist. Die JSON-Übersetzung legt keine Vorlagensprache fest. Gib Kontext zur Beziehung zu den Empfängern, zum Zustellversprechen und zu den erforderlichen rechtlichen Formulierungen an. In diesem Beispiel ist „wird ankommen“ ein Versprechen, das durch eine stilistische Änderung nicht zu einer bloßen Möglichkeit werden darf.

Den Katalog übersetzen #

Initialisiere die aktuelle CLI im Stammverzeichnis des Projekts:

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

Verknüpfe die gewünschte Organisation und Lokalisierungs-Engine. Der erste Backfill erzeugt emails/locales/es.json; ein einfacher erster Push kann einen Ausgangsstand speichern, ohne fehlende Zielversionen zu übersetzen. Warte, bis der Vorgang tatsächlich abgeschlossen ist, und sieh dir Betreff, Preheader, Nachrichtentext und Platzhalternamen an, bevor du die Zielversion verwendest.

Lade für React Email die Katalogtexte und übergib sie an die vorhandenen Komponenten. Setze bei MJML die Texte über die Vorlagenebene des Projekts ein, bevor du das HTML kompilierst; die CLI liest keine .mjml-Dateien. Beide Renderer bleiben für Layout, Maskierung und Links zuständig.

Reine HTML-Vorlagen übersetzen #

Wenn deine Vorlagen reine HTML-Dateien sind, übersetzt die CLI sie direkt. Füge ein Muster hinzu, dessen Pfad die Ausgangssprache enthält, etwa emails/en/*.html. Für jede Zielsprache entsteht eine eigene Datei, etwa emails/es/order-shipped.html. Das HTML-Format setzt übersetzte Texte und unterstützte Attribute in eine Kopie der Quelle ein, belässt Links und nicht bearbeitetes Markup im Originalzustand und schützt {{...}}-Vorlagen-Tokens.

Vor dem Versand eine vollständige lokalisierte Nachricht rendern #

Verwende den vorhandenen Vorschau-Renderer der Anwendung mit denselben unbedenklichen Werten für Ausgangs- und Zielversion. Ein minimales Node-Testskript kann auch eine Nur-Text-Version validieren, ohne eine E-Mail zu versenden. Speichere es als temporäre Datei preview-email.mjs im Stammverzeichnis des Projekts:

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

Führe node preview-email.mjs en und node preview-email.mjs es aus und vergleiche anschließend die beiden gespeicherten Vorschauen. Dieses Testskript unterstützt nur einfache benannte Platzhalter; ICU, die Auswahl von Pluralformen, HTML-Maskierung und E-Mail-Zustellung sind nicht implementiert. Verwende dafür den Vorlagen-Renderer aus dem Produktivbetrieb. Formatiere Datumsangaben und Zahlen entsprechend der Empfängersprache, bevor du sie in Nachrichten einsetzt, deren Vorlage formatierte Werte erwartet.

Rendere die HTML- und Nur-Text-Varianten auch mit langen und leeren Werten. Stelle sicher, dass der Preheader an der vorgesehenen Stelle sichtbar ist, der Button zur autorisierten Tracking-URL führt und rechtliche Kennzeichnungen sowie die Abmeldefunktion erhalten bleiben. Sieh dir die Darstellung in unterstützten E-Mail-Clients, Kürzungen auf Mobilgeräten, längere Beschriftungen und bei Bedarf das Rechts-nach-links-Layout an. Empfehlungen zur Betrefflänge ersetzen nicht den Blick in den tatsächlichen E-Mail-Client.

Wenn Inhalte zur Laufzeit übersetzt werden müssen #

Belasse Zugangsdaten und Übersetzungsaufrufe auf dem Server. Übermittle die Nachrichtenfelder als Inline-JSON-Dokument, starte den Auftrag und lade die fertige Zielversion herunter, bevor du die E-Mail renderst. Stelle diese Arbeit vor der Zustellung in die Warteschlange, damit der Versandprozess auf die Übersetzung und eine gegebenenfalls konfigurierte Prüfung warten kann.

Erfasse für die Anfrage die Ausgangs- und Zielsprachen, die Inhaltsrevision und die Konfiguration der Lokalisierungs-Engine. Behandle Ablehnungen getrennt von Aufträgen, die zunächst angenommen werden und später fehlschlagen. Validiere vor dem Rendern die erforderlichen Betreff- und Textfelder sowie die Kompatibilität der Platzhalter. Wenn der gewählte Workflow auf eine Prüfung wartet, muss der Versandprozess diesen Zustand berücksichtigen.

Lege fest, wie die Zustellung mit fehlgeschlagenen oder noch ausstehenden Übersetzungen umgeht: später erneut versuchen, eine Ersatzversion verwenden, die eine Prüfung durchlaufen hat, oder die Nachricht zurückhalten. Übergib die akzeptierten Inhalte nach der Validierung zum Versand an deinen vorhandenen E-Mail-Dienst.

Freigegebene Texte zusammen mit der Vorlagenrevision aufbewahren #

Verwende bei späteren Änderungen an der Quelle lingo push --wait und wiederhole anschließend den Vergleich der gerenderten Versionen. Bewahre Katalog, Vorlage, akzeptierte Zielversionen und CLI-Lockfile zusammen auf. Speichere vorhandene Korrekturen vor der Aktualisierung. Um Änderungen an Zielversionen zu erkennen, die nach der Übermittlung vorgenommen wurden, lasse --wait weg und sieh dir vor dem Abruf lingo pull --dry-run an. Hinweise zum Umgang mit Konflikten findest du unter Übersetzungen nach der Prüfung beibehalten.

Wenn sich ein Versprechen im Ausgangstext ändert, führe eine Prüfung der entsprechenden Nachrichten in den Zielsprachen durch, bevor du den Versandprozess auf diese Revision umstellst. Eine mehrsprachige Veröffentlichung planen behandelt diese Entscheidung zur Zustellung über mehrere Sprachen hinweg.