AIR HTML ローカリゼーションフレームワークによる HTML コンテンツのローカライズ

ローカリゼーションフレームワークを使用するには、AIRLocalizer.js ファイルをプロジェクトにコピーします。次に、script タグを使用して、アプリケーションのメイン HTML ファイルに含めます。

<script src="AIRLocalizer.js" type="text/javascript" charset="utf-8"></script>

それ以降の JavaScript では、air.Localizer.localizer オブジェクトを呼び出すことができます。

<script> 
    var localizer = air.Localizer.localizer; 
</script>

Localizer クラスには次の静的プロパティが含まれています。

HTML ローカリゼーションフレームワークは、ローカライズされたバージョンのストリングをローカリゼーションファイルから読み取ります。ローカリゼーションファイルは、テキストファイル内で直列化された、キーベースの値のコレクションです。ローカリゼーションファイルは、バンドルと呼ばれることもあります。

アプリケーションプロジェクトディレクトリに、locale という名前のサブディレクトリを作成します（別の名前を使用することもできます。AIR HTML ローカライザ設定のカスタマイズを参照してください）。このディレクトリには、ローカリゼーションファイルが格納されます。このディレクトリはバンドルディレクトリとも呼ばれます。

アプリケーションがサポートする各ロケールについて、バンドルディレクトリのサブディレクトリを作成します。各サブディレクトリには、ロケールコードに一致する名前を付けます。例えば、フランス語用のディレクトリには「fr」、英語用のディレクトリには「en」という名前を付けます。言語と国コードを含むロケールを定義するには、アンダースコア（_）文字を使用できます。例えば、米国英語用のディレクトリには「en_us」という名前を付けます（または、「en-us」のようにアンダースコアの代わりにハイフンを使用することもできます。HTML ローカリゼーションフレームワークではどちらもサポートしています）。

locale サブディレクトリには、必要な数だけリソースファイルを追加できます。一般的には、言語ごとにローカリゼーションファイルを作成し、その言語のディレクトリにファイルを配置します。HTML ローカリゼーションフレームワークには、ファイルの内容を読み取るための getFile() メソッドが含まれています（特定のロケールのリソースの取得を参照してください）。

.properties というファイル拡張子を持つファイルは、ローカリゼーションプロパティファイルと呼ばれます。ローカリゼーションプロパティファイルを使用して、ロケールのキーと値のペアを定義できます。プロパティファイルでは、各行で 1 つのストリング値を定義します。例えば、次の例では、ストリング値 "Hello in English." を、greeting という名前のキーに対して定義しています。

greeting=Hello in English.

次のテキストを含むプロパティファイルは、6 つのキーと値のペアを定義します。

title=Sample Application 
greeting=Hello in English. 
exitMessage=Thank you for using the application. 
color1=Red 
color2=Green 
color3=Blue

この例では、英語バージョンのプロパティファイルは、en ディレクトリに格納されています。

このプロパティファイルのフランス語バージョンは fr ディレクトリに配置されています。

title=Application Example 
greeting=Bonjour en français. 
exitMessage=Merci d'avoir utilisé cette application. 
color1=Rouge 
color2=Vert 
color3=Bleu

異なる種類の情報用に複数のリソースファイルを定義できます。例えば、legal.properties ファイルに定型の法律に関するテキスト（著作権情報など）を含めることができます。このリソースは複数のアプリケーションで再利用できます。同様に、ユーザーインターフェイスの部分ごとにローカライズされたコンテンツを定義する、個別のファイルを定義することもできます。

複数の言語をサポートするには、これらのファイルで UTF-8 エンコードを使用します。

アプリケーションで AIRLocalizer.js ファイルを読み込むと、アプリケーションで定義されているロケールが調べられます。これらのロケールはバンドルディレクトリのサブディレクトリに対応します（リソースバンドルの定義を参照してください）。この利用可能なロケールの一覧をロケールチェーンと呼びます。AIRLocalizer.js ファイルは、オペレーティングシステムの設定で定義されている優先順位に基づいて、ロケールチェーンを自動的に並べ替えます（Capabilities.languages プロパティは、オペレーティングシステムのユーザーインターフェイスの言語を、優先される順序で一覧表示します）。

