Localisation de contenu HTML à l’aide de la structure de localisation HTML d’AIR

Pour utiliser la structure de localisation, copiez le fichier AIRLocalizer.js dans votre projet. Incluez-le ensuite dans le fichier HTML principal de l’application, à l’aide d’une balise script :

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

Vous pouvez ensuite appeler l’objet air.Localizer.localizer par le biais de code JavaScript :

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

La classe Localizer comprend les propriétés statiques suivantes :

La structure de localisation HTML lit les versions localisées des chaînes dans des fichiers de localisation. Un fichier de localisation est un ensemble de valeurs basées sur des clés, sérialisées dans un fichier de texte. Ce type de fichier est parfois appelé un regroupement.

Créez dans le répertoire de projet de votre application un sous-répertoire que vous nommerez locale. (Vous pouvez utiliser un autre nom ; voir Personnalisation des paramètres de la structure de localisation HTML d’AIR.) Ce répertoire contient les fichiers de localisation et est appelé le répertoire de regroupements.

Créez un sous-répertoire dans le répertoire de regroupements pour chaque jeu de paramètres régionaux pris en charge par votre application. Attribuez à chaque sous-répertoire un nom correspondant au code du jeu de paramètres régionaux. Par exemple, nommez le répertoire français « fr » et le répertoire anglais « en ». Vous pouvez utiliser un trait de soulignement (_) pour définir un jeu de paramètres régionaux constitué d’une langue et d’un code de pays. Par exemple, nommez le répertoire anglais américain « en_us ». Vous pouvez éventuellement remplacer le trait de soulignement par un tiret (« en-us », par exemple). La structure de localisation HTML prend ces deux formats en charge.

Libre à vous d’ajouter tout nombre de fichiers de ressources à un sous-répertoire de jeu de paramètres régionaux. En règle générale, vous créez un fichier de localisation par langue (et le placez dans le répertoire correspondant à celle-ci). La structure de localisation HTML comprend une méthode getFile() qui vous permet de lire le contenu d’un fichier (voir Extraction de ressources d’un jeu de paramètres régionaux spécifique).

Les fichiers dotés de l’extension .properties constituent des fichiers de propriétés de localisation. Ils permettent de définir les paires clé-valeur d’un jeu de paramètres régionaux. Un fichier de propriétés définit une valeur chaîne sur chaque ligne. Ainsi, l’exemple suivant attribue la valeur chaîne « Hello in English. » à une clé nommée greeting :

greeting=Hello in English.

Un fichier de propriétés contenant le texte suivant définit six paires clé-valeur :

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

Cet exemple illustre une version anglaise du fichier de propriétés, à stocker dans le répertoire en.

Une version française de ce fichier de propriétés est placée dans le répertoire fr :

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

Vous pouvez définir plusieurs fichiers de ressources pour différents types d’information. Imaginons un fichier nommé legal.properties, qui contient un modèle de texte juridique (tel un avis de copyright). Libre à vous de réutiliser cette ressource dans diverses applications. Vous pouvez de même créer plusieurs fichiers définissant du contenu localisé pour différentes parties de l’interface utilisateur.

Utilisez le codage UTF-8 pour ces fichiers afin de prendre en charge plusieurs langues.

Lorsque votre application charge le fichier AIRLocalizer.js, il examine les jeux de paramètres régionaux définis dans celle-ci. Ces jeux correspondent aux sous-répertoires du répertoire de regroupements (voir Définition de regroupements de ressources). La liste des jeux de paramètres régionaux disponibles est appelée chaînage de jeux de paramètres régionaux. Le fichier AIRLocalizer.js trie automatiquement le chaînage de jeux de paramètres régionaux en fonction de l’ordre de préférence défini par les paramètres du système d’exploitation. (La propriété Capabilities.languages trie les langues d’interface utilisateur du système d’exploitation dans l’ordre de préférence.)

Par conséquent, si une application définit des ressources pour "en", "en_US" et "en_UK", la structure de localisation HTML d’AIR trie le chaînage de jeux de paramètres régionaux de manière appropriée. Lorsqu’une application démarre sur un système qui indique que le jeu de paramètres régionaux principal correspond à "en", le chaînage est trié de la façon suivante : ["en", "en_US", "en_UK"]. Dans ce cas, l’application recherche des ressources dans le regroupement « en » en premier, puis dans le regroupement "en_US".

Cependant, si le système indique que le jeu de paramètres régionaux principal correspond à "en_US", le tri devient ["en_US", "en", "en_UK"]. Dans ce cas, l’application recherche des ressources dans le regroupement "en_US" en premier, puis dans le regroupement "en".

