Cómo cargar recursos de cadenas (HTML)

Artículo
01/29/2016

[ Este artículo está destinado a desarrolladores de Windows 8.x y Windows Phone 8.x que escriben aplicaciones de Windows Runtime. Si estás desarrollando para Windows 10, consulta la documentación más reciente ]

Puedes cargar recursos de cadena a partir de objetos, como archivos de recursos, bibliotecas y controles, además de manifiestos y paquetes de la aplicación.

Cargar cadenas desde archivos de recursos

Los recursos de cadenas se crean en los archivos de recursos y se hace referencia a ellos mediante identificadores de recursos. Para ver una introducción básica a la carga de recursos de cadenas, consulta Inicio rápido: uso de recursos de cadenas.

La mayoría de las aplicaciones solo necesitan un archivo de recursos predeterminado por idioma (<language>/Resources.resjson), y pueden hacer referencia a sus recursos mediante el uso de un trazado relativo a las claves dentro de ese archivo (por ejemplo /String1). Pero en algunas aplicaciones, lo apropiado sería separar los recursos en varios archivos de recursos para proporcionar la separación de los componentes.

Por ejemplo:

Nombre de archivo:

Strings/en-US/Errors.resjson

Referencia de marcado:

<span data-win-res="{textContent: '/Errors/AlreadyRegistered'}"></span>

Referencia de código:

WinJS.Resources.getString('/Errors/AlreadyRegistered');