したがって、アプリケーションで「en」、「en_US」および「en_UK」ロケールのリソースを定義している場合、AIR HTML ローカリゼーションフレームワークではロケールチェーンが適切に並べ替えられます。「en」がプライマリロケールであるシステムでアプリケーションを起動した場合、ロケールチェーンは ["en", "en_US", "en_UK"] のように並べ替えられます。この場合、アプリケーションは最初に「en」バンドルでリソースを検索し、次に「en_US」バンドル内を検索します。

システムのプライマリロケールが「en-US」である場合は、並べ替えは ["en_US", "en", "en_UK"] のようになります。この場合、アプリケーションは最初に「en_US」バンドルでリソースを検索し、次に「en」バンドル内を検索します。

デフォルトでは、アプリケーションはロケールチェーン内の最初のロケールをデフォルトのロケールとして定義します。アプリケーションを最初に実行するときに、ユーザーにロケールを選択するよう求めることができます。選択された内容を環境設定ファイルに保存し、それ以降にアプリケーションを起動するときにはそのロケールを使用できます。

アプリケーションでは、ロケールチェーン内の任意のロケールのリソースストリングを使用できます。特定のロケールでリソースストリングが定義されていない場合、アプリケーションはロケールチェーンで定義されている他のロケールで次に一致するリソースストリングを使用します。

ロケールチェーンは、Localizer オブジェクトの setLocaleChain() メソッドを呼び出すことによってカスタマイズできます。ロケールチェーンの定義を参照してください。

アプリケーション内のエレメントで、ローカリゼーションプロパティファイル内のキー値を参照できます。例えば、次の例の title エレメントでは、local_innerHTML 属性を指定しています。ローカリゼーションフレームワークでは、この属性を使用してローカライズされた値を検索します。デフォルトでは、フレームワークは「local_」で始まる属性名を検索します。フレームワークは、「local_」に続くテキストと一致する名前を持つ属性を更新します。この場合、フレームワークは title エレメントの innerHTML 属性を設定します。innerHTML 属性は、デフォルトプロパティファイル（default.properties）の mainWindowTitle キーに定義されている値を使用します。

<title local_innerHTML="default.mainWindowTitle"/>

現在のロケールで一致する値が定義されていない場合、ローカライザフレームワークは残りのロケールチェーンを検索します。ロケールチェーン内で、次に見つかった、値が定義されているロケールが使用されます。

次の例では、p エレメントのテキスト（innerHTML 属性）で、デフォルトプロパティファイルで定義されている greeting キーの値を使用します。

<p local_innerHTML="default.greeting" />

次の例では、input エレメントの value 属性（および表示テキスト）で、デフォルトプロパティファイルで定義されている btnBlue キーの値を使用します。

<input type="button" local_value="default.btnBlue" />

現在のロケールチェーンで定義されているストリングを使用するように HTML DOM を更新するには、Localizer オブジェクトの update() メソッドを呼び出します。update() メソッドを呼び出すと、Localizer オブジェクトは DOM を解析し、ローカリゼーション（「local_...」）属性が見つかった場所で操作を適用します。

air.Localizer.localizer.update();

属性（「innerHTML」など）と、対応するローカリゼーション属性（「local_innerHTML」など）の両方の値を定義できます。この場合、ローカリゼーションフレームワークは、ロケールチェーンで一致する値が見つかった属性値のみを上書きします。例えば、次のエレメントでは、value 属性と local_value 属性の両方を定義しています。

<input type="text" value="Blue" local_value="default.btnBlue"/>

特定の DOM エレメントのみを更新することもできます。次の節の現在のロケールを使用するための DOM エレメントの更新を参照してください。

デフォルトでは、AIR HTML ローカライザは、エレメントのローカリゼーション設定を定義する属性の接頭辞として、「local_」を使用します。例えば、デフォルトの場合、local_innerHTML 属性は、エレメントの innerHTML 値のバンドルおよびリソース名を定義します。また、デフォルトでは、local_value 属性は、エレメントの value 属性で使用されるバンドルおよびリソース名を定義します。ローカライザで「local_」以外の属性接頭辞を使用するように構成できます。AIR HTML ローカライザ設定のカスタマイズを参照してください。

Localizer オブジェクトが HTML DOM を更新する場合、マークされたエレメントは、現在のロケールチェーンで定義されているストリングに基づいて属性値を使用します。HTML ローカライザで HTML DOM を更新するには、Localizer オブジェクトの update() メソッドを呼び出します。

air.Localizer.localizer.update();

