v0.21

多言語化

はじめに

dframeworkは多言語アプリケーションを構築するための軽量な多言語化システムを提供します。翻訳はロケールごとに整理されたjsonファイルとして保存されフレームワークはコントローラーとビューの両方で翻訳された文字列を取得するためのヘルパーを提供します。ロケール検出はクッキーおよびAccept-Languageヘッダーから自動的に行われアクティブなロケールはリクエストごとに変更するかユーザーのセッションに永続化できます。

翻訳の定義

ディレクトリ構成

翻訳ファイルはプロジェクトルートのlangディレクトリに保存されます。各ロケールにはロケールコードという名前の独自のサブディレクトリがあります。各ロケールディレクトリ内に、関連する翻訳キーをグループ化したjsonファイルを作成します。

1lang/
2├── en/
3│ ├── common.json
4│ ├── auth.json
5│ └── dashboard.json
6├── ja/
7│ ├── common.json
8│ ├── auth.json
9│ └── dashboard.json
10└── es/
11 ├── common.json
12 └── auth.json

翻訳ファイル

各翻訳ファイルはキーを翻訳された文字列にマッピングする標準的なjsonオブジェクトです。

1{
2 "welcome": "welcome to dframework",
3 "goodbye": "see you next time",
4 "greeting": "hello, welcome back"
5}
1{
2 "welcome": "dframeworkへようこそ",
3 "goodbye": "またお会いしましょう",
4 "greeting": "こんにちは、おかえりなさい"
5}

ネストされたキー

翻訳ファイルはネストされたオブジェクトをサポートします。ドット記法を使用してネストされたキーにアクセスします。

1{
2 "buttons": {
3 "save": "save changes",
4 "cancel": "cancel",
5 "delete": "delete permanently"
6 },
7 "messages": {
8 "success": "operation completed",
9 "error": "something went wrong"
10 }
11}
1await t(req, 'common.buttons.save');
2// "save changes"

翻訳の取得

tヘルパー

t()関数は翻訳を取得する主要な方法です。グローバルに利用可能です。ドット記法のキーで直接呼び出すかリクエストオブジェクトを明示的に渡すことができます。リクエストオブジェクトを省略した場合t()は非同期リクエストコンテキストから現在のリクエストを自動的に解決します。

1// auto resolves request from context
2const welcome = await t('common.welcome');
3const missing = await t('common.nonexistent', 'default text');
4
5// or pass request explicitly
6const welcomeExplicit = await t(req, 'common.welcome');

キーの最初のセグメントはファイル名(.json拡張子なし)であり残りのセグメントはjsonオブジェクト内のパスを形成します。

キー ファイル パス
common.welcome lang/{locale}/common.json welcome
auth.errors.invalid lang/{locale}/auth.json errors.invalid
dashboard.stats.users lang/{locale}/dashboard.json stats.users

最初のアクセス時にディスクから翻訳ファイルを読み取るためこの関数は非同期です。

ビュー内での使用

ビューテンプレートでは@t()ディレクティブを使用します。フレームワークはリクエストコンテキストから現在のロケールを自動的に解決します。

1<h1>@t('common.welcome')</h1>
2<button>@t('common.buttons.save')</button>

@t()ディレクティブは現在のリクエストオブジェクトを使用して非同期のawait t()呼び出しにコンパイルされる構文糖です(コンパイル後のテンプレートは非同期として扱われます)。手動でリクエストを渡す必要はありません。

フォールバック動作

NOTE

翻訳キーが存在せずフォールバック文字列も指定されていない場合`t()`は空のテキストではなく生のキーパスを返します。

1await t(req, 'common.missing_key');
2// returns "common.missing_key"
3
4await t(req, 'common.missing_key', 'fallback text');
5// returns "fallback text"

現在のロケールに対応する翻訳ファイル自体が存在しない場合も関数は適切にフォールバックします。

変数補間

翻訳はフレームワークのルートパラメータ規約に一致する:name構文を使用した動的パラメータプレースホルダーをサポートします。オブジェクトをt()の第3引数または@t()の第2引数として渡します。

