メールをローカライズする

件名、プリヘッダー、本文をまとめて翻訳し、受信者のロケールとテンプレートの値を使って、メッセージ全体をレンダリングします。

メールの体験は、読者が開く前から始まっています。件名とプリヘッダーで伝える約束は、本文、ボタン、差し込む値でも、同じ言語で果たす必要があります。これらを翻訳元でひとまとめにし、受信者の同じロケールを使ってレンダリングしてください。

繰り返し使うトランザクションメールのテンプレートは、送信前にカタログを翻訳しておきます。送信側は採用済みのカタログを読み込めば、新たな生成を待たずにメッセージをレンダリングできます。コンテンツを事前に用意できない場合は、実行時の翻訳が役立ちます。ただし、その場合は、後述するように、失敗時の対応と配信の方針を明確に定める必要があります。

文面を受信者データや配信データから切り離す #

次のような文面を含むemails/locales/en.jsonを作成します。

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

テンプレートからname、orderNumber、days、追跡用のURLを渡します。受信者データを翻訳元に含めなければ、注文ごとに同じメッセージを再生成したり、非公開の値を不必要に送信したりせずに済みます。個人データが文面に影響する場合は、翻訳サービスへの提供が許可されていることを確認してから送信してください。

既存のレンダラーに対応したプレースホルダー構文を使ってください。JSONを翻訳しても、テンプレート言語が決まるわけではありません。受信者との関係、配送に関する約束、必須の法的文言について、文脈を伝えてください。この例の「届きます」は約束を表しています。文体を変える際も、単なる可能性を示す表現に変えてはいけません。

カタログを翻訳する #

プロジェクトのルートで、現行の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

対象の組織とローカライゼーションエンジンを関連付けます。初回のバックフィルでemails/locales/es.jsonが生成されます。初回に通常のプッシュを行うだけでは、不足している翻訳先を翻訳せず、ベースラインだけを保存する場合があります。処理が実際に完了するまで待ち、翻訳結果を使う前に、件名、プリヘッダー、本文、プレースホルダー名を確認してください。

React Emailでは、カタログの文字列を読み込んで既存のコンポーネントに渡します。MJMLでは、HTMLにコンパイルする前に、プロジェクトのテンプレート層で文面を差し替えます。CLIは.mjmlファイルを読み取りません。どちらの場合も、レイアウト、エスケープ、リンクの処理は引き続きレンダラーが担います。

通常のHTMLテンプレートを翻訳する #

テンプレートが通常のHTMLファイルであれば、CLIで直接翻訳できます。emails/en/*.htmlのように、パスにソースロケールを含むパターンを追加すると、翻訳先ごとにemails/es/order-shipped.htmlのような個別のファイルが作られます。HTML形式では、ソースのコピーに翻訳済みテキストと対応対象の属性を反映します。リンクや変更対象外のマークアップは元の記述を維持し、{{...}}のテンプレートトークンを保護します。

送信前にローカライズ済みのメッセージ全体をレンダリングする #

アプリケーションの既存のプレビューレンダラーを使い、ソースと翻訳先の両方に同じ安全な値を渡します。最小限のNodeテスト用スクリプトでも、メールを送信せずにプレーンテキスト版を検証できます。次のスクリプトを、プロジェクトのルートに一時的なpreview-email.mjsとして保存します。

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

node preview-email.mjs enとnode preview-email.mjs esを実行し、保存された2つのプレビューを比較します。このテスト用スクリプトが対応するのは、単純な名前付きプレースホルダーのみです。ICU、複数形の選択、HTMLのエスケープ、メール配信は実装していません。これらの処理には、本番用のテンプレートレンダラーを使ってください。テンプレートが書式設定済みの値を想定している場合は、メッセージに渡す前に、受信者のロケールに合わせて日付と数値の書式を整えます。

長い値や空の値でも、HTML版とプレーンテキスト版をレンダリングしてください。プリヘッダーが意図した位置に表示されること、ボタンから許可された追跡用URLに移動できること、法的な識別情報や配信停止の動作が維持されていることを確認します。対応するメールクライアントでの表示、モバイルでの表示の切り詰め、長いラベル、必要に応じて右から左へのレイアウトも確認してください。件名の長さに関する推奨事項だけでは、実際のクライアントでの表示確認に代えることはできません。

コンテンツに実行時の翻訳が必要な場合 #

認証情報の管理と翻訳の呼び出しは、サーバー側で行います。メッセージの各フィールドをインラインのJSONドキュメントとして送信してジョブを開始し、メールをレンダリングする前に、完成した翻訳結果をダウンロードします。送信側が翻訳と、設定されている場合はレビューの完了を待てるよう、配信に先立ってこの処理をキューに入れてください。

リクエストのソースロケールとターゲットロケール、コンテンツのリビジョン、ローカライゼーションエンジンの設定を記録します。リクエストの拒否と、受け付け後の処理の失敗は分けて扱ってください。レンダリング前に、必須の件名・本文フィールドと、プレースホルダーの互換性を検証します。選択したワークフローがレビュー待ちになる場合は、送信処理もその状態に従う必要があります。

翻訳が失敗した場合や保留のままの場合に、配信をどう扱うか決めておきます。後で再試行する、レビュー済みの代替文面を使う、送信を見合わせる、といった対応があります。検証が済んだら、採用済みのコンテンツを既存のメールサービスに渡して送信します。

承認済みの文面をテンプレートのリビジョンと一緒に管理する #

その後ソースを変更した場合は、lingo push --waitを使い、レンダリング結果を再度比較します。カタログ、テンプレート、採用済みの翻訳、CLIのLockfileはまとめて管理してください。更新前には、既存の修正を保存します。送信後に行われた翻訳先の編集を検出するには、--waitを省略し、取得前にlingo pull --dry-runを確認してください。競合への対処については、レビュー済みの翻訳を保持するを参照してください。

ソースで伝える約束が変わった場合は、送信側をそのリビジョンに切り替える前に、対応する翻訳先のメッセージをレビューしてください。多言語リリースを計画するでは、複数のロケールにわたる配信判断について説明しています。