Par défaut, l’application définit le premier jeu de paramètres régionaux du chaînage en tant que jeu à utiliser par défaut. Vous pouvez inviter l’utilisateur à sélectionner un jeu de paramètres régionaux lors de la première exécution de l’application. Vous pouvez ensuite choisir de stocker la sélection dans un fichier de préférences et utiliser ce jeu de paramètres régionaux lors de démarrages suivants.

Votre application peut utiliser des chaînes de ressource de tout jeu de paramètres régionaux du chaînage. Si un jeu de paramètres régionaux spécifique ne définit pas une chaîne de ressource, l’application utilise la chaîne de ressource correspondante suivante d’autres jeux de paramètres régionaux du chaînage.

Vous pouvez personnaliser le chaînage de jeux de paramètres régionaux en appelant la méthode setLocaleChain() de l’objet Localizer. Voir Définition du chaînage de jeux de paramètres régionaux

Un élément de l’application peut référencer une valeur de clé dans un fichier de propriétés de localisation. Ainsi, l’élément title de l’exemple ci-dessous spécifie un attribut local_innerHTML. La structure de localisation utilise cet attribut pour rechercher une valeur localisée. Par défaut, la structure recherche des attributs dont le nom commence par « local_ ». Elle met à jour les attributs portant un nom correspondant au texte suivant « local_ ». Dans ce cas, elle définit l’attribut innerHTML de l’élément title. L’attribut innerHTML utilise la valeur définie pour la clé mainWindowTitle dans le fichier de propriétés par défaut (default.properties) :

<title local_innerHTML="default.mainWindowTitle"/>

Si le jeu de paramètres régionaux en cours ne définit pas de valeur correspondante, la structure de localisation examine le reste du chaînage de jeux. Elle utilise le jeu suivant du chaînage pour lequel une valeur est définie.

Dans l’exemple suivant, le texte (attribut innerHTML) de l’élément p utilise la valeur de la clé greeting définie dans le fichier de propriétés par défaut :

<p local_innerHTML="default.greeting" />

Dans l’exemple suivant, l’attribut value (et le texte affiché) de l’élément input utilise la valeur de la clé btnBlue définie dans le fichier de propriétés par défaut :

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

Pour mettre à jour le DOM HTML afin qu’il utilise les chaînes définies dans le chaînage de jeu de paramètres régionaux en cours, appelez la méthode update() de l’objet Localizer. L’appel de la méthode update() force l’objet Localizer à analyser le DOM et à appliquer des manipulations lorsqu’il détecte des attributs de localisation (« local_... ») :

air.Localizer.localizer.update();

Vous pouvez définir des valeurs pour un attribut (tel que « innerHTML ») et pour l’attribut de localisation correspondant (tel que « local_innerHTML »). Dans ce cas, la structure de localisation ne remplace la valeur de l’attribut que si elle détecte une valeur correspondante dans le chaînage de localisation. Par exemple, l’élément suivant définit les attributs value et local_value :

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

Vous pouvez aussi vous contenter de mettre à jour un élément DOM spécifique. Pour plus d’informations, voir Mise à jour d’éléments DOM afin qu’ils utilisent le jeu de paramètres régionaux en cours

Par défaut, la structure de localisation HTML d’AIR applique le préfixe « local_ » aux attributs définissant des paramètres de localisation pour un élément. Ainsi, un attribut local_innerHTML définit par défaut le regroupement et le nom de ressource utilisés pour la valeur innerHTML d’un élément. De même, un attribut local_value définit par défaut le regroupement et le nom de ressource utilisés pour l’attribut value d’un élément. Vous pouvez configurer la structure de localisation de sorte à utiliser un préfixe autre que « local_ ». Voir Personnalisation des paramètres de la structure de localisation HTML d’AIR.

Lorsque l’objet Localizer met à jour le DOM HTML, les éléments marqués doivent utiliser des valeurs d’attribut basées sur des chaînes définies dans le chaînage de jeux de paramètres régionaux en cours. Pour que la structure de localisation HTML mette à jour le DOM HTML, appelez la méthode update() de l’objet Localizer :

air.Localizer.localizer.update();

Pour mettre à jour un élément DOM spécifique seulement, transmettez-le en tant que paramètre à la méthode update(). La méthode update() possède un seul paramètre, parentNode, qui est facultatif. Lorsqu’il est spécifié, le paramètre parentNode définit l’élément DOM à localiser. L’appel de la méthode update() en incluant le paramètre parentNode définit des valeurs localisées pour tous les éléments enfant qui spécifient des attributs de localisation.

Soit, par exemple, l’élément div ci-dessous :

<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>

Pour mettre cet élément à jour afin qu’il utilise les chaînes localisées définies dans le chaînage de jeu de paramètres régionaux en cours, utilisez le code JavaScript suivant :

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

