@k8ordo/i18n

ロケール

アプリが扱うロケールを、defineLocalesで1か所に定義できるようになります。ロケールごとにtimeZoneとdirを書き、既定のロケールを1つ選びます。

このページの内容

ロケールの一覧

src/i18n.ts
import { defineLocales } from '@k8ordo/i18n';
import type { LocaleOf } from '@k8ordo/i18n';

export const locales = defineLocales(
  {
    ja: { timeZone: 'Asia/Tokyo', dir: 'ltr' },
    'en-US': { timeZone: 'America/New_York', dir: 'ltr' },
    ar: { timeZone: 'Africa/Cairo', dir: 'rtl' },
  },
  { default: 'en-US' },
既定のロケール
);

export type Locale = LocaleOf<typeof locales>;

declare module '@k8ordo/i18n' {
  interface Register {
    locale: Locale;
タグの和集合を`Register`に登録する
  }
}

defineLocalesには、ロケールのタグをキーにしたオブジェクトを渡します。タグはBCP 47で書きます。書いた綴りがそのままURLの区間になり、en-USなら/en-US/…です。

キーはリテラル型のまま推論されるので、as constは要りません。LocaleOf<typeof locales>はタグの和集合の型です。

@k8ordo/frameworkのアプリでは、このlocalesのexportからフレームワークがRegisterを生成するので、宣言は書きません。詳しくは@k8ordo/frameworkのルーティングを見てください。

警告

落とし穴

defineLocalesはアプリで1回だけ呼びます。2回呼ぶと、後から定義した一覧で前の一覧が置き換わります。1つのモジュールで定義してexportし、ほかの場所ではimportしてください。

既定のロケール

ts
locales.default; // 'en-US'

既定のロケールは、第2引数のdefaultで選びます。省くと先頭に書いたロケールになり、locales.defaultの型はタグの和集合になります。

既定のロケールは、次のときに使われます。

  • ブラウザで、URLの先頭の区間がロケールでないとき
  • 言語の選択でどのロケールも一致しなかったとき
  • サーバーで、runもparamsSchemaもロケールを設定していないとき

タイムゾーン

timeZoneは、そのロケールの日付を表示するIANAのタイムゾーンです。日付の書き方は日付と数値の書式を見てください。

実行環境のタイムゾーンは、サーバーではサーバーの設定、ブラウザでは訪問者の設定に従います。これに任せると、サーバーが書いたHTMLとハイドレーション時の描画とで時刻が食い違います。ロケールごとに書いておけば、サーバーとブラウザが同じタイムゾーンで日付を書きます。

タイムゾーンは、サイトの内容に合わせて選びます。東京のイベントのサイトなら、英語のページでもAsia/Tokyoでかまいません。

文字の向き

ts
locales.definitions.ar;
// { timeZone: 'Africa/Cairo', dir: 'rtl' }

dirは、そのロケールの文字の向きで、ltrかrtlを書きます。Intl.LocaleのgetTextInfo()はまだすべてのブラウザでは使えないので、タグから自動では求めません。

<html>には、今のロケールのdirを書きます。書き方は今のロケールを見てください。

拒まれる定義

ts
defineLocales({ ja: { timeZone: 'Asia/Tokio', dir: 'ltr' } });
// TypeError: defineLocales: the timeZone of "ja", "Asia/Tokio", is not a time zone

定義に誤りがあると、defineLocalesを呼んだ時点でTypeErrorになります。エラー文はどれもdefineLocales:で始まります。

  • ロケールが1つも無い:no locale is defined
  • 一覧に無いdefault:the default "fr" is not in ["ja","en"]
  • BCP 47ではないタグ:"en_US" is not a BCP 47 language tag
  • 実行環境が知らないタイムゾーン:the timeZone of "ja", "Asia/Tokio", is not a time zone
  • ltrとrtl以外のdir:the dir of "ja", "auto", is neither "ltr" nor "rtl"

一覧に無いdefault、欠けたtimeZone、ltrとrtl以外のdirは型エラーにもなります。BCP 47ではないタグと実行環境が知らないタイムゾーンは型では見つからず、この検査だけが見つけます。

定義が返すもの

defineLocalesが返す値には、一覧と、一覧から作った関数がまとまっています。使う場所では、このlocalesをimportします。

  • all:書いた順に並んだタグの配列
  • definitions:ロケールごとの{ timeZone, dir }を持つ、渡したオブジェクトそのもの
  • default:既定のロケール
  • is(value):一覧に含まれるかを確かめる型ガード(大文字と小文字を区別)
  • negotiateとnegotiateRequest:訪問者の希望からロケールを選ぶ関数。詳しくは最初の言語を見てください。
  • localizeとdelocalize:pathnameにロケールの区間を付け外しする関数。詳しくは言語の切り替えを見てください。
  • paramsSchemaとrun、getLocale:今のロケールを設定して読むためのもの。詳しくは今のロケールを見てください。
  • @k8ordo/frameworkのstaticモードでは、src/routes/[locale]/paths.tsでallを返します。書き方はパラメータを見てください。
  • dateTimeFormatなど5つ:今のロケールで作ったIntlのフォーマッタ。詳しくは日付と数値の書式を見てください。

引数と戻り値の型はAPIを見てください。

k8ordo

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