Localización de contenido HTML con la arquitectura de localización de HTML de AIR

Para utilizar la arquitectura de localización, copie el archivo AIRLocalizer.js en su proyecto. Inclúyalo en el archivo HTML principal de la aplicación con una etiqueta de script:

<script src="AIRLocalizer.js" type="text/javascript" charset="utf-8"></script>

El código JavaScript que le sigue llamar al objeto air.Localizer.localizer:

<script> 
    var localizer = air.Localizer.localizer; 
</script>

La clase Localizer incluye las siguientes propiedades estáticas:

La arquitectura de localización de HTML lee las versiones localizadas de cadenas de caracteres en los archivos de localización. Un archivo de localización es una colección de valores basados en clave y serializados en un archivo de texto. A veces se le conoce por la palabra paquete.

Cree un subdirectorio del directorio del proyecto de la aplicación llamado “configregional”. (Puede usar otro nombre; consulte Personalización de las opciones de AIR HTML Localizer.) Este directorio incluirá los archivos de localización. Este directorio se conoce como el directorio de paquetes.

Para cada configuración regional que admita la aplicación, cree un subdirectorio del directorio de paquetes. Dé a cada subdirectorio un nombre que corresponda al código de la configuración regional. Por ejemplo: llame al directorio francés “fr” y al directorio inglés “en”. Para definir una configuración regional con códigos de idioma y de país se puede utilizar guión bajo (_). Por ejemplo, el directorio de inglés estadounidense se llamaría “en_us”. (También se puede utilizar un guión normal en lugar de un guión bajo: “en-us”. La arquitectura de localización de HTML admite ambas formas).

No hay límite de la cantidad de archivos de recursos que se pueden añadir a un subdirectorio de configuraciones regionales. Se suele crear un archivo de localización para cada idioma (y colocar el archivo en el directorio de ese idioma). La arquitectura de localización de HTML incluye un método getFile() que permite leer el contenido de un archivo. Consulte Obtención de recursos para una configuración regional específica.

Los archivos que tienen la extensión de archivo .properties se denominan “archivos de propiedades de localización”. Se pueden utilizar para definir pares clave-valor para una configuración regional. Un archivo de propiedades define un valor de cadena en cada línea. En el siguiente ejemplo se define el valor de cadena "Hello in English." para una clave denominada greeting:

greeting=Hello in English.

Un archivo de propiedades que contiene el texto siguiente define seis pares clave-valor:

title=Sample Application 
greeting=Hello in English. 
exitMessage=Thank you for using the application. 
color1=Red 
color2=Green 
color3=Blue

Este ejemplo muestra una versión en inglés del archivo de propiedades, que se guarda en el directorio en.

La versión en francés de este archivo de propiedades se coloca en el directorio fr:

title=Application Example 
greeting=Bonjour en français. 
exitMessage=Merci d'avoir utilisé cette application. 
color1=Rouge 
color2=Vert 
color3=Bleu

Se pueden definir varios archivos de recursos para distintos tipos de información. Por ejemplo: un archivo legal.properties podría contener un texto jurídico estándar (como un aviso de copyright). Quizá se desee utilizar ese recurso en varias aplicaciones. Asimismo, se pueden definir archivos separados que definen el contenido localizado para distintas partes de la interfaz de usuario.

Utilice para estos archivos la codificación UTF-8 para mayor compatibilidad con distintos idiomas.

Cuando la aplicación carga el archivo AIRLocalizer.js, la misma examina las configuraciones regionales que tiene definidas. Estas configuraciones regionales corresponden a los subdirectorios del directorio de paquetes (consulte Definición de paquetes de recursos). Esta lista de configuraciones regionales disponibles se denomina la cadena de configuraciones regionales. El archivo AIRLocalizer.js ordena automáticamente la cadena de configuraciones regionales en función del orden definido en la configuración del sistema operativo. (La propiedad Capabilities.languages enumera los idiomas de la interfaz de usuario del sistema operativo en orden de preferencia).

De este modo, si una aplicación define recursos para las configuraciones regionales "es, "es_ES" y "es_UY", la arquitectura AIR HTML Localizer ordena en consecuencia la cadena de configuraciones regionales. Cuando se inicia una aplicación en un sistema que da aviso de "es" como configuración regional primaria, la cadena de configuraciones regionales se ordena en la secuencia ["es", "es_ES", "es_UY"]. En este caso la aplicación busca recursos primero en el paquete "es" y después en el paquete "es_ES".

