Table of Contents

LocalePerk

継承:Perk セクション名:locale 優先度:215

概要

LocalePerkはユニットを国際化する機能を付与します。実際のローカライズは各ロケールハンドラが行います。

設定

書式-グローバル設定

全ユニットに共通な設定はグローバル設定の“system.locale”セクションに記述します。

{
    "system": {
        "locale": {
            "options": {
                "currencyName": String,
                "fallbackLocaleName": String,
                "localeName": String,
                "localeServer": Boolean|String,
            }
        }
    },
}

書式-ユニット固有設定

各ユニット固有の設定は“locale”セクションに記述します。ハンドラーによっては、独自の設定があります。それぞれのリファレンスを参照してください。

{
    "locale": {
        "options": {
            "autoLocalizeRows": Boolean,
            "currencyName": String,
            "fallbackLocaleName": String,
            "localeName": String,
            "localeServer": Boolean|String,
        },
        "handlers": {
            <handlerName>: {
                "handlerClassName": String,
                "handlerOptions": {
                }
            },
            ...
        }
    }
}

autoLocalizeRows

型:Boolean デフォルト:False

Trueの場合、ローカライズ時に各行を個別にローカライズします。

currencyName

型:String

システム全体で使用する、通貨名を指定します。

fallbackLocaleName

型:String

システム全体で使用する、フォールバックロケール名を指定します。フォールバックロケール名は、ロケールのデータが見つからない時に、自動的に使用されます。

handlerClassName

型:String

ロケールハンドラのクラス名を指定します。

handlerName

型:String

ロケールハンドラの名前を指定します。この名前は重要ではありません。

localeName

型:String デフォルト:navigator.language

システム全体で使用する、ロケール名を指定します。

localeServer

型:Boolean|String デフォルト:False

ロケールサーバに接続するかを指定します。文字列を指定すると、ロケールサーバへのセレクタとみなされ、そのノードを取得して接続します。Trueの場合は、“bm-locale”ユニットに接続します。いずれの場合も、サーバーが“ready”状態になるのを待った後に、接続します。

サーバーに接続すると、現在ユニットが保持するロケール情報を、サーバーの値で上書きします。これによって、同じロケールサーバに接続する全てのユニットが、同じロケール情報を持つようになります。

イベントハンドラ

doApplySettings

設定内容に応じて、ロケールハンドラを追加します。

その後、DOMContentLoadedのタイミングでロケールサーバが存在すれば接続し、ロケール情報を共有します。

beforeApplyLocale

適用するロケールのデータをまだ持ってない場合、ユニットが保有するロケールハンドラの内、autoLoadオプションがTrueのロケールハンドラがメッセージをロードします。

doApplyLocale

localizeスキルを呼び出し、ユニットをローカライズします。またコンテンツをローカライズするために、ユニットのbasic.fillスキルを呼び出します。

afterFillRow

与えられた行のHTML要素をローカライズします。autoLocalizeRowsオプションがTrueの場合のみ、イベントハンドラがインストールされます。

ステート

active

型:Object 対象:unit

現在アクティブなロケール情報を格納するオブジェクトです。グローバル設定もしくはユニット設定の値で、初期化されます。また、ロケールサーバが存在する場合、ロケールサーバの値によって、上書きされます。

以下のキーを持ちます。

キー説明
localeNameString現在有効なロケール名です。applyスキルを使用すると、セットされます。
fallbackLocaleNameStringロケールが存在しない時に使用される、デフォルトのロケール名です。
currencyNameString通貨の名称です。

インベントリ

localizers

型:Object 対象:unit

このユニットに追加されたローカライザーを保持するオブジェクトです。

messages

型:MultiStore 対象:unit

ローカライザーによってロードされた、ロケールメッセージを保持するオブジェクトです。

スキル

localize

型:Undefined 対象:unit

各ロケールハンドラを順番に呼び出し、ステートにセットされているロケール情報で、ローカライズします。

パラメータ

パラメータ説明
rootNodeHTMLElementローカライズ対象のHTML要素です。
interpolationObjectローカライズする際に、補完に使用されるオブジェクトです。

戻り値

なし。

translate

型:String 対象:unit

引数で指定されたキーの、指定されたロケール名のメッセージを返します。指定されたロケール名のデータがない場合、ステートのfallbackLocaleNameで指定されたロケールの値を返します。

パラメータ

パラメータ説明
keyString対象となるキーです。
localeNameStringロケール名です。

戻り値

指定されたロケールのメッセージです。

スペル

addHandler

型:Undefined 対象:unit 非同期

ユニットに、handlerClassName設定で指定されたクラスをインスタンス化して、追加します。該当の設定が存在しない場合、デフォルトで“LocaleHandler”を追加します。

追加後、ロケールハンドラのinit()メソッドを呼び出し、ハンドラの初期化を行います。

パラメータ

パラメータ説明
handlerNameString対象となるキーです。
optionsObjectオプションです。ハンドラのinit()メソッドに渡されます。

戻り値

なし。

apply

型:Undefined 対象:unit 非同期

引数のオプションで渡されたロケールを適用するために、関連するイベントをトリガーします。このパーク自身も、beforeApplyLocaledoApplyLocaleイベントハンドラにて処理を行います。

オプションで指定されたロケール名は、doApplyLocaleイベントの直前で、ステートのlocale.localeNameにセットされます。

パラメータ

パラメータ説明
optionsObjectオプションです。トリガーするイベントに渡されます。以下のキーがあります。
“localeName”String適用するロケールの名前です。

戻り値

なし。

トリガーするイベント

summon

型:Undefined 対象:unit 非同期

各ロケールハンドラを順番に呼び出し、引数で指定されたロケールメッセージをロードします。

パラメータ

パラメータ説明
localeNameStringロケール名です。
optionsObjectロケールハンドラに渡される、オプションです。

戻り値

なし。