トラブルシューティング
よくある症状の原因と直し方です。エラー文で探すときは、ページの中を検索してください。
このページの内容
no text for "en"
原因
文言に、そのロケールの文がありません。ロケールの型がRegisterに登録される前に書いた文言や、asで型を通した文言、JavaScriptで書いた文言で起こります。
直し方
エラー文に、欠けているロケールと文言が持つロケールが出ています。欠けているロケールの文を足します。ロケールの型がRegisterに登録されていれば、宣言の時点で型エラーになります。
型エラーにならない文の不足
原因
Registerにロケールの型が登録されていません。登録されるまでRegisteredLocaleはstringなので、どのロケールの組み合わせでも通ります。
直し方
ロケールの一覧を定義するモジュールに、declare module '@k8ordo/i18n'でRegisterを書きます。そのモジュールがTypeScriptのプロジェクトに含まれているかも確かめます。@k8ordo/frameworkのアプリではRegisterが生成されます。生成される条件は@k8ordo/frameworkのルーティングを見てください。
言語を切り替えても変わらない文言
原因
モジュールのトップレベルで文言を呼び、文字列にしています。文言は呼ばれた時点のロケールを読むので、モジュールを読み込んだときのロケールで固定されます。
直し方
文言はMessageのまま持ち、描画するコンポーネントの中で呼びます。
サーバーとブラウザで食い違う日付
原因
timeZoneを指定しないnew Intl.DateTimeFormatは、実行環境のタイムゾーンで日付を整形します。サーバーとブラウザのタイムゾーンが違うと、日付がずれてハイドレーションで食い違います。
直し方
locales.dateTimeFormatで整形します。ロケールのtimeZoneを使うので、サーバーとブラウザで同じ日付になります。訪問者のタイムゾーンで見せたいものは、ブラウザだけで描画する部分に置きます。
既定のロケールで描画されるページ
原因
サーバーで、runもparamsSchemaもロケールを設定していません。サーバーの文言はURLを読まないので、/en/…でも既定のロケールで描画されます。
直し方
文言を呼ぶ処理をlocales.runで囲むか、その前にparamsSchemaでロケールを検証します。@k8ordo/frameworkでは、[locale]のレイアウトからparamsSchemaをexportします。詳しくは@k8ordo/frameworkのルーティングを見てください。
no AsyncLocalStorage to scope a locale to
原因
サーバーのランタイムにprocess.getBuiltinModuleが無く、AsyncLocalStorageを取れません。ロケールを非同期コンテキストに設定できないので、既定のロケールで描画する代わりにエラーになります。
直し方
process.getBuiltinModule('node:async_hooks')を持つランタイムで動かします。Node 24にはあります。
in the browser the URL is the locale
原因
ブラウザでlocales.runを呼んでいます。jsdomやhappy-domのようにdocumentを定義するテスト環境も、ブラウザとして扱われます。
直し方
ブラウザでロケールを変えるには、そのロケールのURLへ移動します。テストではhistory.replaceStateでpathnameを変えます。書き方はテストを見てください。
英語のままの@k8ordo/uiのコンポーネント
原因
ロケールの一覧を定義するモジュールが、ブラウザで読み込まれていません。
直し方
Client Componentからlocalesをimportします。詳しくは@k8ordo/uiのコンポーネントの文言を見てください。
@k8ordo/ui: no built-in text for "fr"
原因
@k8ordo/uiに、jaとen以外の辞書を登録していません。
直し方
ロケールの一覧を定義するモジュールで、@k8ordo/ui/i18nのregisterMessages('fr', fr)を呼びます。登録の仕方は@k8ordo/uiのコンポーネントの文言を見てください。
ロケールが2つ並ぶ切り替え先のURL
原因
ロケールの区間が付いたままのpathnameをlocalizeに渡しています。localizeは、区間がすでにあるかを確かめません。
直し方
先にdelocalizeで区間を外し、そのpathnameをlocalizeに渡します。
既定の言語のままの404ページ
原因
静的なホストの404.htmlのように、1回だけ描画したHTMLをどのURLにも返しています。Server Componentが描画した文は、描画したときのロケールのまま変わりません。
直し方
訪問者のロケールで出したい文は、ハイドレーションが終わってからブラウザで描画します。@k8ordo/frameworkは404.htmlを書かれたとおりにハイドレーションし、終えたら訪問者のURLで描画し直します。そのため、Client Componentの文言は訪問者のロケールになります。詳しくは@k8ordo/frameworkのデプロイを見てください。
Client Componentに渡せない文言
原因
文言は関数で、Reactは関数をpropsとしてClient Componentへ送れません。
直し方
呼んだ結果の文字列を渡すか、Client Componentの中で文言をimportして呼びます。