Sin embargo, si el sistema da aviso de "es_ES" como configuración regional primaria, la clasificación es ["es_ES", "es", "es_UY"]. En este caso la aplicación busca recursos primero en el paquete "es_ES" y después en el paquete "es".

La aplicación define automáticamente la primera configuración regional de la cadena como la configuración regional predeterminada que se va a utilizar. Puede pedir al usuario que seleccione una configuración regional la primera vez que ejecuta la aplicación. Puede optar por guardar la selección en un archivo de preferencias y en adelante utilizar esa configuración regional cada vez que se inicie la aplicación.

La aplicación puede utilizar cadenas de caracteres de recurso en cualquier configuración regional de la cadena de configuraciones regionales. Si una configuración regional específica no define una cadena de caracteres de recurso, la aplicación utiliza la siguiente cadena de caracteres de recurso que coincida para otras configuraciones regionales definidas en la cadena de dichas configuraciones.

Se puede personalizar la cadena de configuraciones regionales llamando al método setLocaleChain() del objeto Localizer. Consulte Definición de la cadena de configuraciones regionales.

Un elemento de la aplicación puede hacer referencia a un valor de clave de un archivo de propiedades de localización. En el ejemplo siguiente, el elemento title especifica un atributo local_innerHTML. La arquitectura de localización utiliza este atributo para buscar un valor localizado. De forma predeterminada, la arquitectura busca nombres de atributo que empiezan con "local_". La arquitectura actualiza los atributos cuyos nombres coinciden con el texto que sigue a "local_". En este caso, la arquitectura define el atributo innerHTML del elemento title. El atributo innerHTML utiliza el valor definido para la clave mainWindowTitle en el archivo de propiedades predeterminadas (default.properties):

<title local_innerHTML="default.mainWindowTitle"/>

Si la configuración regional actual no define ningún valor que coincida, la arquitectura de localización busca en el resto de la cadena de configuraciones regionales. Utiliza la siguiente configuración regional de la cadena que tenga definido un valor.

En el siguiente ejemplo el texto (el atributo innerHTML) del elemento p utiliza el valor de la clave greeting definido en el archivo de propiedades predeterminadas:

<p local_innerHTML="default.greeting" />

En el siguiente ejemplo el atributo del valor (y el texto mostrado) del elemento input utiliza el valor de la clave btnBlue definido en el archivo de propiedades predeterminadas:

<input type="button" local_value="default.btnBlue" />

Para actualizar el DOM de HTML para que utilice las cadenas de caracteres definidas en la cadena de configuraciones regionales actual, llame al método update() del objeto Localizer. Al llamar al método update() el objeto Localizer analiza el DOM y aplica manipulaciones donde encuentre atributos de localización ("local_..."):

air.Localizer.localizer.update();

Se pueden definir valores tanto para un atributo ("innerHTML", por ejemplo) como para su correspondiente atributo de localización ("local_innerHTML", por ejemplo). En este caso, la arquitectura de localización sólo sobrescribe el valor del atributo si encuentra un valor coincidente en la cadena de localización. Por ejemplo, el siguiente elemento define ambos atributos, value y local_value:

<input type="text" value="Blue" local_value="default.btnBlue"/>

También puede actualizarse un solo elemento DOM en particular. Consulte el apartado siguiente, Actualización de elementos DOM para utilizar la configuración regional actual.

De forma predeterminada, AIR HTML Localizer utiliza "local_" como prefijo para los atributos que definen las opciones de localización para un elemento. Por ejemplo: de forma predeterminada, un atributo local_innerHTML define el nombre del paquete y recurso que se utiliza para el valor innerHTML de un elemento. También de forma predeterminada, un atributo local_value define el nombre del paquete y recurso que se utiliza para el atributo value de un elemento. Se puede configurar AIR HTML Localizer para que utilice otro prefijo de atributo en lugar de "local_". Consulte Personalización de las opciones de AIR HTML Localizer.

Cuando el objeto Localizer actualiza del DOM de HTML, hace que los elementos marcados utilicen valores de atributo basados en las cadenas de caracteres definidas en la actual cadena de configuraciones regionales. Para que el localizador de HTML actualice el DOM de HTML, llame al método update() del objeto Localizer:

air.Localizer.localizer.update();

Para actualizar un solo elemento DOM especificado, páselo como parámetro al método update(). El método update() tiene un solo parámetro, parentNode, que es optativo. Cuando está especificado, el parámetro parentNode define el elemento DOM que se debe localizar. Llamar al método update() y especificar un parámetro parentNode define valores localizados para todos los elementos secundarios que especifican atributos de localización.

Por ejemplo, tomemos el siguiente elemento div:

<div id="colorsDiv"> 
    <h1 local_innerHTML="default.lblColors" ></h1> 
    <p><input type="button" local_value="default.btnBlue" /></p> 
    <p><input type="button" local_value="default.btnRed" /></p> 
    <p><input type="button" local_value="default.btnGreen" /></p> 
</div>

Para actualizar este elemento de modo que utilice cadenas de caracteres localizadas en la cadena de configuraciones regionales actual, use el código JavaScript siguiente:

var divElement = window.document.getElementById("colorsDiv"); 
air.Localizer.localizer.update(divElement);

Si no se encuentra un valor de clave en la cadena de configuraciones regionales, la arquitectura de localización define como valor de atributo el valor del atributo "local_". Por ejemplo: supongamos que en el ejemplo anterior la arquitectura de localización no encuentra ningún valor para la clave lblColors (en ninguno de los archivos default.properties de la cadena de configuraciones regionales). En este caso, utiliza "default.lblColors" como el valor de innerHTML. El uso de este valor indica (al desarrollador) que faltan recursos.

El método update() distribuye un evento resourceNotFound cuando no encuentra un recurso en la cadena de configuraciones regionales. La constante air.Localizer.RESOURCE_NOT_FOUND define la cadena "resourceNotFound". El evento tiene tres propiedades: bundleName, resourceName y locale. La propiedad bundleName es el nombre del paquete en el que no se encuentra el recurso. La propiedad resourceName es el nombre del recurso no disponible. La propiedad locale es el nombre de la configuración regional en la que no se encuentra el recurso.

El método update() distribuye un evento bundleNotFound cuando no encuentra el paquete especificado. La constante air.Localizer.BUNDLE_NOT_FOUND define la cadena "bundleNotFound". El evento tiene tres propiedades: bundleName y locale. La propiedad bundleName es el nombre del paquete en el que no se encuentra el recurso. La propiedad locale es el nombre de la configuración regional en la que no se encuentra el recurso.

El método update() funciona de modo asíncrono (y distribuye los eventos resourceNotFound y bundleNotFound de forma asíncrona). El siguiente código define detectores para los eventos resourceNotFound y bundleNotFound:

air.Localizer.localizer.addEventListener(air.Localizer.RESOURCE_NOT_FOUND, rnfHandler); 
air.Localizer.localizer.addEventListener(air.Localizer.BUNDLE_NOT_FOUND, rnfHandler); 
air.Localizer.localizer.update(); 
function rnfHandler(event) 
{ 
    alert(event.bundleName + ": " + event.resourceName + ":." + event.locale); 
} 
function bnfHandler(event) 
{ 
    alert(event.bundleName + ":." + event.locale); 
}

El método setBundlesDirectory() del objeto Localizer permite personalizar la ruta del directorio de paquetes. El método setLocalAttributePrefix() del objeto Localizer permite personalizar la ruta del directorio de paquetes y el valor de atributo que utiliza el Localizer.

El directorio de paquetes predeterminado se define como el subdirectorio de configuraciones regionales del directorio de la aplicación. Para especificar otro directorio, llame al método setBundlesDirectory() del objeto Localizer. Este método utiliza un parámetro, path, que es la ruta al directorio de paquetes deseado, en forma de cadena de caracteres. El parámetro path puede tener cualquiera de los valores siguientes:

En el siguiente ejemplo, el código define como directorio de paquetes un subdirectorio "languages" del directorio de almacenamiento de la aplicación (y no el directorio de la aplicación):

air.Localizer.localizer.setBundlesDirectory("languages");

Pase una ruta válida como parámetro path. De lo contrario, el método emite una excepción BundlePathNotFoundError. Este error tiene a "BundlePathNotFoundError" como su propiedad name y su propiedad message especifica la ruta no válida.

