ウェブアプリをローカライズする
翻訳済みカタログをフレームワークのロケール選択やリソース読み込みに組み込み、画面表示を確認します。
ウェブアプリがすでにロケールファイルのメッセージを表示しているなら、その仕組みをそのまま活用しましょう。既存のライブラリでロケールの選択、メッセージの読み込み、画面表示を続けながら、Lingo.devでソースカタログを翻訳できます。アプリ全体の翻訳に進む前に、まずは一つの画面でこの一連の流れを完成させてください。
このガイドでは、各種フレームワークで使われている既存のキー付きカタログを扱います。@lingo.dev/reactでソースとコンテキストに基づくメッセージを扱う場合は、Reactクイックスタートまたは移行ガイドを参照してください。そこで抽出される識別情報は、既存のi18nextやnext-intlのカタログで使われるキーとは異なります。
一連の動作を確認するテストケースを一つ用意する #
ラベル、変数を含むメッセージ、複数形または条件分岐のあるメッセージがそろった画面を選びます。既存のライブラリを使って、ソース言語で表示してください。名前空間、変数展開の構文、検索キーはそのまま維持します。汎用のJSON翻訳では、あるライブラリのメッセージ構文を別のライブラリの構文に変換することはできません。
既存のreact-i18nextのソースがpublic/locales/en/translation.jsonにある場合は、プロジェクトのルートでCLIを初期化します。
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'public/locales/en/translation.json' --yes
lingo linkリンク済みの.lingo/config.jsonは、次のような形式になります。
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es"],
"files": [{ "pattern": "public/locales/en/translation.json" }]
}リンク時に生成された実際の組織IDとローカライゼーションエンジンIDは、そのまま使用してください。別のフレームワークでは、以下の該当セクションに記載されたソースパスに置き換えます。ソースカタログだけを選択し、翻訳先のパスをローダーに合わせてください。ロケールのセグメントがない構成では、翻訳先の明示的なパスを使用します。
不足している翻訳先ファイルを生成するには、次を実行します。
lingo push --backfill-missing --wait完了したら、生成されたカタログを確認し、画面をスペイン語で読み込みます。同じ変数の値と複数形のケースを、両言語で比較してください。以下のフレームワーク別の手順で、このファイルを実際のリクエストやビルドに組み込みます。初回は通常のプッシュだけを行い、不足している翻訳を依頼せずに基準となる状態を保存することもできます。
書き戻しの実行を待つ間は、翻訳先ファイルを変更しないでください。既存のローカル修正を競合から保護する必要がある場合は、--waitを付けずに送信し、lingo pull --dry-runを確認してから、送信に使用したチェックアウトで取得します。詳しくはレビュー済みの翻訳を保持するを参照してください。
react-i18nextを使うReact #
react-i18nextでは、既存の名前空間と検索呼び出しをそのまま使います。public/locales/en/translation.jsonにあるソースはpublic/locales/es/translation.jsonに対応します。複数の名前空間を使うアプリでは、生成されたスペイン語ファイルまで含んでしまうグロブパターンではなく、英語のソースを個別に設定してください。
i18nextのリソースローダーが、翻訳先のロケールと名前空間をリクエストするように設定します。そのうえで、既存のuseTranslation呼び出しを使ってテストケースを表示します。変数の置換と、インストール済みのi18nextのバージョンで使われる複数形キーの規則を確認してください。汎用のJSON翻訳ツールでは、あるライブラリの複数形スキーマを別のライブラリのスキーマに変換することはできません。クライアントアプリでは、画面のテキストだけでなく、リソースのネットワークリクエストも確認します。英語へのフォールバックによって、スペイン語ファイルの欠落を見落とすことがあります。
next-intlを使うNext.js App Router #
next-intlでは、一般的にmessages/en.jsonをソースとしてmessages/es.jsonを生成します。next-intlの設定で、リクエスト時にロケールを判定し、対応するメッセージを読み込むようにしてください。ロケールに対応したルートとナビゲーションも、その選択に合わせます。
翻訳先ロケールへの直接リクエストと、別のロケールからのナビゲーションの両方で、テストケースを表示します。サーバー側で描画されたコンテンツ、クライアント側のハイドレーション、ICUの変数や複数形を確認してください。メッセージファイルを翻訳するだけでは、App Routerのロケールセグメントや言語切り替え機能は追加されません。これらの画面用カタログと併せて長文ドキュメントを扱う場合は、Next.jsでMarkdocを使うを参照してください。
next-i18nextを使うNext.js Pages Router #
next-i18nextでは、既存のロケールディレクトリと名前空間に合うようにソースパターンを設定します。対象がpublic/locales/en/common.jsonとpublic/locales/en/checkout.jsonであれば、それぞれに対応するスペイン語ファイルを生成してください。messages/en.jsonを使っている場合は、それを実際に読み込むカスタムローダーを維持します。
ページで既存のサーバー側または静的なデータ読み込み処理を通じて、必要な名前空間を読み込みます。ローカライズされたページへの直接リクエストと、クライアント側のルート変更を検証してください。初期ページデータとクライアントの実行環境で、ロケールと名前空間が一致していることを確認します。ページに読み込まれなければ、ディスク上に翻訳済みファイルがあるだけでは不十分です。
vue-i18nを使うVue #
vue-i18nでは、src/locales/en.jsonやsrc/locales/es.jsonのような辞書を読み込めます。英語のソースを翻訳し、既存の国際化インスタンスにスペイン語の辞書を登録するか、動的に読み込んでください。使用するロケールは、アプリがすでにロケールを管理している箇所で設定します。
テストケースで$tまたはuseI18nの呼び出しを実行します。ネストしたキー、変数展開、インストール済みライブラリの複数形メッセージ構文を確認してください。再読み込みなしでのロケール切り替えと、ページの新規読み込みの両方をテストします。辞書をインポートしてバンドルしている場合は、翻訳済みファイルがビルドに含まれていることも確認してください。
国際化モジュールを使うNuxt #
Nuxt i18nでは、locales/en.jsonのようなソースをlocales/es.jsonに翻訳します。インストール済みのバージョンに適したモジュール設定に、ロケールとファイルを登録してください。設定した言語ディレクトリとCLIの出力パスを一致させます。
翻訳ジョブ内で別のルーティング方式を作るのではなく、プロジェクトの既存のロケール対応ルーティングに従ってください。テストケースのページで、サーバー側の描画、遅延読み込み、ローカライズされたナビゲーション、メタデータを検証します。翻訳設定に翻訳先を追加するだけでは、Nuxtのロケール一覧にそのロケールは追加されません。
SvelteとSvelteKitの辞書 #
svelte-i18nでは、src/lib/locales/en.jsonのような辞書を翻訳します。翻訳先の辞書またはその遅延ローダーを登録し、コンポーネントで必要になる前に、選択したロケールを初期化してください。
アプリの既存の翻訳ストアを通じて、テストケースを表示します。サーバーサイドレンダリングを使うアプリでは、まずサーバー側で描画する新規リクエストをテストし、次にクライアント側でのロケール変更をテストしてください。ロケールの状態がサーバーリクエストごとに分離されていることと、翻訳先の辞書の読み込みが完了することを確認します。フォールバックによる表示を、翻訳が完了した証拠としないでください。
AngularのXLIFF #
まずAngularの国際化ワークフローを使い、メッセージにマークを付けて抽出します。XLIFFハンドラーは、プレーンテキストとインラインコードを含むXLIFF 1.2および2.xに対応しています。<g>や<pc>のように対になったコードの内側のテキストは、構造を保ったまま翻訳されます。<ph>のような単独のコードは保護されます。メッセージとインラインコードの識別子を変えずに維持し、翻訳先カタログをインポートする前に、返されたプレースホルダーを確認してください。
対応している入力では、src/locale/en/messages.xlfがsrc/locale/es/messages.xlfに対応します。XLIFFでは、messages.en.xlfからmessages.es.xlfへの接尾辞置換は使いません。ロケールディレクトリ、または明示的な翻訳先テンプレートを使用してください。翻訳をAngularに戻す際は、メッセージの識別情報を維持します。
Angularのローカライズ用ビルド設定に翻訳先ファイルを登録し、翻訳先ロケールのバンドルをビルドして配信し、画面を確認します。Angularのコンパイル時ローカライズは、実行時のJSONローダーとは異なります。ブラウザのロケールを変えても、存在しないローカライズ済みバンドルがビルドされるわけではありません。バンドルを採用する前に、メッセージが網羅されているか、プレースホルダーが正しく表示されるかを確認してください。
Astro #
画面上のラベルは、src/i18n/en.jsonを対応する翻訳先ファイルに翻訳し、独自の辞書ローダーでそのファイルを選択するようにします。コンテンツコレクションでは、ロケールごとのMarkdownまたはMDXのソースを翻訳し、静的コンテンツのワークフローを使用してください。
翻訳とは別に、Astroのロケールルーティングを設定します。生成された翻訳先ルートをビルドして開き、各ロケール版をつなぐリンクと、独自のメッセージを読み込むクライアント側のアイランドを確認してください。コンテンツコレクションとアイランドの画面用辞書には、別々の入力が必要になる場合があります。
Laravel #
Laravelのローカライズでは、lang/en/messages.phpのようなPHPソースがlang/es/messages.phpに対応します。配列のキーと、実行時に使う置換名はそのまま保持してください。対応するカタログ構造の範囲を超えた実行可能コードを含むファイルを選択する前に、PHP形式のリファレンスを参照してください。
アプリの既存のミドルウェアやコントローラーの方針に従ってリクエストのロケールを設定し、Laravelの翻訳ヘルパーでメッセージを表示します。値の置換と複数形の選択を実際に試してください。対応する各ロケールのリクエストと、フォールバックするケースをテストします。翻訳済みファイルがリクエストのロケールを選ぶわけではありません。
Django #
Djangoの抽出ワークフローでlocale/en/LC_MESSAGES/django.poを作成し、そのソースPOを翻訳して、翻訳先のロケールディレクトリに配置します。gettextのメッセージ識別情報、コンテキスト、変数展開を維持してください。プロジェクトの既存のgettextビルド手順で、翻訳済みPOをDjangoが実際に読み込むリソースにコンパイルします。
Djangoの言語選択と言語一覧を設定します。翻訳ミドルウェアを通じてローカライズされたリクエストを検証し、単数形と複数形の呼び出しでメッセージを表示してください。ディスク上にPOファイルがあっても、コンパイル済みカタログが最新とは限りません。ファイルの要件についてはGettextを参照してください。
Rails #
Railsは、ルートキーを見て、ルートにロケールを持つYAMLを識別します。yaml-root-keyを選択し、Railsのロケール設定、ヘルパー、変数展開を確認してください。用途ごとのファイル分割、リクエストのロケール切り替え、範囲を限定した更新を含む手順全体は、Railsアプリをローカライズするで説明しています。
繰り返しの翻訳でレビューしやすい出力を得る #
画面が正しく動作したら、残りのソースカタログとローダーを追加します。承認した翻訳先ファイルは、ソースのリビジョンおよびCLIのLockfileと一緒に保持してください。その後のソース変更では、通常の差分処理にlingo push --waitを使います。位置引数でファイルパターンを指定した場合は、範囲を限定した計画処理が選択されます。
GitHub Appまたは継続的インテグレーションのレシピを使い、ソース変更を検知するトリガーと書き戻し方法を選びます。GitLab、Bitbucket、GitHub ActionsのレシピはCLIを実行するため、リポジトリへの書き戻し処理を別途用意する必要があります。出力に対してフレームワークのビルドまたはリソースの検証を実行し、その後で翻訳の意味をレビューしてください。lingo checkは、すべてのフレームワークを検証するものでも、PHP、PO、XLIFFの完全性を保証するものでもありません。
エージェントは、ローダーの調査や設定変更の提案を支援できます。ワークフローを広げる前に、エージェントによる編集にも、ソース選択、ビルド、実際の画面表示について同じ確認を行ってください。