Lingo.dev の CLI と localization API は、メールのローカライズに 2 つのパターンをサポートしています。1 つはビルド時にテンプレートファイルを翻訳してロケールごとのテンプレートを配信する方法、もう 1 つは送信前に実行時でコンテンツを翻訳する方法です。どちらも、用語集ルール、ブランドボイス、モデル選択が自動で適用される設定済みの ローカライゼーションエンジン を通して実行されます。
アプローチを選ぶ#
| アプローチ | 最適な用途 | 仕組み |
|---|---|---|
| ビルド時（CLI） | テンプレートファイル - react-email、MJML、HTML | リポジトリ内のファイルを翻訳し、ロケールごとのテンプレートをデプロイ |
| 実行時（API） | 動的コンテンツ、ESP 側でレンダリングされるテンプレート | 送信前に ローカライゼーション API を呼び出し、翻訳済みコンテンツをメールプロバイダーに渡します |
どのアプローチを選ぶ？
メールテンプレートがファイル（HTML、MJML、または React コンポーネント）としてリポジトリ内にあるなら、ビルド時のアプローチを使います。メールコンテンツが動的に生成される場合や、メールサービスプロバイダーに保存されている場合は、実行時のアプローチを使います。
前提条件#
すべての翻訳は ローカライゼーションエンジン を通して実行されます。これは、どの LLM モデル、用語集、ブランドボイス、指示を適用するかを決める設定です。Lingo.dev ダッシュボードで作成し、API key を生成してください。
ビルド時のローカライズ#
CLI はメールテンプレートファイルを直接翻訳します。テンプレート形式に合ったバケットを設定し、CLI を実行すると、ソーステンプレートと並んでロケールごとのテンプレートファイルが生成されます。
react-email テンプレートは、HTML をレンダリングする React コンポーネントです。翻訳対象の文字列を react-i18next のような i18n ライブラリで JSON リソースファイルに切り出し、その JSON ファイルを CLI で翻訳します。
{
"$schema": "https://lingo.dev/schema/i18n.json",
"version": "1.15",
"locale": {
"source": "en",
"targets": ["es", "fr", "de", "ja"]
},
"buckets": {
"json": {
"include": ["emails/locales/[locale].json"]
}
}
}レンダリング時にロケールをメールコンポーネントに渡し、対応する JSON ファイルを読み込みます。react-email の render() 関数は、送信可能なロケール別の HTML を生成します。
翻訳の実行には次のコマンドを使います。
npx lingo.dev@latest run実行時のローカライズ#
メールコンテンツが動的な場合、たとえばパーソナライズされた通知、ユーザー生成コンテンツの要約、CMS に保存されたマーケティングコピーなどは、送信前に実行時で翻訳します。これは Translation API guide で説明しているパターンに基づいています。
async function sendLocalizedEmail(userId, templateId, content) {
const user = await db.users.findById(userId);
const response = await fetch("https://api.lingo.dev/process/localize", {
method: "POST",
headers: {
"X-API-Key": process.env.LINGODOTDEV_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
engineId: "eng_abc123",
sourceLocale: "en",
targetLocale: user.locale,
data: {
subject: content.subject,
preheader: content.preheader,
body: content.body,
},
}),
});
const { data } = await response.json();
await emailProvider.send({
to: user.email,
subject: data.subject,
html: renderTemplate(templateId, data),
});
}ベストプラクティス#
| 項目 | 推奨事項 |
|---|---|
| 件名 | 50 文字以内に収めてください。ブランド名を翻訳対象外に固定するには glossary を使います。 |
| プレビューテキスト | 本文とは分けて翻訳してください。メールクライアントでは独立して表示されます。 |
| ブランドボイス | ローカライゼーションエンジンで ロケールごとのトーン を設定してください。日本語のマーケティングメールには、ドイツ語とは異なる文体が必要です。 |
| RTL 言語 | アラビア語、ヘブライ語、ペルシャ語では、メールクライアント上でレンダリング結果をテストしてください。HTML dir="rtl" の扱いはクライアントごとに異なります。 |
| キーの固定 | 翻訳してはいけない URL、製品名、法的識別子には locked keys を使ってください。 |
