@k8ordo/i18n

仕組み

@k8ordo/i18nがロケールの読み取りをいつ、どこで行うかと、保証することとしないことが分かります。

このページの内容

ロケールを読む場所

text
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を通さない日付と、今からの相対時間は、サーバーとブラウザで同じになるとは限りません。
k8ordo

Baselineに入った機能を、制限なく使うReactのライブラリ群。