ロケール
アプリが扱うロケールを、defineLocalesで1か所に定義できるようになります。ロケールごとにtimeZoneとdirを書き、既定のロケールを1つ選びます。
このページの内容
ロケールの一覧
src/i18n.tsimport { 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してください。
既定のロケール
locales.default; // 'en-US'既定のロケールは、第2引数のdefaultで選びます。省くと先頭に書いたロケールになり、locales.defaultの型はタグの和集合になります。
既定のロケールは、次のときに使われます。
- ブラウザで、URLの先頭の区間がロケールでないとき
- 言語の選択でどのロケールも一致しなかったとき
- サーバーで、
runもparamsSchemaもロケールを設定していないとき
タイムゾーン
timeZoneは、そのロケールの日付を表示するIANAのタイムゾーンです。日付の書き方は日付と数値の書式を見てください。
実行環境のタイムゾーンは、サーバーではサーバーの設定、ブラウザでは訪問者の設定に従います。これに任せると、サーバーが書いたHTMLとハイドレーション時の描画とで時刻が食い違います。ロケールごとに書いておけば、サーバーとブラウザが同じタイムゾーンで日付を書きます。
タイムゾーンは、サイトの内容に合わせて選びます。東京のイベントのサイトなら、英語のページでもAsia/Tokyoでかまいません。
文字の向き
locales.definitions.ar;
// { timeZone: 'Africa/Cairo', dir: 'rtl' }dirは、そのロケールの文字の向きで、ltrかrtlを書きます。Intl.LocaleのgetTextInfo()はまだすべてのブラウザでは使えないので、タグから自動では求めません。
<html>には、今のロケールのdirを書きます。書き方は今のロケールを見てください。
拒まれる定義
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を見てください。