De forma predeterminada, AIR HTML Localizer utiliza "local_" como prefijo para los atributos que definen las opciones de localización para un elemento. Por ejemplo, el atributo local_innerHTML define el nombre del paquete y recurso que se utiliza para el valor innerHTML del siguiente elemento input:

<p local_innerHTML="default.greeting" />

El método setLocalAttributePrefix() del objeto Localizer permite utilizar otro prefijo de atributo en lugar de "local_". Este método estático utiliza un parámetro, que es la cadena de caracteres que se desea utilizar como prefijo de atributo. En el siguiente ejemplo, el código define la arquitectura de localización para que utilice "loc_" como prefijo de atributo:

air.Localizer.localizer.setLocalAttributePrefix("loc_");

Se puede personalizar el prefijo de atributo que utiliza la arquitectura de localización. Puede ser conveniente personalizar el prefijo si el valor predeterminado ("local_") está en conflicto con el nombre de otro atributo que se utilice en el código. Cuando llame a este método, asegúrese de utilizar caracteres válidos para los atributos de HTML. (Por ejemplo, el valor no puede contener un carácter de espacio en blanco).

Para obtener más información sobre el uso de atributos de localización en elementos HTML, consulte Actualización de los elementos DOM con contenido localizado.

Las opciones de directorio de paquetes y prefijo de atributo no persisten entre distintas sesiones de la aplicación. Si utiliza opciones personalizadas para el directorio de paquetes o el prefijo de atributo, asegúrese de configurarlas cada vez que inicie la aplicación.

Cuando se carga el código de AIRLocalizer.js, define automáticamente la cadena de configuraciones regionales predeterminada. Las configuraciones regionales disponibles en el directorio de paquetes y la configuración de idiomas del sistema operativo definen esta cadena de configuraciones regionales. (Para obtener más información, consulte Gestión de cadenas de configuraciones regionales).

Se puede modificar la cadena de configuraciones regionales llamando al método estático setLocaleChain() del objeto Localizer. Por ejemplo, puede ser conveniente llamar a este método si el usuario indica una preferencia para un idioma concreto. El método setLocaleChain() utiliza un solo parámetro, chain, que es un conjunto de configuraciones regionales, por ejemplo ["fr_FR","fr","fr_CA"]. El orden de las configuraciones locales en el conjunto define el orden en que la arquitectura busca recursos (en operaciones posteriores). Si no se encuentra un recurso para la primera configuración regional de la cadena, sigue buscando en los recursos de la otra configuración regional. Si falta el argumento chain, o si no es un conjunto o es un conjunto vacío, la función falla y emite una excepción IllegalArgumentsError.

El método estático getLocaleChain() del objeto Localizer devuelve un conjunto que enumera las configuraciones regionales de la cadena de configuraciones regionales actual.

El siguiente código lee la cadena de configuraciones regionales actual y añade dos configuraciones regionales francesas a la cabeza de la cadena:

var currentChain = air.Localizer.localizer.getLocaleChain(); 
newLocales = ["fr_FR", "fr"]; 
air.Localizer.localizer.setLocaleChain(newLocales.concat(currentChain));

El método setLocaleChain() distribuye un evento "change" cuando actualiza la cadena de configuraciones regionales. La constante air.Localizer.LOCALE_CHANGE define la cadena "change". El evento tiene una propiedad, localeChain, que es un conjunto de códigos de configuración regional en la nueva cadena de configuraciones regionales. El siguiente código define un detector para este evento:

var currentChain = air.Localizer.localizer.getLocaleChain(); 
newLocales = ["fr_FR", "fr"]; 
localizer.addEventListener(air.Localizer.LOCALE_CHANGE, changeHandler); 
air.Localizer.localizer.setLocaleChain(newLocales.concat(currentChain)); 
function changeHandler(event) 
{ 
    alert(event.localeChain); 
}

La propiedad estática air.Localizer.ultimateFallbackLocale representa la configuración regional que se utiliza cuando la aplicación no admite ninguna de las preferencias del usuario. El valor predeterminado es "en". Se lo puede cambiar a otra configuración regional, como en el código siguiente:

air.Localizer.ultimateFallbackLocale = "fr";

bundleName

resourceName

templateArgs

locale