Si le chaînage de jeux de paramètres régionaux ne contient pas de valeur de clé, la structure de localisation définit la valeur de l’attribut sur la valeur de l’attribut « local_ ». Ainsi, imaginons que dans l’exemple précédent, la structure de localisation n’a pas trouvé de valeur pour la clé lblColors (dans aucun des fichiers default.properties du chaînage de jeux de paramètres régionaux). Dans ce cas, elle attribue la valeur "default.lblColors" à l’attribut innerHTML. L’utilisation de cette valeur indique une absence de ressources (au développeur).

La méthode update() distribue un événement resourceNotFound lorsqu’une ressource est introuvable dans le chaînage de jeux de paramètres régionaux. La constante air.Localizer.RESOURCE_NOT_FOUND définit la chaîne "resourceNotFound". L’événement possède trois propriétés : bundleName, resourceName et locale. La propriété bundleName représente le nom du regroupement dans lequel la ressource est introuvable. La propriété resourceName représente le nom de la ressource introuvable. La propriété locale représente le nom du jeu de paramètres régionaux dans lequel la ressource est introuvable.

La méthode update() distribue un événement bundleNotFound lorsque le regroupement spécifié est introuvable. La constante air.Localizer.BUNDLE_NOT_FOUND définit la chaîne "bundleNotFound". L’événement possède deux propriétés : bundleName et locale. La propriété bundleName représente le nom du regroupement introuvable. La propriété locale représente le nom du jeu de paramètres régionaux dans lequel la ressource est introuvable.

La propriété update() s’exécute en mode asynchrone (et distribue des événements resourceNotFound et bundleNotFound de manière asynchrone). Le code suivant définit des écouteurs pour les événements resourceNotFound et 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); 
}

La méthode setBundlesDirectory() de l’objet Localizer vous permet de personnaliser le chemin d’accès au répertoire de regroupements. La méthode setLocalAttributePrefix() de l’objet Localizer vous permet de personnaliser le chemin d’accès au répertoire de regroupements et la valeur d’attribut utilisée par l’objet.

Le répertoire de regroupements par défaut correspond au sous-répertoire de jeux de paramètres régionaux du répertoire d’application. Vous pouvez spécifier un autre répertoire en appelant la méthode setBundlesDirectory() de l’objet Localizer. Cette méthode gère un paramètre unique, path, qui représente sous forme de chaîne le chemin d’accès au répertoire de regroupements souhaité. Le paramètre path prend en charge les valeurs suivantes :

Par exemple, le code suivant définit le répertoire de regroupements sur le sous-répertoire languages du répertoire de stockage de l’application (répertoire d’application) :

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

Définissez le paramètre path sur un chemin valide. Sinon, la méthode renvoie une exception BundlePathNotFoundError. « BundlePathNotFoundError » correspond à la propriété name de cette erreur, dont la propriété message spécifie le chemin non valide.

Par défaut, la structure de localisation HTML d’AIR applique le préfixe « local_ » aux attributs définissant des paramètres de localisation pour un élément. Par exemple, l’attribut local_innerHTML définit le regroupement et le nom de ressource utilisés pour la valeur innerHTML de l’élément input suivant :

<p local_innerHTML="default.greeting" />

La méthode setLocalAttributePrefix() de l’objet Localizer vous permet d’utiliser un préfixe d’attribut autre que « local_ ». Cette méthode statique gère un paramètre unique, qui correspond à la chaîne à utiliser comme préfixe d’attribut. Par exemple, le code suivant force la structure de localisation à utiliser « loc_ » comme préfixe d’attribut :

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

Vous pouvez personnaliser le préfixe d’attribut utilisé par la structure de localisation. Vous souhaiterez peut-être personnaliser le préfixe si la valeur par défaut (« local_ ») crée un conflit avec le nom d’un autre attribut utilisé par le code. Lorsque vous appelez cette méthode, veillez à utiliser des caractères valides pour les attributs HTML. (La valeur ne doit pas contenir d’espaces, par exemple.)

Pour plus d’informations sur l’utilisation d’attributs de localisation dans des éléments HTML, voir Mise à jour d’éléments DOM avec du contenu localisé.

Les paramètres relatifs au répertoire de regroupements et au préfixe d’attribut ne sont pas persistants d’une session d’application à une autre. Si vous utilisez des paramètres personnalisés, veillez donc à les définir à chaque initiation de l’application.

Lorsque vous chargez le code AIRLocalizer.js, il définit automatiquement le chaînage de jeux de paramètres régionaux par défaut. Les jeux de paramètres régionaux disponibles dans le répertoire de regroupements et les paramètres de langue du système d’exploitation définissent ce chaînage (pour plus d’informations voir Gestion des chaînages de jeux de paramètres régionaux).

