======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": {
: {
"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"状態になるのを待った後に、接続します。
サーバーに接続すると、現在ユニットが保持する[[#locale|ロケール情報]]を、サーバーの値で上書きします。これによって、同じロケールサーバに接続する全てのユニットが、同じロケール情報を持つようになります。
=====イベントハンドラ=====
====doApplySettings====
設定内容に応じて、ロケールハンドラを追加します。
その後、DOMContentLoadedのタイミングでロケールサーバが存在すれば接続し、ロケール情報を共有します。
====beforeApplyLocale====
適用するロケールのデータをまだ持ってない場合、ユニットが保有するロケールハンドラの内、autoLoadオプションがTrueのロケールハンドラがメッセージをロードします。
====doApplyLocale====
localizeスキルを呼び出し、ユニットをローカライズします。またコンテンツをローカライズするために、ユニットのbasic.fillスキルを呼び出します。
====afterFillRow====
与えられた行のHTML要素をローカライズします。autoLocalizeRowsオプションがTrueの場合のみ、イベントハンドラがインストールされます。
=====ステート=====
====active====
''型:Object'' ''対象:unit''
現在アクティブなロケール情報を格納するオブジェクトです。[[#書式-グローバル設定|グローバル設定]]もしくは[[#書式-ユニット固有設定|ユニット設定]]の値で、初期化されます。また、ロケールサーバが存在する場合、ロケールサーバの値によって、上書きされます。
以下のキーを持ちます。
^キー^型^説明^
|localeName|String|現在有効なロケール名です。[[#apply|applyスキル]]を使用すると、セットされます。|
|fallbackLocaleName|String|ロケールが存在しない時に使用される、デフォルトのロケール名です。|
|currencyName|String|通貨の名称です。|
=====インベントリ=====
====localizers====
''型:Object'' ''対象:unit''
このユニットに追加されたローカライザーを保持するオブジェクトです。
====messages====
''型:MultiStore'' ''対象:unit''
ローカライザーによってロードされた、ロケールメッセージを保持するオブジェクトです。
=====スキル=====
====localize====
''型:Undefined'' ''対象:unit''
各ロケールハンドラを順番に呼び出し、ステートにセットされているロケール情報で、ローカライズします。
===パラメータ===
^パラメータ^型^説明^
|rootNode|HTMLElement|ローカライズ対象のHTML要素です。|
|interpolation|Object|ローカライズする際に、補完に使用されるオブジェクトです。|
===戻り値===
なし。
====translate====
''型:String'' ''対象:unit''
引数で指定されたキーの、指定されたロケール名のメッセージを返します。指定されたロケール名のデータがない場合、ステートのfallbackLocaleNameで指定されたロケールの値を返します。
===パラメータ===
^パラメータ^型^説明^
|key|String|対象となるキーです。|
|localeName|String|ロケール名です。|
===戻り値===
指定されたロケールのメッセージです。
=====スペル=====
====addHandler====
''型:Undefined'' ''対象:unit'' ''非同期''
ユニットに、[[#handlerclassname|handlerClassName設定]]で指定されたクラスをインスタンス化して、追加します。該当の設定が存在しない場合、デフォルトで"LocaleHandler"を追加します。
追加後、ロケールハンドラのinit()メソッドを呼び出し、ハンドラの初期化を行います。
===パラメータ===
^パラメータ^型^説明^
|handlerName|String|対象となるキーです。|
|options|Object|オプションです。ハンドラのinit()メソッドに渡されます。|
===戻り値===
なし。
====apply====
''型:Undefined'' ''対象:unit'' ''非同期''
引数のオプションで渡されたロケールを適用するために、関連するイベントをトリガーします。このパーク自身も、[[#beforeapplylocale|beforeApplyLocale]]と[[#doapplylocale|doApplyLocale]]イベントハンドラにて処理を行います。
オプションで指定されたロケール名は、doApplyLocaleイベントの直前で、ステートのlocale.localeNameにセットされます。
===パラメータ===
^パラメータ^型^説明^
|options|Object|オプションです。トリガーするイベントに渡されます。以下のキーがあります。|
| "localeName"|String|適用するロケールの名前です。|
===戻り値===
なし。
===トリガーするイベント===
* beforeApplyLocale
* doApplyLocale
* afterApplyLocale
====summon====
''型:Undefined'' ''対象:unit'' ''非同期''
各ロケールハンドラを順番に呼び出し、引数で指定されたロケールメッセージをロードします。
===パラメータ===
^パラメータ^型^説明^
|localeName|String|ロケール名です。|
|options|Object|ロケールハンドラに渡される、オプションです。|
===戻り値===
なし。