文字列リソースを読み込む方法 (HTML)
[ この記事は、Windows ランタイム アプリを作成する Windows 8.x および Windows Phone 8.x 開発者を対象としています。Windows 10 向けの開発を行っている場合は、「最新のドキュメント」をご覧ください]
文字列リソースは、リソース ファイル、ライブラリ、コントロール、アプリ パッケージ、マニフェストなどのオブジェクトから読み込むことができます。
リソース ファイルから文字列を読み込む
文字列リソースはリソース ファイル内に作られ、リソース識別子を使って参照されます。文字列リソースの読み込みの基本的な概要については、「クイック スタート: 文字列リソースの使用」をご覧ください。
ほとんどのアプリでは、言語別の既定のリソース ファイル (<language>/Resources.resjson) が 1 つだけ必要となり、そのファイルに含まれるキーへの相対パスを使ってリソースを参照できます (例: /String1)。ただし、コンポーネントを分離するためにリソースを複数のリソース ファイルに分けることが適しているアプリもあります。
例:
ファイル名:
Strings/en-US/Errors.resjson
マークアップからの参照:
<span data-win-res="{textContent: '/Errors/AlreadyRegistered'}"></span>
コードからの参照:
WinJS.Resources.getString('/Errors/AlreadyRegistered');
リソース識別子は **/ResourceFileName/**StringName という形式になります。リソース ファイル名には拡張子またはフォルダー パスは含まれません。したがって、すべてのリソース ファイル名はコンポーネントまたはプロジェクト内で一意である必要があります。
ライブラリとコントロールから文字列を読み込む
アプリは、複数のコンポーネントを備えていたり、.NET ポータブル クラス ライブラリ、互換性がある他のクラス ライブラリ、コントロール ライブラリなどのライブラリに依存したりする場合があります。
可能であれば、コントロールとライブラリではリソース数を減らし、リソースを提供するアプリを利用する必要があります。ライブラリがリソースを提供する必要がある場合、アプリがそれらのリソースを入力に置き換えられるようにする必要があります。これは、ライブラリがアプリと同じ程度ローカライズされていない場合に必要になることがあります。
例:
var rating = new WinJS.UI.RatingsControl(el, {label: 'Please Rate', image: 'images/star.png'});
コントロールは、渡されたカスタムの文字列を与えられたとおりに表示し、可能な限り、アプリにローカライズを処理させる必要があります。
var control = new Control(el, {commands: [
{label: R.getString('Reply')},
{label: R.getString('ReplyAll')
]});
コンポーネントまたはライブラリ ファイルは、通常パッケージのサブフォルダーに追加されます。これらは、文字列リソースと同様に、ビルド処理の間に含められます。これらのリソース識別子は通常次のような形式です。
ClassLibraryOrAssemblyName**/ResourceFileName/**StringName
プログラムを使って、ライブラリはリソースに対して独自の ResourceLoader を取得することもできます。たとえば、次のコードはライブラリが自身のリソース ファイルに対して ResourceLoader を取得する方法を示しています。
var resources = Windows.ApplicationModel.Resources;
var RL = new resources.ResourceLoader('ContosoControl/Resources');
RL.getString('loadingStr'); // which came from ContosoControl's Resources
他のパッケージから文字列を読み込む
各アプリ パッケージのリソースは、現在の ResourceManager からアクセスできる、個々のトップ レベルの ResourceMap オブジェクトを介して個別に管理され、アクセスされます。各パッケージ内では、さまざまなコンポーネントが独自の ResourceMap Subtree 値を持つことができます。
フレームワーク パッケージはより絶対的なリソース識別子 URI を使って独自のリソースにアクセスできます。
ms-resource URI について詳しくは、「URI スキーム」をご覧ください。
JavaScript コントロールから文字列を読み込む
既定の文字列を提供する JavaScript コントロールは、WinJS.Resources.getString を使って独自の文字列を取得する必要があります。
Web コンテキストに読み込まれた HTML ドキュメント (ms-app-web: が付加されています) は、Windows ランタイム API にアクセスできません。したがって、JavaScript コードには、WinJS.Resources.getString を使うように記述された JavaScript コントロールを含めてください。Web コンテキストで、WinJS.Resources.getString はフォールバックしてグローバル文字列オブジェクトのプロパティとして指定された識別子を探します。
var strings = { 'String1' : 'Hello' };
WinJS.Resources.getString('String1');
WinJS.Resources.getString を上書きして、別の場所からリソースにアクセスすることもできます。
WinJS.Resources.getString = function(id){
return getStringFromOtherService(id);
}
アプリ マニフェストから文字列を読み込む
マニフェスト内のすべての表示可能な文字列とロゴはローカライズできます。また、ロゴをスケールやハイ コントラスト モードに合わせて調整することもできます。文字列の参照は、ms-resource: スキーム指定された URI をマニフェスト データに配置することによって、ハードコードされた文字列の位置に追加できます (通常、この操作は、appxmanifest を編集するための Visual Studio のタブ方式の UI で行われます)。たとえば、ms-resource:String1 は Resources.resw リソース ファイルの String1 と呼ばれる文字列を参照し、ms-resource:/ManifestStrings/Shortname は ManifestStrings.resw リソース ファイルの Shortname と呼ばれる文字列を参照します。
特定の言語またはコンテキスト用の文字列を読み込む
ResourceManager から取得されるオブジェクトである既定の ResourceContext は、リソースが適合される現在の状態を表します。ResourceContext には、現在のユーザーとコンピューターのさまざまな修飾子のすべての値が含まれます。ただし、各修飾子が上書きされる可能性があるので上書きすることはお勧めしません。多くの修飾子にはシステム データ プロバイダーがありますが、これを個別の API (つまり、PrimaryLanguageOverride) を介して変更するか、変更しないでおく方が良いことがあります。
さまざまな修飾子について詳しくは、「修飾子を使ってリソースに名前を付ける方法」をご覧ください。
ResourceManager は、リソース検索の実行対象となる既定のコンテキスト オブジェクトを管理します。アプリでリソースを読み込むときに、言語、スケール、他のコンテキスト修飾子を明示的に示すと、役立つ場合があります。たとえば、ユーザーがヒントやエラー メッセージに別の言語を選ぶことができようにアプリを設定できます。リソース検索では、選んだリソースが反映されるように、明示的に上書きされたコンテキスト オブジェクトを独自に指定できます。Languages プロパティが意図的に上書きされている場合、明示的なコンテキストを指定する方法は次のとおりです。
var rcns = Windows.ApplicationModel.Resources.Core;
var context = new rcns.ResourceContext(); // deliberately not using getForCurrentView()
context.languages = new Array('fr-fr');
var resourceMap = rcns.ResourceManager.current.mainResourceMap.getSubtree('Resources');
var str = resourceMap.getValue('string1', context).ValueAsString;
別の方法としては、ResourceContext.GetForCurrentView を呼び出す前に ResourceContext.SetGlobalQualifierContext を呼び出す方法があります。言語のシナリオでは、language 修飾子を新しい値に設定します。これを行った場合の相違点は、修飾子とコンテキストの変更が、単一の GetValue 呼び出しで使うために作成した特定の ResourceContext だけでなく、すべてのリソース検索に適用されることです。ApplicationLanguages.PrimaryLanguageOverride もご覧ください。
イベントとコンテキストの変更
場合によっては、アプリは、システムが変更されても実行し続けることができます。そのため、さまざまな修飾子のセットが使われます。そのようなシステム変更が発生するのは、ユーザーがハイ コントラストをオンにした場合などです。システムでさまざまな変更が行われると、ResourceContext オブジェクトでイベントが呼び出されます。
JavaScript でこれらのイベントをリッスンする最も簡単な方法は、次のように addEventListener メソッドを使う方法です。
WinJS.Resources.addEventListener('contextchanged', refresh, false);
イベントを検出すると、アプリは正しいリソースが読み込まれるようにドキュメントを再処理できます。
function refresh(){
WinJS.Resources.processAll(); // Refetch string resources.
}
リソースを再処理すると、新しいリソースが要素のプロパティに直接適用されたときにリソース内のデータバインド値がリセットされる可能性があります。リソースにデータバインディング スロットが含まれている場合は、再処理時にそれらのスロットを必ず再バインドしてください。
関連トピック
Windows.ApplicationModel.Resources.ResourceLoader
Windows.ApplicationModel.Resources.Core.ResourceContext
Windows.ApplicationModel.Resources.Core.ResourceManager
Windows.ApplicationModel.Resources.Core.ResourceMap
Windows.Globalization.ApplicationPreferences.PrimaryLanguageOverride