Vous pouvez modifier le chaînage de jeux de paramètres régionaux en appelant la méthode statique setLocaleChain() de l’objet Localizer. Ainsi, vous souhaiterez peut-être appeler cette méthode si l’utilisateur indique qu’il préfère utiliser une langue spécifique. La méthode setLocaleChain() gère un paramètre unique, chain, qui correspond à un tableau de jeux de paramètres régionaux, tel que ["fr_FR","fr","fr_CA"]. L’ordre des jeux dans le tableau détermine l’ordre dans lequel la structure recherche ultérieurement des ressources. Si une ressource est absente du premier jeu du chaînage, la structure continue la recherche dans les autres jeux. Si l’argument chain est absent, n’est pas un tableau ou est un tableau vide, la fonction échoue et renvoie une exception IllegalArgumentsError.

La méthode statique getLocaleChain() de l’objet Localizer renvoie un tableau répertoriant les jeux de paramètres régionaux du chaînage en cours.

Le code suivant lit le chaînage en cours et ajoute deux jeux de paramètres régionaux français au début :

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

La méthode setLocaleChain() distribue un événement « change » lorsqu’elle met à jour le chaînage de jeux de paramètres régionaux. La constante air.Localizer.LOCALE_CHANGE définit la chaîne « change ». L’événement possède une propriété unique, localeChain, un tableau des codes de jeux de paramètres régionaux que comprend le nouveau chaînage. Le code suivant définit un écouteur pour cet événement :

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 propriété statique air.Localizer.ultimateFallbackLocale représente le jeu de paramètres régionaux utilisé lorsque l’application ne prend pas en charge de préférences utilisateur. La valeur par défaut est "en". Vous pouvez définir un autre jeu de paramètres régionaux, comme illustré ci-dessous :

air.Localizer.ultimateFallbackLocale = "fr";

bundleName

resourceName

templateArgs

locale

La structure de localisation peut mettre à jour des attributs DOM HTML marqués. Vous pouvez cependant utiliser les chaînes localisées autrement. Ainsi, vous pouvez utiliser une chaîne dans du contenu HTML généré dynamiquement ou en tant que valeur de paramètre dans un appel de fonction. Par exemple, le code suivant appelle la fonction alert() avec la chaîne définie dans la ressource error114 du fichier de propriété par défaut du jeu de paramètres régionaux fr_FR :

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

La méthode getString() distribue un événement resourceNotFound si la ressource est introuvable dans le regroupement spécifié. La constante air.Localizer.RESOURCE_NOT_FOUND définit la chaîne "resourceNotFound". L’événement possède trois propriétés : bundleName, resourceName et locale. La propriété bundleName représente le nom du regroupement dans lequel la ressource est introuvable. La propriété resourceName représente le nom de la ressource introuvable. La propriété locale représente le nom du jeu de paramètres régionaux dans lequel la ressource est introuvable.

La méthode getString() distribue un événement bundleNotFound lorsque le regroupement spécifié est introuvable. La constante air.Localizer.BUNDLE_NOT_FOUND définit la chaîne "bundleNotFound". L’événement possède deux propriétés : bundleName et locale. La propriété bundleName représente le nom du regroupement introuvable. La propriété locale représente le nom du jeu de paramètres régionaux dans lequel la ressource est introuvable.

La méthode getString() s’exécute en mode asynchrone (et distribue les événements resourceNotFound et bundleNotFound en mode asynchrone). Le code suivant définit des écouteurs pour les événements resourceNotFound et 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); 
}

La méthode getResourceBundle() de l’objet Localizer renvoie le regroupement spécifié pour un jeu de paramètres régionaux donné. La valeur renvoyée de la méthode est un objet dont les propriétés correspondent aux clés du regroupement. (Si l’application ne trouve pas le regroupement spécifié, la méthode renvoie 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/>");

La méthode getResourceBundle() distribue un événement bundleNotFound lorsque le regroupement spécifié est introuvable. La constante air.Localizer.BUNDLE_NOT_FOUND définit la chaîne "bundleNotFound". L’événement possède deux propriétés : bundleName et locale. La propriété bundleName représente le nom du regroupement introuvable. La propriété locale représente le nom du jeu de paramètres régionaux dans lequel la ressource est introuvable.

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

Par exemple, le code suivant appelle la méthode document.write() à l’aide du contenu du fichier about.html du jeu de paramètres régionaux fr :

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

La méthode getFile() distribue un événement fileNotFound lorsqu’une ressource est introuvable dans le chaînage de jeux de paramètres régionaux. La constante air.Localizer.FILE_NOT_FOUND définit la chaîne "fileNotFound". La méthode getFile() s’exécute en mode asynchrone (et distribue l’événement fileNotFound de manière asynchrone). L’événement possède deux propriétés : fileName et locale. La propriété fileName représente le nom du fichier introuvable. La propriété locale représente le nom du jeu de paramètres régionaux dans lequel la ressource est introuvable. Le code suivant définit un écouteur pour cet événement :

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); 
}