指定した DOM エレメントのみを更新するには、DOM エレメントをパラメーターとして update() メソッドに渡します。update() メソッドのパラメーターは parentNode のみで、これはオプションです。指定した場合、parentNode パラメーターはローカライズする DOM エレメントを定義します。update() メソッドを呼び出して、parentNode パラメーターを指定すると、ローカリゼーション属性を指定するすべての子エレメントについてローカライズされた値が設定されます。

例えば、次のような div エレメントがあるとします。

<div id="colorsDiv"> 
    <h1 local_innerHTML="default.lblColors" ></h1> 
    <p><input type="button" local_value="default.btnBlue" /></p> 
    <p><input type="button" local_value="default.btnRed" /></p> 
    <p><input type="button" local_value="default.btnGreen" /></p> 
</div>

現在のロケールチェーンで定義されているローカライズされたストリングを使用するようにこのエレメントを更新するには、次の JavaScript コードを使用します。

var divElement = window.document.getElementById("colorsDiv"); 
air.Localizer.localizer.update(divElement);

ロケールチェーンでキーの値が見つからない場合は、ローカリゼーションフレームワークによって、属性値は「local_」属性の値に設定されます。例えば、前の例で、lblColors キーの値が（ロケールチェーン内のデフォルトプロパティファイルのいずれにも）見つからなかったとします。この場合、ローカリゼーションフレームワークは、「default.lblColors」を innerHTML 値として使用します。この値を使用することで、（開発者に対して）リソースが不足していることが示されます。

update() メソッドは、ロケールチェーン内でリソースが見つからなかった場合、resourceNotFound イベントを送出します。air.Localizer.RESOURCE_NOT_FOUND 定数は、ストリング「resourceNotFound」を定義します。このイベントには、bundleName、resourceName および locale の 3 つのプロパティがあります。bundleName プロパティは、リソースが見つからないバンドルの名前です。resourceName プロパティは、リソースが見つからないバンドルの名前です。locale プロパティは、リソースが見つからないロケールの名前です。

update() メソッドは、指定されたバンドルが見つからなかった場合、bundleNotFound イベントを送出します。air.Localizer.BUNDLE_NOT_FOUND 定数は、ストリング「bundleNotFound」を定義します。このイベントには、bundleName と locale の 2 つのプロパティがあります。bundleName プロパティは、リソースが見つからないバンドルの名前です。locale プロパティは、リソースが見つからないロケールの名前です。