El identificador del recurso tiene el formato **/ResourceFileName/**StringName. Ten en cuenta que el nombre de archivo del recurso no incluye la extensión ni el trazado de la carpeta. Por lo tanto, los nombres de archivo de todos los recursos deben ser únicos en un componente o un proyecto.

Cargar cadenas desde bibliotecas y controles

Las aplicaciones suelen tener varios componentes o tomar dependencias de bibliotecas, como las bibliotecas de clases portátiles de .NET, otras bibliotecas de clases compatibles y las bibliotecas de controles.

Siempre que sea posible, los controles y las bibliotecas deben intentar reducir la cantidad de recursos y depender de la aplicación para proporcionarlos. Cuando una biblioteca tiene que proporcionar recursos, debería permitir que las aplicaciones sustituyan esos recursos como si fueran una entrada. Esto puede ser necesario si la biblioteca no tiene el mismo grado de localización que la aplicación que la usa.

Por ejemplo:

var rating = new WinJS.UI.RatingsControl(el, {label: 'Please Rate', image: 'images/star.png'});

El control debe mostrar las cadenas personalizadas que pasan a él exactamente como se proporcionan y, siempre que sea posible, debe dejar que la aplicación controle la localización.

var control = new Control(el, {commands: [
    {label: R.getString('Reply')}, 
    {label: R.getString('ReplyAll')
    ]});

Los componentes o los archivos de biblioteca se suelen agregar en una subcarpeta del paquete en el que se encuentran durante el proceso de compilación, del mismo modo que sus recursos de cadena. Su identificador de recurso, por lo general, tendrá la siguiente forma:

ClassLibraryOrAssemblyName**/ResourceFileName/**StringName

Desde el punto de vista de la programación, las bibliotecas también pueden tener su propio ResourceLoader para sus recursos. Por ejemplo, el siguiente código muestra cómo una biblioteca puede obtener ResourceLoader para su propio archivo de recursos:


var resources = Windows.ApplicationModel.Resources;
var RL = new resources.ResourceLoader('ContosoControl/Resources');
RL.getString('loadingStr'); // which came from ContosoControl's Resources

Cargar cadenas desde otros paquetes

Los recursos de cada paquete de la aplicación se administran por separado y se tiene acceso a ellos mediante el objeto ResourceMap de alto nivel independiente al que se puede acceder desde ResourceManager actual. Dentro de cada paquete puede haber varios componentes que tengan sus propios valores ResourceMap Subtree.

Los paquetes de marco pueden acceder a sus propios recursos con un URI de identificador de recursos más absoluto:

Para obtener más detalles sobre URI ms-resource, consulta esquemas URI.

Cargar cadenas desde controles de JavaScript

Los controles de JavaScript que proporcionan cadenas predeterminadas deberían utilizar WinJS.Resources.getString para recuperar sus propias cadenas.

Los documentos HTML cargados en el contexto web (con ms-app-web:) no tienen acceso a las API de Windows en tiempo de ejecución. Por lo tanto, en el código de JavaScript incluye controles de JavaScript que se hayan escrito para que usen WinJS.Resources.getString. En el contexto web, WinJS.Resources.getString retrocede para buscar el identificador determinado como propiedad de un objeto de cadenas global.

var strings = { 'String1' : 'Hello' };
WinJS.Resources.getString('String1');

WinJS.Resources.getString también se puede sobrescribir para acceder a recursos desde una ubicación distinta.

WinJS.Resources.getString = function(id){
    return getStringFromOtherService(id);
}

Cargar cadenas desde el manifiesto de la aplicación

Todas las cadenas y los logotipos que se pueden mostrar del manifiesto son localizables. También se puede adaptar la escala y el modo de contraste alto de los logotipos. Para agregar referencias de cadena en el lugar de una cadena codificada de forma rígida, coloca un URI especificado por el esquema ms-resource: en los datos de manifiesto (por lo general, esto se realiza en la interfaz de usuario con pestañas de Visual Studio para editar appxmanifest). Por ejemplo, ms-resource:String1 hace referencia a una cadena denominada String1 del archivo de recursos Resources.resw, mientras que ms-resource:/ManifestStrings/Shortname hace referencia a una cadena denominada Shortname del archivo de recursos ManifestStrings.resw.

Cargar cadenas para un idioma o un contexto específicos

El ResourceContext predeterminado, un objeto que se obtiene del ResourceManager, representa el estado actual con el coinciden los recursos. El ResourceContext contiene todos los distintos valores de calificador del usuario y la máquina actual. Aunque se puede sobrescribir cada calificador, esto no se recomienda. La mayor parte de los calificadores tienen un proveedor de datos del sistema que, en algunos casos, es mejor modificar mediante una API distinta (es decir, PrimaryLanguageOverride) o, mejor aún, se puede dejar sin cambiar.

Consulta Cómo asignar nombre a los recursos mediante calificadores para obtener información detallada sobre los distintos calificadores.

ResourceManager mantiene el objeto de contexto predeterminado en el que se realizan las búsquedas de recursos. En algunos casos, resulta útil dar información explícita sobre el idioma, la escala u otros calificadores de contexto cuando la aplicación carga recursos. Por ejemplo, una aplicación podría permitir que un usuario seleccione un idioma alternativo para la información sobre herramientas o los mensajes de error. Las búsquedas pueden especificar su propio objeto de contexto sobrescrito explícito para decidir qué recurso se elige. Para especificar un contexto explícito, donde la propiedad Languages se reemplaza de forma deliberada:

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;

Otra técnica que puedes usar es llamar a ResourceContext.SetGlobalQualifierContext antes de llamar a ResourceContext.GetForCurrentView. Para el escenario de idioma deberías establecer el calificador language en un nuevo valor. Si haces esto, la diferencia es que el cambio de calificador y contexto ahora se aplica en todas las búsquedas de recursos, no solo a ResourceContext específico que has creado para el uso de la llamada GetValue única. Consulta también ApplicationLanguages.PrimaryLanguageOverride.

Eventos y cambios de contexto

Una aplicación puede seguir ejecutándose cuando el sistema cambia. Esto hace que se use un conjunto distinto de calificadores. Uno de estos cambios se produce si el usuario activa el contraste alto. Hay varios cambios del sistema que invocarán eventos en el objeto ResourceContext.

En JavaScript, la forma más simple de detectar estos eventos es mediante el método addEventListener.

WinJS.Resources.addEventListener('contextchanged', refresh, false);

Después de detectar el evento, las aplicaciones pueden volver a procesar el documento para que se puedan volver a cargar los recursos.

function refresh(){
    WinJS.Resources.processAll(); // Refetch string resources.
}

Si se reprocesan los recursos, es posible que se restablezcan los valores de enlace de datos dentro del recurso, cuando se aplique el nuevo recurso directamente en la propiedad el elemento. Si el recurso contiene ranuras de enlace de datos, asegúrate de reenlazarlas en el reprocesamiento.