Compartir a través de

Calificadores en MRM

  • Artículo

El indexador de recursos (y el entorno de ejecución de MRT) usan "calificadores" para determinar los contextos en los que se debe usar un candidato de recurso determinado. Cada recurso tiene un nombre y uno o varios candidatos (o valores) y cada candidato tiene cero o más calificadores. Para obtener más información sobre cómo asignar nombres a recursos, consulte Nombres de recursos en MRM.

Por ejemplo, puede haber un recurso de cadena denominado greeting con tres candidatos diferentes para tres localizaciones diferentes:

  • En inglés, el texto "Hello"
  • En alemán, el texto "Hallo"
  • En coreano, el texto "안녕하세요"

Estos candidatos se agregan al indexador con los calificadores de idioma correctos y se almacenan en el archivo PRI para que MRT sepa cuál usar en tiempo de ejecución. Por ejemplo, para agregar estas tres cadenas a un indexador, puede usar:

    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 */ }

Idioma es solo uno de los posibles calificadores; otros calificadores comunes incluyen Escala (para especificar imágenes en diferentes resoluciones) o Contraste (para diferentes configuraciones de contraste). En el tema ResourceContext.QualifierValues se muestra una lista completa de calificadores.

Tenga en cuenta que la forma "abreviada" de los calificadores (por ejemplo, "idiom" en lugar de "idioma") no son compatibles con las API de MRM; se debe usar el formato largo. No obstante, las funciones MrmIndexFileAutoQualifiers y MrmIndexResourceContainerAutoQualifiers que deducen calificadores de rutas de archivo admiten las formas abreviadas.

Los calificadores se especifican como cadenas con formato name-value, como language-en o scale-200. (Los valores de un calificador de Idioma también puede contener guiones, como en-us). Tanto el nombre como el valor no distinguen mayúsculas de minúsculas, por lo que LANGUAGE-EN-US, Language-En-Us y language-en-us son todos equivalentes.

Tenga en cuenta que es un error especificar dos candidatos para el mismo recurso con los mismos calificadores pero con valores diferentes. Desafortunadamente, este error no se muestra cuando se agregan recursos al indexador (por ejemplo, al llamar a MrmIndexString), pero en el momento en que se genera el archivo PRI, la generación devolverá ERROR_MRM_DUPLICATE_ENTRY pero no proporcionará ninguna indicación de qué recurso causó el problema.

Por ejemplo, este fragmento de código se realizará correctamente al agregar un candidato duplicado, pero fallará más adelante durante la generación de 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 el mismo candidato exacto se agrega dos veces (por ejemplo, en el código anterior, si la segunda llamada repite "rojo" en lugar de usar "azul"), se omite el duplicado y no se genera ningún error.

Listas de calificadores

Los candidatos de recursos pueden tener más de un calificador. Por ejemplo, los archivos de imagen pueden necesitar candidatos basados en Escala (100%, 200%, etc.) y Contraste (estándar o alto). Si la imagen contiene texto, es posible que también tenga que calificarse en función del Idioma.

Se especifican varios calificadores en una sola cadena, separados por caracteres de subrayado. Por ejemplo, un candidato de imagen para contraste alto en un escalado del 200 % usaría el calificador contrast-high_scale-200. El orden en el que se especifican calificadores en la lista no importa; MRT tiene un orden integrado de importancia para cada calificador (por ejemplo, el Idioma es más importante que la Escala).

Aunque no es un error repetir un calificador en una lista de calificadores (incluso con valores diferentes), se ignorarán todos menos el primero.

  • language-en_language-en (especifique el inglés dos veces: el idioma efectivo es inglés)
  • language-en_language-de (especifique inglés y, a continuación, alemán: el idioma efectivo es inglés)
  • language-de_language-en (especifique alemán y, a continuación, inglés: el idioma efectivo es alemán)

Como se indicó anteriormente, es un error agregar dos candidatos a recursos con los mismos calificadores, pero con valores diferentes. Esto es independiente del orden de los calificadores en una lista de calificadores.

Candidatos neutros

Al agregar candidatos de recursos al indexador, puede especificar una cadena vacía (o puntero nulo) como calificador para indicar que el candidato es "neutro" y que puede coincidir con cualquier contexto. Por ejemplo, el nombre de la aplicación que se muestra en el menú Inicio puede ser un candidato neutro porque los nombres de aplicación no suelen localizarse (y no dependen de otros elementos como la escala o el contraste). Los candidatos neutros se pueden usar además de candidatos específicos, si lo desea.

Por ejemplo:

// 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");

Calificadores predeterminados

Al crear un archivo de configuración (a través de una de las funciones MrmCreateConfig...) o al crear un indexador de recursos (a través de una de las funciones MrmCreateResourceIndexer...), los defaultQualifiers son los calificadores (por ejemplo, el idioma) que indican los candidatos de recursos que se van a usar si no se pueden encontrar coincidencias mejores. Por ejemplo, si una aplicación tiene recursos en inglés y francés, pero se ejecuta en el sistema con el idioma establecido en japonés, se usará el idioma especificado como "calificador predeterminado" cuando se creó el archivo PRI. Los calificadores predeterminados también determinan qué idioma y escala se deben usar para crear el archivo PRI principal al usar el empaquetado AutoSplit (consulte MrmPackagingMode para obtener más información).

Tenga en cuenta que todos los recursos deben tener un candidato especificado con los calificadores predeterminados (o un candidato neutro), de lo contrario no habría nada a lo que recurrir en caso de que no hubiera mejor coincidencia. Tenga en cuenta que no proporcionar un candidato de reserva no se considera un error (el indexador generará un candidato de cadena vacía), pero puede dar lugar a una mala experiencia de usuario o errores de aplicación.