今のロケール
ブラウザではURLの先頭の区間が、サーバーではlocales.runかparamsSchemaが設定したロケールが、今のロケールになります。getLocale()でそのタグを読み、<html lang>に書けるようになります。
このページの内容
ブラウザのロケール
ブラウザでは、location.pathnameの先頭の区間がロケールです。文言は呼ぶたびにURLを読みます。先頭の区間が集合のロケールでないときは、既定のロケールを使います。
ロケールを持つ状態が無いので、ブラウザではlocales.runを使えません。呼ぶと、locales.run: in the browser the URL is the locale — navigate insteadというエラーになります。
ロケールを変えるには、同じpathnameのまま別のロケールの区間へ移動します。移動すればページが再描画され、文言は新しいURLのロケールで読まれます。書き方は言語の切り替えを見てください。
サーバーのロケール
src/lib/welcome.tsimport { locales } from '../i18n';
import type { Locale } from '../i18n';
import { welcomeSubject } from '../messages/email';
export const subjectIn = (locale: Locale) =>
locales.run(locale, () => welcomeSubject());サーバーの文言は、今の非同期コンテキストに設定されたロケールを読みます。メールの件名やバッチ処理で文言を呼ぶときは、locales.run(locale, fn)で囲みます。fnとそこから始まる処理がそのロケールで動き、fnがasyncでもawaitをまたいでロケールが保たれます。runはfnの戻り値をそのまま返します。
locales.paramsSchemaは、{ locale }を検証するStandard Schemaです。ロケールを受け付けると、検証を呼んだ非同期コンテキストの残りにそのロケールを設定します。@k8ordo/frameworkでは、[locale]のレイアウトからexportすると、ページの描画とそのページから送ったServer Actionにロケールが設定されます。詳しくは@k8ordo/frameworkのルーティングを見てください。
どちらもロケールを設定していないときは、既定のロケールを使います。文言がリクエストのURLやヘッダーを読むことはありません。ページをサーバーで描画するときは、リクエストのURLの先頭の区間と同じロケールを設定します。違うと、Client Componentがサーバーで書いた文と、ハイドレーションでブラウザが描画する文が食い違います。
落とし穴
AsyncLocalStorageの無いランタイムでは、runとparamsSchemaがエラーになります。エラー文はlocales.run: this runtime has no AsyncLocalStorage to scope a locale toのように、呼んだ関数の名前で始まります。既定のロケールで描画を続けることはありません。
ロケールのタグ
src/components/region-name.tsximport { locales } from '../i18n';
export function RegionName({ code }: { code: string }) {
const names = new Intl.DisplayNames(locales.getLocale(), {
type: 'region',
});
return <>{names.of(code)}</>;
}ロケールのタグそのものが要るときは、locales.getLocale()を呼びます。ブラウザではURLの先頭の区間を、サーバーではrunかparamsSchemaが設定したロケールを返します。フックではないので、どこからでも呼べます。
getLocaleは、export const { getLocale } = localesのように取り出してexportできます。
メモ
getLocale()はURLの変化を購読しません。Client Componentでは、呼んだ時点のURLを読むだけです。URLの変化に合わせて再描画したいコンポーネントは、@k8ordo/routerのusePathname()を使います。詳しくは@k8ordo/routerの現在地を見てください。
<html lang>とdir
src/components/document.tsximport type { ReactNode } from 'react';
import { locales } from '../i18n';
export function Document({ children }: { children: ReactNode }) {
const locale = locales.getLocale();
return (
<html dir={locales.definitions[locale].dir} lang={locale}>
<body>{children}</body>
</html>
);
}langとdirは、サーバーが書いたHTMLの時点で正しくなければなりません。クローラーやスクリーンリーダーは、ハイドレーションを待たずに読むからです。
ロケールが設定されていない描画で使うときは、locales.delocalize(pathname).locale ?? locales.defaultでpathnameから読みます。delocalizeは先頭の区間がロケールでないときにnullを返すので、既定のロケールは呼ぶ側で補います。
Viteのbase
import { locales } from '../i18n';
// base: '/docs/', URL: '/docs/en/ui'
locales.delocalize('/en/ui');
// { locale: 'en', pathname: '/ui' }
locales.localize('/ui', 'ja');
// '/ja/ui'アプリを/docs/のようなサブパスに置くときも、ロケールはbaseより下の最初の区間です。/docs/en/uiのロケールはenです。
localizeとdelocalizeが扱うのは、baseを除いたpathnameです。移動する前に、baseを付け直します。
@k8ordo/routerのusePathname()はbaseを除いたpathnameを返し、withBaseがbaseを付け直します。詳しくは@k8ordo/routerのベースパスを見てください。