La arquitectura de localización puede actualizar los atributos marcados del DOM de HTML. Hay también otras formas de utilizar cadenas localizadas. Por ejemplo, se puede utilizar una cadena de caracteres en HTML generado de forma dinámica o como valor de parámetro en una llamada a una función. En el siguiente ejemplo, el código llama a la función alert() con la cadena de caracteres definida en el recurso error114 del archivo de propiedades predeterminadas de la configuración regional fr_FR:

alert(air.Localizer.localizer.getString("default", "error114", null, "fr_FR"));

El método getString() distribuye un evento resourceNotFound cuando no encuentra el recurso en el paquete especificado. La constante air.Localizer.RESOURCE_NOT_FOUND define la cadena "resourceNotFound". El evento tiene tres propiedades: bundleName, resourceName y locale. La propiedad bundleName es el nombre del paquete en el que no se encuentra el recurso. La propiedad resourceName es el nombre del recurso no disponible. La propiedad locale es el nombre de la configuración regional en la que no se encuentra el recurso.

El método getString() distribuye un evento bundleNotFound cuando no encuentra el paquete especificado. La constante air.Localizer.BUNDLE_NOT_FOUND define la cadena "bundleNotFound". El evento tiene tres propiedades: bundleName y locale. La propiedad bundleName es el nombre del paquete en el que no se encuentra el recurso. La propiedad locale es el nombre de la configuración regional en la que no se encuentra el recurso.

El método getString() funciona de modo asíncrono (y distribuye los eventos resourceNotFound y bundleNotFound de forma asíncrona). El siguiente código define detectores para los eventos resourceNotFound y bundleNotFound:

air.Localizerlocalizer.addEventListener(air.Localizer.RESOURCE_NOT_FOUND, rnfHandler); 
air.Localizerlocalizer.addEventListener(air.Localizer.BUNDLE_NOT_FOUND, bnfHandler); 
var str = air.Localizer.localizer.getString("default", "error114", null, "fr_FR"); 
function rnfHandler(event) 
{ 
    alert(event.bundleName + ": " + event.resourceName + ":." + event.locale); 
} 
function bnfHandler(event) 
{ 
    alert(event.bundleName + ":." + event.locale); 
}

El método getResourceBundle() del objeto Localizer devuelve un paquete especificado para una configuración regional determinada. El valor devuelto del método es un objeto con propiedades que coinciden con las claves del paquete. (Si la aplicación no puede encontrar el paquete especificado, el método devuelve null.)

locale

bundleName

var aboutWin = window.open(); 
var bundle = localizer.getResourceBundle("fr", "default"); 
aboutWin.document.write(bundle.str1); 
aboutWin.document.write("<br/>"); 
aboutWin.document.write(bundle.str2); 
aboutWin.document.write("<br/>");

El método getResourceBundle() distribuye un evento bundleNotFound cuando no encuentra el paquete especificado. La constante air.Localizer.BUNDLE_NOT_FOUND define la cadena "bundleNotFound". El evento tiene tres propiedades: bundleName y locale. La propiedad bundleName es el nombre del paquete en el que no se encuentra el recurso. La propiedad locale es el nombre de la configuración regional en la que no se encuentra el recurso.

resourceFileName

templateArgs

<html> 
<body>Hello, {0}. You have {1} new messages.</body> 
</html> 

<html> 
<body>Hello, Raúl. You have 4 new messages. </body> 
</html> 

locale

En el siguiente ejemplo, el código llama al método document.write() utilizando el contenido del archivo about.html file de la configuración regional fr:

var aboutWin = window.open(); 
var aboutHtml = localizer.getFile("about.html", null, "fr"); 
aboutWin.document.close(); 
aboutWin.document.write(aboutHtml);

El método getFile() distribuye un evento fileNotFound cuando no encuentra un recurso en la cadena de configuraciones regionales. La constante air.Localizer.FILE_NOT_FOUND define la cadena "resourceNotFound". El método getFile() funciona de modo asíncrono (y distribuye el evento fileNotFound de forma asíncrona). El evento tiene tres propiedades: bundleName y locale. La propiedad fileName es el nombre del archivo que no se encuentra. La propiedad locale es el nombre de la configuración regional en la que no se encuentra el recurso. El siguiente código define un detector para este evento:

air.Localizer.localizer.addEventListener(air.Localizer.FILE_NOT_FOUND, fnfHandler); 
air.Localizer.localizer.getFile("missing.html", null, "fr"); 
function fnfHandler(event) 
{ 
    alert(event.fileName + ": " + event.locale); 
}