仕組み
@k8ordo/i18nがロケールの読み取りをいつ、どこで行うかと、保証することとしないことが分かります。
このページの内容
ロケールを読む場所
server locales.run('en', fn) → AsyncLocalStorage
paramsSchema accepts 'en' → AsyncLocalStorage
home() → reads the storage → 'Home'
browser location.pathname '/en/ui' → first segment 'en'
home() → reads the URL → 'Home'文言はロケールを引数やプロバイダから受け取らず、呼ばれたときに自分で読みます。読む場所はサーバーとブラウザで違います。どちらで動いているかは、モジュールを読み込んだ時点でdocumentが定義されているかで1度だけ決まります。
サーバー
サーバーでは、runに渡したロケールとparamsSchemaが受け付けたロケールをAsyncLocalStorageに置きます。同時に描画しているリクエストがいくつあっても、ロケールは混ざりません。AsyncLocalStorageはprocess.getBuiltinModuleで取り出し、node:async_hooksはimportしません。そのため、同じビルドをブラウザでもそのまま読み込めます。
RSCの環境と、Client ComponentをHTMLにするSSRの環境は、同じプロセスの中の別のモジュールグラフです。両方が同じロケールを読めるように、ストレージはglobalThisに置きます。
runは、fnとそこから始まる処理だけにロケールを設定します。paramsSchemaは、検証を呼んだ非同期コンテキストの残り全体に設定します。どの描画がそのコンテキストで動くかは、スキーマを走らせる側が決めます。@k8ordo/frameworkがスキーマを走らせる順番は、@k8ordo/frameworkのパラメータを見てください。
ブラウザ
ブラウザでは、location.pathnameからViteのbaseを除いた最初の区間を、文言を呼ぶたびに読みます。
集合を定義するモジュールがブラウザでまだ評価されていない間は、URLの区間がロケールかどうか分かりません。その間は、呼ばれた文言が文を持たない区間をロケールではないとみなし、最初に書いた文を返します。これで/fr/…の404ページはエラーになりません。
集合の登録
defineLocalesは集合を返すほかに、既定のロケールとisをglobalThisに登録します。messageは集合を受け取らないので、ここから既定のロケールと、区間がロケールかどうかを判定するisを読みます。
登録は、後から定義した集合で上書きされます。開発サーバーがロケールを足したi18n.tsを評価し直したとき、次に呼ばれる文言が新しい集合を読めるようにするためです。
落とし穴
テストや補助関数の中で別の集合を定義すると、それ以降のすべての文言がその集合を読みます。直し方はテストを見てください。
文言とバンドル
src/components/save-button.tsx'use client';
import { save } from '../messages/form';
export function SaveButton() {
return <button type="submit">{save()}</button>;
ブラウザのバンドルに入るのはこの文言だけ
}messageが返すのは、受け取った文を持つ関数だけです。宣言の時点では、どこにも登録せず何も確かめません。そのため、どこからも呼ばれない文言は使われないコードとしてバンドラが取り除けます。
ブラウザのバンドルに入るのは、'use client'のモジュールとそのimport先が名前で参照した文言だけです。入る文言は、すべてのロケールの文を持ちます。Server Componentだけが描画する文は、どのモジュールで宣言されていてもバンドルに入りません。
使われない文言を取り除けるように、次の3つも決めています。
- 文言は1つの辞書オブジェクトにせず、1つずつexportします。辞書は丸ごと残るか丸ごと消えるかのどちらかです。
- ロケールの欠けは宣言の時点で確かめません。エラーになりうる宣言はバンドラが副作用とみなし、使われない文言を取り除けなくなります。型で検出できなかった欠けは、文言を読んだ時点で
TypeError: message: no text for "en" in ["ja"]になります。 messageはロケールの集合を引数に取りません。locales.message(…)のような集合のメソッドにすると、そのメソッドはほかの呼び出し(defineLocales)が返した関数になります。バンドラはその中を解析しないので、使われない文言が残ります。
保証すること
- 一覧に無いロケールは、
paramsSchemaが受け付けません。ブラウザでは集合が定義されたあと、URLの先頭の区間が一覧に無ければ、文言とgetLocale()は既定のロケールを使います。 runが設定したロケールは、fnとそこから始まる処理の中でだけ読まれます。同時に処理しているほかのリクエストには使われません。AsyncLocalStorageの無いサーバーのランタイムでは、paramsSchemaとrunがエラーになります。既定のロケールで描画を続けることはありません。- 文言と
getLocale()はフックではありません。Server ComponentとClient Componentのどちらでも、イベントハンドラやほかの文言の関数の中でも呼べます。 messageの宣言には副作用がありません。どこからも呼ばれない文言は、バンドラが取り除けます。- ロケールが欠けた文言は、ロケールの型が
Registerに登録されていれば型エラーになります。型を通り抜けた欠けは、文言を読んだ時点でTypeErrorになり、undefinedは返しません。 dateTimeFormatは、サーバーでもどのブラウザでも、ロケールのtimeZoneで日付を書きます。
保証しないこと
- 文言と
getLocale()は、URLの変化を購読しません。ブラウザでは、呼んだ時点のURLを読むだけです。 - 呼んで得た文字列は、あとからロケールが変わっても変わりません。モジュールのトップレベルで呼ぶと、読み込んだときのロケールで固定されます。
- サーバーでは、
paramsSchemaもrunもロケールを設定していない処理の文言は、既定のロケールの文を返します。リクエストのURLやヘッダーは読みません。 paramsSchemaは、検証を呼んだ非同期コンテキストの残りにロケールを設定します。リクエストごとにコンテキストを分けるのは、スキーマを呼ぶ側です。- Client Componentが使う文言は、すべてのロケールの文を持ってブラウザのバンドルに入ります。ロケールごとにバンドルを分けません。
dateTimeFormatを通さない日付と、今からの相対時間は、サーバーとブラウザで同じになるとは限りません。