1{
2 "greeting": "こんにちは、:nameさん!",
3 "items": ":name様は:count個のアイテムを持っています。"
4}
1await t(req, 'messages.greeting', { name: '太郎' });
2// "こんにちは、太郎さん!"
3
4await t(req, 'messages.items', { name: '山田', count: 5 });
5// "山田様は5個のアイテムを持っています。"

ビューではパラメータオブジェクトを@t()に渡します:

1<p>@t('messages.greeting', { name: '太郎' })</p>

日本語のルビ(ふりがな)サポート

dframeworkは日本語のルビ(ふりがな)注釈の組み込みサポートを提供します。漢字[かんじ]表記を使用して翻訳文字列内に直接ふりがなを定義するかグローバルのruby()ヘルパーおよび@ruby()ディレクティブを使用できます。

1{
2 "welcome": "東京[とうきょう]へようこそ、:nameさん!"
3}
1await t(req, 'messages.welcome', { name: '花子' });
2// "<ruby>東京<rt>とうきょう</rt></ruby>へようこそ、花子さん!"

またruby()を直接呼び出すかビューで@ruby()を使用することもできます:

1ruby('漢字', 'かんじ');
2// "<ruby>漢字<rt>かんじ</rt></ruby>"
3
4ruby('日本[にほん]語[ご]へようこそ');
5// "<ruby>日本<rt>にほん</rt></ruby><ruby>語<rt>ご</rt></ruby>へようこそ"
1<h1>@ruby("漢字", "かんじ")</h1>
2<p>@ruby("日本[にほん]語")</p>

ruby()とふりがな注釈付きの翻訳はどちらもビューでレンダリングされたときに安全なhtmlを出力します。

ロケールの検出

検出順序

dframeworkは以下の優先順位を使用してユーザーのロケールを自動的に検出します:

  1. localeクッキー(localeクッキーが存在し有効なロケールコード(2〜10文字の英数字)が含まれている場合、即座に使用されます)
  2. Accept-Languageヘッダー(クッキーが見つからない場合、フレームワークはAccept-Language httpヘッダーを解析し、lang/でサポートされている場合は地域ロケールコード(例: en-US、zh-CN)に一致させ、そうでない場合は基本言語コード(en、zh)にフォールバックします)
  3. デフォルトロケール(どちらのソースも有効なロケールを提供しない場合、設定されたデフォルトロケールが使用されます)

この検出はリクエスト処理中に自動的に行われます。検出されたロケールはリクエストオブジェクト上にreq.localeとして保存されます。

デフォルトロケール

デフォルトロケールはconfig/app.jsファイルのlocaleキーで設定されます。

1// config/app.js
2export default {
3 locale: 'en'
4};

デフォルトが設定されていない場合フレームワークは'en'にフォールバックします。

ロケールの設定

永続的なロケール

ユーザーのロケールを変更するにはLocale.set()関数を使用します。デフォルトではlocaleクッキーを書き込みユーザーのセッションに設定を保存することで変更が永続化されます。Locale.set()はpromiseを返しawaitできます。

1import { Locale } from 'dframework';
2
3await Locale.set('ja');

クッキーは1年間の有効期間(秒単位でmaxAge: 365 * 24 * 60 * 60)で書き込まれるためユーザーの言語設定はブラウザセッションをまたいで保持されます。クッキーはSameSite=Lax、非local環境でのsecureフラグ、およびルートパス/を使用します。

ロケール値は標準のBCP 47形式(/^[a-zA-Z]{2,8}(-[a-zA-Z0-9]{2,8})*$/)に一致する必要がありes-419、zh-Hans-CN、zh-Hant-TWなどの地域タグや数値識別子をサポートします。無効な値はエラーをスローします。

リクエスト限定のロケール

永続化せずに現在のリクエストに対してのみロケールを変更する必要がある場合は第2引数としてtrueを渡します。

1Locale.set('fr', true);

これによりリクエストの期間中req.localeが設定されますがクッキーの書き込みやセッションの更新は行われません。これは異なる言語でのコンテンツのプレビューやロケールパラメータを受け入れるapiエンドポイントに役立ちます。

ロケールの読み取り

リクエストコンテキストから現在のロケールを読み取ることができます。Localeエクスポートはロケール管理メソッドへのアクセスを提供します。

1import { Locale } from 'dframework';
2
3const currentLocale = Locale.get();

デフォルトロケールを直接読み取ることもできます。

