Qualificateurs dans MRM
L’indexeur de ressources (et le runtime MRT) utilisent des « qualificateurs » pour déterminer le(s) contexte(s) dans le(s)quel(s) un candidat ressource donné doit être utilisé. Chaque ressource a un nom et un ou plusieurs candidats (ou valeurs), et chaque candidat a zéro ou plusieurs qualificateurs. Pour plus d’informations sur la dénomination des ressources, veuillez consulter la section Noms de ressources dans MRM.
Par exemple, il peut y avoir une ressource chaîne nommée greeting avec trois candidats différents pour trois localisations différentes :
- Pour l’anglais, le texte « Hello »
- Pour l’allemand, le texte « Hallo »
- Pour le coréen, le texte « 안녕하세요 »
Ces candidats sont ajoutés à l’indexeur avec les qualificateurs de langue appropriés, et ils sont stockés dans le fichier PRI afin que MRT sache lequel utiliser à l’exécution. Par exemple, pour ajouter ces trois chaînes à un indexeur, on pourrait utiliser :
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 n’est qu’un des qualificateurs possibles ; d’autres qualificateurs courants incluent Scale (pour spécifier des images à différentes résolutions) ou Contrast (pour différents réglages de contraste). Une liste complète des qualificateurs est fournie dans la rubrique ResourceContext.QualifierValues.
Notez que la forme « courte » des qualificateurs (par exemple « lang » au lieu de « language ») n’est pas prise en charge par les API MRM ; vous devez utiliser la forme longue. Néanmoins, les fonctions MrmIndexFileAutoQualifiers et MrmIndexResourceContainerAutoQualifiers, qui déduisent les qualificateurs à partir des chemins de fichiers, prennent en charge les formes courtes.
Les qualificateurs sont spécifiés sous forme de chaînes dans le format name-value, tel que language-en ou scale-200.
(Les valeurs pour un qualificateur Language peuvent également contenir des tirets, tels que en-us). Le nom et la valeur sont insensibles à la casse, donc LANGUAGE-EN-US, Language-En-Us et language-en-us sont tous équivalents.
Notez qu’il est une erreur de spécifier deux candidats pour la même ressource avec les mêmes qualificateurs mais des valeurs différentes. Malheureusement, cette erreur n’est pas signalée lorsque des ressources sont ajoutées à l’indexeur (par exemple, lors de l’appel à MrmIndexString), mais au moment où le fichier PRI est généré : la génération renverra ERROR_MRM_DUPLICATE_ENTRY sans fournir d’indication sur la ressource ayant causé le problème.
Par exemple, cet extrait de code réussira lors de l’ajout d’un candidat dupliqué, mais échouera plus tard lors de la génération du fichier 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);
Si exactement le même candidat est ajouté deux fois (par exemple, dans le code ci-dessus, si le second appel répétait « red » au lieu d’utiliser « blue »), alors le duplicata est ignoré et aucune erreur n’est générée.
Listes de qualificateurs
Les candidats ressources peuvent avoir plus d’un qualificateur. Par exemple, les fichiers image peuvent nécessiter des candidats basés à la fois sur Scale (100 %, 200 %, etc.) et Contrast (standard ou élevé). Si l’image contient du texte, il peut également être nécessaire de la qualifier en fonction de Language.
Les qualificateurs multiples sont spécifiés dans une seule chaîne, séparés par des traits de soulignement. Par exemple, un candidat image pour un contraste élevé à 200 % d’échelle utiliserait le qualificateur contrast-high_scale-200. L’ordre dans lequel les qualificateurs sont spécifiés dans la liste n’a pas d’importance ; MRT dispose d’un ordre d’importance intégré pour chaque qualificateur (par exemple, Language est plus important que Scale).
Bien qu’il ne soit pas une erreur de répéter un qualificateur dans une liste de qualificateurs (même avec des valeurs différentes), tous sauf le premier seront ignorés.
language-en_language-en(spécifier deux fois l’anglais : la langue effective est l’anglais)language-en_language-de(spécifier l’anglais puis l’allemand : la langue effective est l’anglais)language-de_language-en(spécifier l’allemand puis l’anglais : la langue effective est l’allemand)
Comme mentionné ci-dessus, il est une erreur d’ajouter deux candidats de ressource avec les mêmes qualificateurs mais des valeurs différentes. Cela est indépendant de l’ordre des qualificateurs dans une liste de qualificateurs.
Candidats neutres
Lorsque vous ajoutez des candidats de ressources à l’indexeur, vous pouvez spécifier une chaîne vide (ou un pointeur nul) comme qualificateur pour indiquer que le candidat est « neutre » et peut correspondre à n’importe quel contexte. Par exemple, le nom de l’application affiché dans le menu Démarrer peut être un candidat neutre parce que les noms d’applications ne sont généralement pas localisés (et ils ne dépendent pas d’autres critères comme Scale ou Contrast). Les candidats neutres peuvent être utilisés en plus des candidats spécifiques, si désiré.
Par exemple :
// 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");
Qualificateurs par défaut
Lors de la création d’un fichier de configuration (via l’une des fonctions MrmCreateConfig...) ou de la création d’un indexeur de ressources (via l’une des fonctions MrmCreateResourceIndexer...), les qualificateurs par défaut sont les qualificateurs (tels que la langue) qui indiquent les candidats de ressource à utiliser s’il n’y a pas de meilleure correspondance trouvée. Par exemple, si une application dispose de ressources en anglais et en français, mais qu’elle fonctionne sur un système avec la langue définie en japonais, la langue spécifiée comme « qualificateur par défaut » lors de la création du fichier PRI sera utilisée. Les qualificateurs par défaut déterminent également quelle langue et quelle échelle doivent être utilisées pour créer le fichier PRI principal lors de l’utilisation de l’empaquetage AutoSplit (veuillez consulter MrmPackagingMode pour plus d’informations).
Notez que toutes les ressources doivent avoir un candidat spécifié avec les qualificateurs par défaut (ou un candidat neutre), sinon il n’y aurait rien sur quoi se rabattre au cas où il n’y aurait pas de meilleure correspondance. Notez que ne pas fournir de candidat de secours n’est pas considéré comme une erreur (l’indexeur générera un candidat de chaîne vide pour vous), mais cela peut entraîner une mauvaise expérience utilisateur ou des bugs dans l’application.