update() メソッドは非同期に動作します(resourceNotFound イベントと bundleNotFound イベントを非同期に送出します）。次のコードは、resourceNotFound イベントとbundleNotFound イベントのイベントリスナーを設定します。

air.Localizer.localizer.addEventListener(air.Localizer.RESOURCE_NOT_FOUND, rnfHandler); 
air.Localizer.localizer.addEventListener(air.Localizer.BUNDLE_NOT_FOUND, rnfHandler); 
air.Localizer.localizer.update(); 
function rnfHandler(event) 
{ 
    alert(event.bundleName + ": " + event.resourceName + ":." + event.locale); 
} 
function bnfHandler(event) 
{ 
    alert(event.bundleName + ":." + event.locale); 
}

Localizer オブジェクトの setBundlesDirectory() メソッドによって、バンドルディレクトリのパスをカスタマイズできます。Localizer オブジェクトの setLocalAttributePrefix() メソッドによって、バンドルディレクトリのパスをカスタマイズし、ローカライザで使用される属性値をカスタマイズできます。

デフォルトのバンドルディレクトリは、アプリケーションディレクトリの locale サブディレクトリとして定義されています。別のディレクトリを指定するには、Localizer オブジェクトの setBundlesDirectory() メソッドを呼び出します。このメソッドは、path というパラメーターを 1 つ使用します。このパラメーターは、目的のバンドルディレクトリへのパスを示すストリングです。path パラメーターの値には、次のいずれかを指定できます。

例えば、次のコードは、バンドルディレクトリを、アプリケーション記憶域ディレクトリ（アプリケーションディレクトリではない）の languages サブディレクトリに設定します。

air.Localizer.localizer.setBundlesDirectory("languages");

有効なパスを path パラメーターとして渡します。そうしないと、このメソッドは BundlePathNotFoundError 例外をスローします。このエラーは、「BundlePathNotFoundError」をその name プロパティとして持ち、message プロパティで無効なパスを示します。

デフォルトでは、AIR HTML ローカライザは、エレメントのローカリゼーション設定を定義する属性の接頭辞として、「local_」を使用します。例えば、local_innerHTML 属性は、次の input エレメントの innerHTML 値として使用されるバンドルおよびリソース名を定義します。

<p local_innerHTML="default.greeting" />

Localizer オブジェクトの setLocalAttributePrefix() メソッドによって、「local_」以外の属性接頭辞を使用できます。この静的メソッドはパラメーターを 1 つ使用します。このパラメーターが属性接頭辞として使用されるストリングです。例えば、次のコードは、ローカリゼーションフレームワークで属性接頭辞として「loc_」を使用するように設定します。

air.Localizer.localizer.setLocalAttributePrefix("loc_");

ローカリゼーションフレームワークで使用する属性接頭辞をカスタマイズできます。デフォルト値（「local_」）が、コードで使用されている別の属性の名前と競合する場合は、接頭辞をカスタマイズできます。このメソッドを呼び出す場合は、HTML 属性として有効な文字を使用してください（例えば、値に空白文字を含めることはできません）。

HTML エレメントでのローカリゼーション属性の使用について詳しくは、ローカライズされたコンテンツによる DOM エレメントの更新を参照してください。

バンドルディレクトリおよび属性接頭辞の設定は、アプリケーションセッション間で保持されません。カスタムバンドルディレクトリまたはカスタム属性接頭辞の設定を使用する場合は、アプリケーションを開始するたびに設定してください。

デフォルトでは、AIRLocalizer.js コードを読み込むと、デフォルトのロケールチェーンが設定されます。バンドルディレクトリで使用できるロケールおよびオペレーティングシステムの言語の設定によって、このロケールチェーンが定義されます（詳しくは、ロケールチェーンの管理を参照してください）。

ロケールチェーンは、Localizer オブジェクトの静的メソッド setLocaleChain() を呼び出すことによって変更できます。例えば、ユーザーが特定の言語の環境設定を指定した場合に、このメソッドを呼び出すことができます。setLocaleChain() メソッドは chain パラメーターを使用します。このパラメーターは、["fr_FR","fr","fr_CA"] などのロケールの配列です。配列内のロケールの順序によって、フレームワークが（以降の操作で）リソースを検索する順序が決まります。チェーン内の最初のロケールでリソースが見つからない場合は、他のロケールのリソースを検索し続けます。chain 引数が指定されていない場合、配列ではない場合または空の配列である場合、この関数は失敗し、IllegalArgumentsError 例外をスローします。

Localizer オブジェクトの静的メソッド getLocaleChain() は、現在のロケールチェーンに含まれるロケールの一覧を示す配列を返します。

次のコードは、現在のロケールチェーンを読み取って、2 つのフランス語ロケールをチェーンの先頭に追加します。

var currentChain = air.Localizer.localizer.getLocaleChain(); 
newLocales = ["fr_FR", "fr"]; 
air.Localizer.localizer.setLocaleChain(newLocales.concat(currentChain));

setLocaleChain() メソッドは、ロケールチェーンを更新すると、「change」イベントを送出します。air.Localizer.LOCALE_CHANGE 定数は、ストリング「change」を定義します。このイベントには localeChain というプロパティがあります。このプロパティは、新しいロケールチェーン内のロケールコードの配列です。次のコードは、このイベントのイベントリスナーを設定します。

var currentChain = air.Localizer.localizer.getLocaleChain(); 
newLocales = ["fr_FR", "fr"]; 
localizer.addEventListener(air.Localizer.LOCALE_CHANGE, changeHandler); 
air.Localizer.localizer.setLocaleChain(newLocales.concat(currentChain)); 
function changeHandler(event) 
{ 
    alert(event.localeChain); 
}

静的プロパティ air.Localizer.ultimateFallbackLocale は、アプリケーションがユーザー設定をサポートしていない場合に使用されるロケールを表します。デフォルト値は「en」です。次のコードに示されているように、この値を別のロケールに設定できます。

air.Localizer.ultimateFallbackLocale = "fr";

bundleName

resourceName

templateArgs

locale

ローカリゼーションフレームワークでは、マークされた HTML DOM 属性を更新できます。ただし、他の方法でもローカライズされたストリングを使用できます。例えば、動的に生成される HTML でストリングを使用したり、関数呼び出しのパラメーター値としてストリングを使用したりすることができます。例えば、次のコードは alert() 関数を呼び出します。このとき、fr_FR ロケールのデフォルトプロパティファイルの error114 リソースで定義されているストリングを使用します。

alert(air.Localizer.localizer.getString("default", "error114", null, "fr_FR"));

getString() メソッドは、指定されたバンドル内でリソースが見つからなかった場合、resourceNotFound イベントを送出します。air.Localizer.RESOURCE_NOT_FOUND 定数は、ストリング「resourceNotFound」を定義します。このイベントには、bundleName、resourceName および locale の 3 つのプロパティがあります。bundleName プロパティは、リソースが見つからないバンドルの名前です。resourceName プロパティは、リソースが見つからないバンドルの名前です。locale プロパティは、リソースが見つからないロケールの名前です。

getString() メソッドは、指定されたバンドルが見つからなかった場合、bundleNotFound イベントを送出します。air.Localizer.BUNDLE_NOT_FOUND 定数は、ストリング「bundleNotFound」を定義します。このイベントには、bundleName と locale の 2 つのプロパティがあります。bundleName プロパティは、リソースが見つからないバンドルの名前です。locale プロパティは、リソースが見つからないロケールの名前です。

getString() メソッドは非同期に動作します（resourceNotFound イベントと bundleNotFound イベントを非同期に送出します）。次のコードは、resourceNotFound イベントとbundleNotFound イベントのイベントリスナーを設定します。

air.Localizerlocalizer.addEventListener(air.Localizer.RESOURCE_NOT_FOUND, rnfHandler); 
air.Localizerlocalizer.addEventListener(air.Localizer.BUNDLE_NOT_FOUND, bnfHandler); 
var str = air.Localizer.localizer.getString("default", "error114", null, "fr_FR"); 
function rnfHandler(event) 
{ 
    alert(event.bundleName + ": " + event.resourceName + ":." + event.locale); 
} 
function bnfHandler(event) 
{ 
    alert(event.bundleName + ":." + event.locale); 
}

Localizer オブジェクトの getResourceBundle() メソッドは、特定のロケールの指定されたバンドルを返します。メソッドの戻り値は、バンドルのキーに一致するプロパティを持つオブジェクトです（アプリケーションで指定されたバンドルが見つからなかった場合、メソッドは null を返します）。

locale

bundleName

var aboutWin = window.open(); 
var bundle = localizer.getResourceBundle("fr", "default"); 
aboutWin.document.write(bundle.str1); 
aboutWin.document.write("<br/>"); 
aboutWin.document.write(bundle.str2); 
aboutWin.document.write("<br/>");

getResourceBundle() メソッドは、指定されたバンドルが見つからなかった場合、bundleNotFound イベントを送出します。air.Localizer.BUNDLE_NOT_FOUND 定数は、ストリング「bundleNotFound」を定義します。このイベントには、bundleName と locale の 2 つのプロパティがあります。bundleName プロパティは、リソースが見つからないバンドルの名前です。locale プロパティは、リソースが見つからないロケールの名前です。

resourceFileName

templateArgs

<html> 
<body>Hello, {0}. You have {1} new messages.</body> 
</html> 

<html> 
<body>Hello, Raúl. You have 4 new messages. </body> 
</html> 

locale

例えば、次のコードは、fr ロケールの about.html ファイルの内容を使用して、document.write() メソッドを呼び出します。

var aboutWin = window.open(); 
var aboutHtml = localizer.getFile("about.html", null, "fr"); 
aboutWin.document.close(); 
aboutWin.document.write(aboutHtml);

getFile() メソッドは、ロケールチェーン内でリソースが見つからなかった場合、fileNotFound イベントを送出します。air.Localizer.FILE_NOT_FOUND 定数は、ストリング「resourceNotFound」を定義します。getFile() メソッドは非同期に動作します（fileNotFound イベントを非同期に送出します）。このイベントには、fileName と locale の 2 つのプロパティがあります。fileName プロパティは、見つからなかったファイルの名前です。locale プロパティは、リソースが見つからないロケールの名前です。次のコードは、このイベントのイベントリスナーを設定します。

air.Localizer.localizer.addEventListener(air.Localizer.FILE_NOT_FOUND, fnfHandler); 
air.Localizer.localizer.getFile("missing.html", null, "fr"); 
function fnfHandler(event) 
{ 
    alert(event.fileName + ": " + event.locale); 
}