1const defaultLocale = Locale.getDefault();

キャッシングとホットリロード

翻訳ファイルは最初の読み取り後にメモリにキャッシュされます。同じロケールとファイルの組み合わせでの以降のt()呼び出しはファイルシステムにアクセスすることなくキャッシュされた辞書を返します。

local環境ではフレームワークはロードされた各翻訳ファイルにファイルウォッチャーを設定します。翻訳ファイルを編集して保存するとその特定のファイルとロケールのキャッシュが自動的に無効化されます。次回のt()呼び出しで更新されたファイルがディスクから再読み込みされます。これによりサーバーを再起動することなく開発中に即座にフィードバックが得られます。

ファイルウォッチャーはアプリケーション終了時に自動的にクリーンアップされます。本番環境ではファイルウォッチャーは作成されずキャッシュはプロセスの存続期間中持続します。

dComponentの多言語化

すべての組み込みおよびカスタムdComponentはdComponentを介した統一的なクライアントサイド多言語化に対応しています。主要コンポーネントはネットワーク通信なしで独自の英語と日本語辞書をカプセル化して標準搭載しています。

コンポーネント固有の翻訳定義

各コンポーネントは静的ゲッターを使用して独自のデフォルト翻訳を直接カプセル化します。これにより単一責任の原則が維持され基底クラスが肥大化しません。

1class MyUploader extends dComponent {
2 static get tag() { return "my-uploader"; }
3
4 static get translations() {
5 return {
6 en: {
7 select_files: "choose files to upload",
8 selected_count: ":count files selected"
9 },
10 ja: {
11 select_files: "アップロードするファイルを選択",
12 selected_count: ":count個のファイルが選択されました"
13 }
14 };
15 }
16
17 mount() {
18 const label = this.t("select_files", "アップロードするファイルを選択");
19 const counter = this.t("selected_count", { count: 3 }, ":count件のファイルを選択中");
20 }
21}

dComponent.define()でコンポーネントを定義すると宣言された翻訳辞書がコンポーネントのタグ名に対して自動登録されます。

コンポーネント内での翻訳

任意のdComponentサブクラス内でthis.t(key, params, fallback)を使用して翻訳文字列を取得できます。翻訳キーは以下の順序で解決されます。

  1. dComponent.setTranslations()で登録されたグローバルユーザー設定
  2. クラス上で定義されたコンポーネント固有の翻訳 (static get translations)
  3. タグ名に対して登録されたコンポーネント辞書
  4. フォールバック値または生のキー文字列

キーは:name形式のパラメータ補間に対応しています。

ロケール解決の順序

各コンポーネントは以下の階層順序でアクティブなロケールを決定します。

  1. コンポーネントの明示的な属性またはプロパティ (<d-calendar locale="ja">)
  2. langまたはlocale属性を持つ最も近い親要素 (<div lang="ja"><d-file-input></div>)
  3. dComponent.setLocale()で設定されたグローバルクライアントロケール
  4. ルートhtml要素の言語属性 (document.documentElement.lang)
  5. ブラウザの言語設定
  6. デフォルトのフォールバックロケール (en)

実行時のロケール切り替え

dComponent.setLocale()を呼び出すとアクティブなロケールが更新されページのリロードなしで画面上のすべてのマウント済みコンポーネントが即座に再レンダリングされます。

1// 言語を切り替え、表示中のすべてのdComponentを即座に更新
2dComponent.setLocale("ja");

翻訳辞書の登録

外部言語パックの読み込みや既存の翻訳の上書きにはdComponent.setTranslations()を使用します。

1dComponent.setTranslations("fr", {
2 "d-file-input": {
3 placeholder: "déposez le fichier ici",
4 subtitle: "ou cliquez pour parcourir"
5 }
6});

ロケールの読み取りと静的ヘルパー

コンポーネントインスタンスの外部でも、dComponentの静的ヘルパーを使用してアクティブなロケールを取得したり、文字列を直接翻訳できます。

1// アクティブなクライアントロケールコードを取得 (例: "ja", "en-US")
2const active = dComponent.getLocale();
3
4// 文字列を直接翻訳
5const label = dComponent.t("common.save", "保存");
6const welcome = dComponent.t("welcome.user", { name: "alice" }, "こんにちは :name");