MRM の修飾子
リソース インデクサー (および MRT ランタイム) は "修飾子" を使用して、特定のリソース候補を使用する必要があるコンテキストを決定します。 すべてのリソースには名前と 1 つ以上の候補 (または値) があり、各候補には 0 個以上の修飾子があります。 リソースの名前付けの詳細については、「MRM のリソース名」を参照してください。
たとえば、3 つの異なるローカライズに対して 3 つの候補を持つ greeting という名前の文字列リソースがあるとします。
- 英語の場合は、"Hello" というテキスト
- ドイツ語の場合は、"Hallo" というテキスト
- 韓国語の場合は、"안녕하세요" というテキスト
これらの候補は、適切な言語修飾子を使用してインデクサーに追加され、MRT が実行時に使用する言語を認識できるように PRI ファイルに格納されます。 たとえば、これら 3 つの文字列をインデクサーに追加するのに、次のコマンドを使用するかもしれません。
HRESULT hr{};
hr = MrmIndexString(indexer, L"ms-resource:///strings/greeting", L"Hello", L"language-en");
hr |= MrmIndexString(indexer, L"ms-resource:///strings/greeting", L"Hallo", L"language-de");
hr |= MrmIndexString(indexer, L"ms-resource:///strings/greeting", L"안녕하세요", L"language-ko");
if (FAILED(hr)) { /* error handling */ }
Language は使用可能な修飾子の 1 つにすぎません。他の一般的な修飾子には、Scale (異なる解像度でイメージを指定する場合) や Contrast (異なるコントラスト設定の場合) などがあります。 修飾子の完全な一覧は、ResourceContext.QualifierValues トピックに掲載されています。
"短い" 形式の修飾子 ("language" ではなく "lang" など) は MRM API ではサポートされていないことに注意してください。長い形式を使用する必要があります。 ただし、ファイル パスから修飾子を推測する MrmIndexFileAutoQualifiers 関数と MrmIndexResourceContainerAutoQualifiers 関数では短い形式がサポートされます。
修飾子は、language-en や scale-200 など、形式 name-value の文字列として指定されます。
(Language 修飾子の値には、en-us などのハイフンを含めることもできます)。名前と値はどちらも大文字と小文字が区別されないため、LANGUAGE-EN-US、Language-En-Us、language-en-us はすべて同等です。
修飾子が同じでも値が異なる同じリソースに対して 2 つの候補を指定するとエラーになるので注意してください。 残念ながら、このエラーは、リソースがインデクサーに追加されたとき (MrmIndexString を呼び出すときなど) には発生しませんが、PRI ファイルが生成されたときには発生します。生成されると ERROR_MRM_DUPLICATE_ENTRY が返されますが、どのリソースが問題の原因かは示されません。
たとえば、このコード スニペットは、重複する候補を追加すると成功しますが、PRI の生成中の場合に追加すると後で失敗します。
// Add "color = red". Returns S_OK, since all arguments are valid.
hr = MrmIndexString(indexer, L"ms-resource:///strings/color", L"red", L"language-en");
// Add "color = blue". Returns S_OK, since all arguments are valid (in isolation).
hr = MrmIndexString(indexer, L"ms-resource:///strings/color", L"blue", L"language-en");
// Fails with ERROR_MRM_DUPLICATE_ENTRY since there are two English candidates for "strings/color"
// ("red" and "blue").
hr = MrmCreateResourceFile(indexer, MrmPackagingModeStandaloneFile, MrmPackagingOptionsNone, fileName);
まったく同じ候補が 2 回追加されると (上記のコードでは、2 回目の呼び出しで "blue" を使用する代わりに "red" が繰り返し使用された場合など)、重複は無視され、エラーは生成されません。
修飾子リスト
リソース候補には、複数の修飾子を指定できます。 たとえば、イメージ ファイルには、Scale (100%、200% など) と Contrast (標準または高) の両方に基づく候補が必要な場合があります。 イメージにテキストが含まれている場合は、Language に基づいて修飾することが必要な場合もあります。
1 つの文字列で複数の修飾子を指定する場合は、アンダースコアで区切ります。 たとえば、200% スケールのハイ コントラストのイメージ候補では、修飾子 contrast-high_scale-200 が使用されます。 リストで修飾子を指定する順序は関係ありません。MRT には、各修飾子の重要度の順序が組み込まれています (例: Language は Scale よりも重要)。
修飾子リスト内で修飾子を繰り返してもエラーになりませんが (値が異なる場合でも)、最初の修飾子以外はすべて無視されます。
language-en_language-en(英語を 2 回指定する - 有効な言語は英語)language-en_language-de(英語を指定してからドイツ語を指定する - 有効な言語は英語)language-de_language-en(ドイツ語を指定してから英語を指定する - 有効な言語はドイツ語)
上記のように、修飾子は同じでも値が異なる 2 つのリソース候補を追加するとエラーになります。 これは、修飾子リスト内の修飾子の順序とは関係ありません。
ニュートラル候補
リソース候補をインデクサーに追加するときに、修飾子に空の文字列 (または null ポインター) を指定して、候補が "ニュートラル" であり、どのコンテキストとも一致する可能性があることを示すことができます。 たとえば、アプリ名は通常ローカライズされないため (そして、Scale や Contrast などの他の要素に依存しないため)、スタート メニューに表示されるアプリの名前はニュートラルな候補になる場合があります。 必要に応じて、特定の候補に加えてニュートラル候補を使用できます。
次に例を示します。
// The name of the app is the same, regardless of language, scale, etc.
hr = MrmIndexString(indexer, L"ms-resource:///strings/AppName", L"Contoso Widgets", nullptr);
// The name of the publisher is always "Contoso Inc." except in Australia, where it is "Contoso PTY LTD".
hr = MrmIndexString(indexer, L"ms-resource:///strings/AppPublisher", L"Contoso Inc.", nullptr);
hr = MrmIndexString(indexer, L"ms-resource:///strings/AppPublisher", L"Contoso PTY LTD", L"homeregion-au");
既定の修飾子
構成ファイルを (MrmCreateConfig... 関数の 1 つを使用して) 作成するとき、またはリソース インデクサーを (MrmCreateResourceIndexer... 関数の 1 つを使用して) 作成するとき、defaultQualifiers は、より適切な一致が見つからない場合に使用されるリソース候補を示す修飾子 (言語など) になります。 たとえば、アプリのリソースは英語とフランス語であるのに、言語が日本語に設定されているシステムでアプリが実行されている場合、PRI ファイルの作成時に "既定の修飾子" として指定された言語が使用されます。 また、AutoSplit パッケージの使用時には、メイン PRI ファイルを作成するために使用する必要のある言語とスケールも既定の修飾子で決まります (詳細については、MrmPackagingMode を参照してください)。
すべてのリソースは既定の修飾子 (またはニュートラル候補) で指定された候補を持つ必要があることに注意してください。それ以外の場合は、最適な一致がない場合にフォールバックするものはありません。 フォールバック候補の指定の失敗はエラーとはみなされません (インデクサーによって空の文字列候補が生成されます) が、ユーザー エクスペリエンスの低下またはアプリケーションのバグが発生する可能性があることに注意してください。