Reactのメッセージのトラブルシューティング

抽出から描画までのどの段階で、メッセージの翻訳、値、タグ、ロケールが失われているかを特定します。

実際に画面に表示されているメッセージをたどってください。ソースとコンテキストによってキーが選ばれ、最も近いプロバイダーがカタログを提供し、選ばれたテンプレートが呼び出し時の値で整形されます。通常はこれらの入力を確認すれば、生成されたキーを手作業で変更せずに問題の箇所を特定できます。

useLingoがプロバイダーの外で例外をスローする #

テストや単独のプレビューでも、フックを呼び出すコンポーネントより上にLingoProviderを配置してください。同じコンポーネントが返すプロバイダーは、そのフックより下に位置します。フックを子コンポーネントに移すか、Reactのコンテキストを介して描画しない関数でcreateLingo(locale, messages)を使用してください。

現在のプロバイダー実装ではReact 19を使用してください。パッケージのピア依存関係でより広いバージョン範囲が許容されていても、実装で使われているReact 19のコンテキスト省略記法がReact 18でも使えるわけではありません。

翻訳ではなくソーステキストが表示される #

  1. 最も近いプロバイダーに実際に渡されているlocaleとmessagesを確認してください。メッセージには、ファイルのURL、プロミス、LocaleFileではなく、ハッシュを文字列に対応付けたマップが必要です。
  2. 実際の呼び出しの内容からcomputeKey(source, context)を算出し、渡されたマップ内でそのキーを探してください。句読点、空白、コンテキストが変わると、別の識別子が生成されることがあります。
  3. 抽出結果にキーがない場合は、l.text(...)などの対応する呼び出し先でソースとコンテキストをリテラルとして指定し、抽出を再実行してください。動的に値を算出する呼び出しは、実行時に描画できても抽出できない場合があります。
  4. ソースカタログにキーがあり、翻訳先のカタログにない場合は、完成した翻訳を取得してマップを再読み込みしてください。送信しただけでは、ファイルはアプリケーションに配置されません。
  5. ファイルにキーがあるのにプロバイダーにない場合は、ローダーのパスとルートの選択を確認してください。カタログの読み込みでは、翻訳済みのJSONCからメタデータが失われた場合に必要な、ソースキーによる結合について説明しています。

値がない場合も空文字列の場合も、ソースにフォールバックします。開発時の警告では両者が区別され、同じキーとロケールの組み合わせに対する警告は重複して出力されません。本番環境ではこれらの診断情報が出力されないため、コンソールに何も表示されなくても、カタログに不足がないとは限りません。

Nextのローダーは、ファイルがない場合に{}を返しますが、JSONCの形式が不正な場合は例外をスローすることがあります。TanStackの組み込みカタログは、ファイルの欠落や読み込み、解析の失敗を{}として処理し、その結果をキャッシュします。どちらの場合も、ソースへのフォールバックによってページは読める状態に保たれますが、読み込みの問題が見えにくくなることがあります。

プレースホルダーやICU式がそのまま表示される #

呼び出しに実際に渡されるvaluesオブジェクトを確認してください。単純なプレースホルダーに対応する値がないと、{name}がそのまま表示されます。値のオブジェクト自体がない場合、ランタイムは選択されたテンプレートを整形せずに返します。

複雑なICUメッセージでは、選択された翻訳先テンプレートの構文、引数名、値の型を確認してください。解析や整形でエラーが起きると、そのテンプレートがそのまま返され、開発時には重複を除いてエラーが出力されます。そのため、英語のソースではなく、不正な翻訳が表示される場合があります。テンプレートを修正するか、不足している引数を渡してから、該当するケースを再度描画してください。

生成された型宣言は、ソースから検出された引数の不備を検出できますが、翻訳先の構文を検証したり、ICUの分岐内にネストされたすべてのプレースホルダーを検出したりするものではありません。実際の値を使い、該当する分岐の動作を確認してください。

リッチメッセージでは、tags.linkのような名前付きコールバックを使います。翻訳内のタグ名と完全に一致させ、リンク先はコールバック内に保持してください。認識されない対のタグ、自己終了タグ、対応する終了タグのない開始タグは、そのままテキストとして残ります。

ネストする要素には、それぞれ異なる名前を使ってください。同じ名前を繰り返すネスト構造は、パーサーでサポートされていません。リッチメッセージが対応しているのは単純なプレースホルダーで、ICU構文全体には対応していません。ICU構文を扱う場合は、テキスト構文ヘルパーを使ってください。対応する形式はリッチテキストで確認できます。

URLが変わっても言語が変わらない #

ロケールとカタログは同時に置き換えてください。ロケールだけを更新すると、フランス語のテキストがスペイン語の規則で整形されることがあります。ネストされたプロバイダーも確認してください。異なるロケールを持つ子プロバイダーは独立しており、親のカタログを継承しません。

選択したアダプターの切り替え方式に従ってください。Next Pagesでは、ルーターによる画面遷移とロケールのクッキーを使います。TanStackでは、通常のアンカーを使うことで、新しいリクエストで新しいカタログを読み込めるようにしています。

ハイドレーション中にテキスト、文字方向、日付が変わる #

サーバーとクライアントの入力を比較してください。確認するのは、カタログのリビジョン、ロケール、値、タイムスタンプ、タイムゾーン、相対時刻の基準です。ドキュメントのlangとdirは、フレームワークのシェルで設定してください。基本プロバイダーはこれらを変更しません。そのうえで、サーバー描画のチェックリストを使い、初期HTMLとハイドレーション後のページをテストしてください。