Lokalizace e-mailů

Přeložte předmět, preheader i tělo e-mailu společně a pak vykreslete celou zprávu v jazyce příjemce s dosazenými hodnotami šablony.

E-mail začíná působit ještě dřív, než ho čtenář otevře. Předmět a preheader dávají příslib, který musí tělo zprávy, tlačítko i dosazené hodnoty naplnit ve stejném jazyce. Tyto části proto ve zdroji pro překlad uchovávejte pohromadě a vykreslujte je se stejným nastavením jazyka příjemce.

U opakovaně používaných šablon transakčních e-mailů přeložte katalogy ještě před odesíláním. Odesílací služba pak může načíst přijatý katalog a vykreslit zprávu bez čekání na nové generování. Překlad za běhu se hodí, když obsah nelze připravit předem. Vyžaduje ale jasná pravidla pro případ selhání i pro doručování, která popisujeme níže.

Oddělte texty od údajů o příjemci a doručení #

Vytvořte emails/locales/en.json například s těmito texty:

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

Šablona doplní name, orderNumber, days a sledovací URL. Když údaje o příjemci ponecháte mimo zdroj pro překlad, nemusíte stejnou zprávu znovu generovat pro každou objednávku ani zbytečně odesílat soukromé údaje. Pokud osobní údaje ovlivňují znění textu, před odesláním ověřte, že je smíte předat překladové službě.

Používejte syntaxi zástupných symbolů, která je kompatibilní se stávajícím vykreslovacím nástrojem. Překlad JSON neurčuje, jaký šablonovací jazyk máte použít. Doplňte kontext ke vztahu s příjemcem, příslibu doručení a povinným právním formulacím. V tomto příkladu vyjadřuje „dorazí“ příslib, který se stylistickou úpravou nesmí změnit v pouhou možnost.

Přeložte katalog #

V kořenovém adresáři projektu inicializujte aktuální CLI:

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

Propojte požadovanou organizaci a lokalizační engine. První zpětné doplnění vytvoří emails/locales/es.json; samotné první odeslání může uložit výchozí stav, aniž by přeložilo chybějící cílové verze. Počkejte, až se zpracování skutečně dokončí, a před použitím cílové verze zkontrolujte předmět, preheader, tělo zprávy a názvy zástupných symbolů.

V React Email načtěte řetězce z katalogu a předejte je stávajícím komponentám. V MJML dosaďte texty přes šablonovací vrstvu projektu ještě před kompilací HTML; CLI soubory .mjml nečte. Za rozvržení, escapování a odkazy nadále odpovídají oba vykreslovací nástroje.

Přeložte šablony v prostém HTML #

Pokud máte šablony v prostých souborech HTML, CLI je přeloží přímo. Přidejte vzor se zdrojovým jazykem v cestě, například emails/en/*.html, a pro každý cílový jazyk vznikne samostatný soubor, například emails/es/order-shipped.html. Formát HTML vloží přeložený text a podporované atributy do kopie zdroje, ponechá odkazy i nezměněné značky v původní podobě a chrání šablonové tokeny {{...}}.

Před odesláním vykreslete celou lokalizovanou zprávu #

Použijte stávající nástroj aplikace pro vykreslování náhledů a pro zdrojovou i cílovou verzi zadejte stejné bezpečné hodnoty. Jednoduchý testovací skript pro Node může ověřit i prostou textovou verzi bez odesílání e-mailu. Uložte ho jako dočasný soubor preview-email.mjs do kořenového adresáře projektu:

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

Spusťte node preview-email.mjs en a node preview-email.mjs es a pak porovnejte oba uložené náhledy. Tento testovací skript podporuje pouze jednoduché pojmenované zástupné symboly; neřeší ICU, výběr tvarů množného čísla, escapování HTML ani doručování e-mailů. Tyto úlohy přenechte produkčnímu nástroji pro vykreslování šablon. Pokud šablona očekává formátované hodnoty, naformátujte datumy a čísla podle jazyka příjemce ještě před jejich předáním do zprávy.

Vykreslete HTML i prostou textovou variantu také s dlouhými a prázdnými hodnotami. Ověřte, že se preheader zobrazuje na správném místě, tlačítko vede na schválenou sledovací URL a právní identifikátory i fungování odhlášení z odběru zůstávají beze změny. Zkontrolujte zobrazení v podporovaných klientech, zkracování na mobilních zařízeních, delší popisky a tam, kde je to potřeba, i rozvržení zprava doleva. Doporučení pro délku předmětu nenahradí kontrolu přímo v e-mailovém klientovi.

Pokud obsah vyžaduje překlad za běhu #

Přihlašovací údaje i volání překladové služby ponechte na serveru. Odešlete pole zprávy jako vložený dokument JSON, spusťte úlohu a před vykreslením e-mailu stáhněte dokončenou cílovou verzi. Zařaďte tuto práci do fronty s předstihem před doručením, aby odesílací služba mohla počkat na překlad i případnou nastavenou kontrolu.

U požadavku zaznamenejte zdrojový a cílový jazyk, revizi obsahu a konfiguraci lokalizačního engine. Zamítnutí řešte odděleně od úloh, které byly přijaty, ale později selhaly. Před vykreslením ověřte povinná pole předmětu a těla zprávy i kompatibilitu zástupných symbolů. Pokud vybrané workflow čeká na kontrolu, musí odesílací proces tento stav respektovat.

Určete, jak má doručování postupovat, když překlad selže nebo zůstane nevyřízený: zkusit to později znovu, použít zkontrolovanou náhradní verzi, nebo zprávu neodeslat. Po ověření předejte přijatý obsah své stávající e-mailové službě k odeslání.

Uchovávejte schválené texty spolu s revizí šablony #

Při pozdějších změnách zdroje použijte lingo push --wait a pak znovu porovnejte vykreslené verze. Katalog, šablonu, přijaté cílové verze a soubor Lockfile pro CLI uchovávejte pohromadě. Před obnovením uložte stávající opravy. Chcete-li odhalit úpravy cílových verzí provedené po odeslání, vynechte --wait a před stažením zkontrolujte lingo pull --dry-run. Řešení konfliktů popisuje část Zachování zkontrolovaných překladů.

Když se příslib ve zdroji změní, zkontrolujte odpovídající cílové zprávy dřív, než odesílací službu přepnete na danou revizi. Část Plánování vícejazyčného vydání popisuje toto rozhodování o doručování napříč jazyky.