@k8ordo/i18n

今のロケール

ブラウザでは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.ts
import { 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.tsx
import { 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.tsx
import 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

ts
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のベースパスを見てください。

k8ordo

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