既存のReactメッセージを移行する

プレースホルダー、複数形の動作、採用済みの翻訳を保ちながら、小規模なReactメッセージのフィクスチャを、原文とコンテキストを明示する形式へ移行します。

既存のReactカタログには、検索に使う識別情報、変数展開のルール、複数形の動作、レビュー済みの翻訳など、これまでの判断の成果が蓄積されています。原文とコンテキストに基づくメッセージへ移行する際も、その成果を引き継ぐことが大切です。まずは一つのコンポーネント全体を変換し、採用済みの翻訳を新しい識別情報に対応付けましょう。描画結果を比較してから、移行範囲を広げます。

識別情報を変える前に従来の動作を記録する #

ラベル、変数、リンク、件数、条件に応じたメッセージを含むコンポーネントを選びます。従来のキー、原文と翻訳の文言、変数展開の構文、名前空間、プロバイダーのロケールを保存してください。値を固定し、原文の言語と一つの翻訳先言語で描画します。この結果が、移行後も維持すべき具体的な基準になります。

たとえば、既存のi18next形式の呼び出しは次のようになります。

tsx
t("account.greeting", { name });

原文カタログにはWelcome, {{name}}が含まれているかもしれません。この変数展開の構文を、新しいメッセージ仕様にそのままコピーしないでください。原文とコンテキストを明示するReactメッセージでは、名前付き変数{name}を使います。

tsx
l.text("Welcome, {name}", {
  context: "Greeting on the signed-in account page",
  values: { name },
});

ここで示した区切り文字の変更は、移行元ライブラリの設定に固有のものです。他のメッセージを変換する前に、インストール済みライブラリの設定を確認してください。変数展開の区切り文字のカスタマイズや複数形の規則によっては、異なる変更が必要です。

メソッド名だけでなくメッセージの動作を対応付ける #

値を含む通常のメッセージにはtext、名前付きコンポーネントスロットにはrich、件数に応じた形式にはplural、特定の値に対応する選択肢とotherによるフォールバックにはselectを使います。リッチな対話型メッセージでは、この四つをすべて使った完全な例を紹介しています。

従来のリッチメッセージ用コンポーネントでは、リンクをインデックスで表している場合があります。インデックスは用途の分かる名前付きスロットに置き換え、リンク先はコード内に残します。変数の名前、型、意味上の役割は維持してください。従来の複数形カタログでは接尾辞付きのキーを保存している場合がありますが、新しいランタイムは各形式から複数形メッセージを組み立てます。接尾辞付きのキーを機械的に変更するのではなく、翻訳先言語での動作を確認してください。

コンテキストには、メッセージの用途が伝わる内容を指定します。新しい識別情報は、account.greetingではなく原文の文言とコンテキストから生成されます。従来のキー、ロケール、抽出された新しいキー、構文の変換内容を記録する移行対応表を用意してください。挨拶メッセージの行には、{{name}}から{name}への変換を記録します。この対応表があれば、レビュー担当者は採用済みの文言が新しいカタログのどこに引き継がれたかを追跡し、まだ対応付けられていないメッセージも確認できます。

小規模なカタログを慎重に抽出・インポートする #

Reactクイックスタートに従って@lingo.dev/reactをインストールし、LingoProviderを設定します。現在のプロバイダー実装にはReact 19を使ってください。ピア依存関係の対応範囲にReact 18が含まれていても、古いアプリケーションでのテストを省略できるわけではありません。コンポーネントを変換したら、インストール済みのCLIを実行します。

sh
lingo extract --src src --source-locale en

パスを上書きしていない場合は、locales/en.jsoncとlingo.d.tsを確認します。各原文メッセージとコンテキストを探し、実際に抽出されたキーを移行対応表にコピーしてください。従来のキーを残したり、独自のハッシュを作ったりすると、翻訳がランタイムの検索と結び付かなくなります。

採用済みの各翻訳を、対応付けた新しいキーの下に配置します。意味を保ちながら、プレースホルダー、リッチスロット、複数形の構文を一つずつ確認して変換してください。カタログ読み込みワークフローに従い、ハッシュをキー、翻訳文字列を値とする対応表を読み込みます。翻訳側のメタデータがない場合は、対応する原文の有効なキーを使います。まだ対応付けられていない項目は、不要と判断せず、残作業として確認できる状態にしておきます。

要求されたロケールと、そのロケールの翻訳メッセージを一緒にLingoProviderへ渡します。段階的な移行中は、新旧のプロバイダーをそれぞれの呼び出し元を囲む形で残してください。プロバイダーの仕様では、同じロケールでの統合と、異なるロケール間の分離について説明しています。入れ子になった画面を移行する際は、この二点を確認してください。

メッセージの欠落や形式不正を検証する #

移行前と同じ値でフィクスチャを描画し、表示内容の意味、変数の配置、リンクの動作、複数形の出力、フォールバックの選択を比較します。件数がゼロ、一、それより大きい場合に加え、長い変数値や未知の選択値も検証に含めてください。

ローカルのフィクスチャから翻訳項目を一つ削除し、原文へのフォールバックを確認します。メッセージが欠落していたり空だったりしても原文が表示される場合があるため、画面が使えることだけでは、翻訳が網羅されているとは判断できません。生成された宣言を含めて抽出結果の整合性チェックとTypeScriptのチェックを実行し、その後でアプリケーションの既存の描画テストを実行してください。型で確認できるのは呼び出しの互換性であり、翻訳の品質ではありません。

リッチタグやICUメッセージの形式が不正な場合は、出力と診断情報を確認します。新しいランタイムでは、マークアップや整形されていないテンプレートがそのまま表示されることがあります。従来のランタイムを削除する前に、この動作がアプリケーションの要件を満たすか確認してください。こうした制約は、Reactのトラブルシューティングで説明しています。

エージェントの支援結果はレビューしてから使う #

既存ライブラリの調査、キーの対応表の維持、未対応パターンの特定、ソース編集とカタログのインポートの切り分けをエージェントに依頼します。提案されたソースとカタログの変更は、適用前にレビューしてください。

フィクスチャが描画チェックとネイティブチェックに合格したら、コンポーネントまたは名前空間ごとに移行範囲を広げます。すべての呼び出し元と採用済みの翻訳について移行先を検証できるまでは、両方のカタログを残してください。従来のプロバイダーと依存関係を削除するのは、それらを使うコードがなくなってからです。APIクライアントとルーターアダプターはそれぞれ別の役割を担っており、メッセージのランタイムを変更しても、それらの代わりにはなりません。