Localisation d'une extension

Introduction

Cet article reprend et développe les précédents exemples de création d'extension en ajoutant le support de localisation à notre extension stock watcher. En quelques étapes faciles vous rendrez votre extension facile à localiser en diverses langues sans qu'il soit nécessaire d'éditer de fichiers XUL ou JavaScript.

Si vous n'avez pas encore créé d'extension, ou si vous souhaitez vous rafraîchir la mémoire, jetez un coup d'œil aux articles précédents de la même série :

Télécharger l'exemple

Vous pouvez télécharger le code de l'exemple utilisé dans cet article, de manière à l'avoir sous les yeux pendant la lecture, ou bien pour l'utiliser comme point de départ pour votre propre extension.

https://developer.mozilla.org/samples...ockwatcher.zip

Créer les fichiers de localisation nécessaires

Chaque fichier XUL qui inclut une interface utilisateur de votre extension devrait avoir un fichier de locale correspondant dans le répertoirelocale

Chaque fichier de locale dresse la liste des entités correspondant aux chaînes ellles-mêmes. Le dialogue d'options, par exemple, dont le fichier XUL est options.xul, a un fichier correspondant options.dtd qui ressemble à ceci :

 <!ENTITY options_window_title "StockWatcher 2 Preferences">
 <!ENTITY options_symbol.label "Stock to watch: ">

Le nom d'entité "options_window_title" fait référence à la chaîne "StockWatcher 2 Preferences", qui est utilisée comme titre de la fenêtre des options.

Le fichier stockwatcher2.dtd contient de même les entités correspondant au fichier stockwatcher2.xul file:

 <!ENTITY panel_loading "Loading...">
 <!ENTITY menu_refresh_now.label "Refresh Now">
 <!ENTITY menu_apple.label "Apple (AAPL)">
 <!ENTITY menu_google.label "Google (GOOG)">
 <!ENTITY menu_microsoft.label "Microsoft (MSFT)">
 <!ENTITY menu_yahoo.label "Yahoo (YHOO)">

Mettre à jour les fichiers XUL

Chaque fichier XUL doit faire référence à son fichier de locale correspondant. Nous devons aussi mettre à jour le code pour utiliser les entités et non les chaînes de caractères, afin que les substitutions s'opèrent en utilisant la locale active.

Pour faire référence au fichier de locale correspondant à un fichier XUL donné, nous devons ajouter une ligne au fichier XUL. Dans options.xul, nous ajoutons cette ligne :

 <!DOCTYPE window SYSTEM "chrome://stockwatcher2/locale/options.dtd">

Nous ajoutons une ligne du même type au fichier stockwatcher.xul :

 <!DOCTYPE overlay SYSTEM "chrome://stockwatcher2/locale/stockwatcher2.dtd">

Notez que les URLs des fichiers DTD ne mentionnnent pas le nom de la localisation à utiliser. Le mot "locale" qui apparaît dans ces URLs permet de diriger automatiquement vers le répertoire adéquat, en fonction du choix de locale de l'utilisateur.

Ensuite nous remplaçons simplement chaque chaîne de texte de nos fichiers XUL par l'entité correspondante. Par exemple, dans stockwatcher2.xul, nous transformons cette ligne :

 <menuitem label="Refresh Now" oncommand="StockWatcher.refreshInformation()"/>

 <menuitem label="&menu_refresh_now.label;" oncommand="StockWatcher.refreshInformation()"/>

Reproduire cette substitution pour toutes les chaînes utilisées dans tous les fichiers XUL.

Mettre à jour le fichier chrome manifest

Pour indiquer à Firefox l'existence de fichiers de locale, nous devons réviser notre fichier chrome.manifest file, en ajoutant une ligne comme celle-là pour chaque localisation :

 locale stockwatcher2 en-US chrome/locale/en-US/

Elle indique à Firefox que la locale en-US est située dans le répertoire chrome/locale/en-US.

Localiser les chaînes du code JavaScript

Si notre code JavaScript contient des chaînes de caractères qui doivent être localisées, comme c'est le cas dans notre exemple avec stock watcher, nous devons également les rendre localisables. C'est possible en transférant ces chaînes dans unstring bundle . Lesstring bundles sont créés grâce à un fichier properties qui liste les variables renvoyant aux chaînes de caractères. Pour une explication détaillée de ce processus, voir Tutoriel XUL : fichiers de propriétés.

Créer un fichier properties

La première chose à faire est de créer un fichier properties pour les chaînes utilisées dans le code JavaScript de stockwatcher2.js :

changeString=Chg:
openString=Open:
lowString=Low:
highString=High:
volumeString=Vol:

Le fichier stockwatcher2.properties ci-dessus attribue à 5 variables (changeString, openString, lowString, highString, et volumeString) les textes en anglais correspondants.

Créer lestring bundle

L'étape suivante consiste à modifier le fichier stockwatcher2.xul pour faire référence à ce fichier properties. Nous créons pour cela unstring bundle , en utilisant le code XML suivant :

 <stringbundleset id="stringbundleset">
   <stringbundle id="string-bundle" src="chrome://stockwatcher2/locale/stockw...er2.properties"/>
 </stringbundleset>

Un nouveau string bundle est ainsi créé avec son identifiant (ID) ; ses variables et leur valeur (= les chaînes de caractères correspondantes) seront récupérées dans le fichier stockwatcher2.properties que nous avons déjà créé.

Mettre à jour le code JavaScript

Nous voilà prêts pour réviser le code JavaScript afin qu'il charge les chaînes depuis lestring bundle au lieu d'utiliser directement les chaînes d'origine. Ceci implique la réécriture de la fonction refreshInformation() pour charger les chaînes, ainsi que la fonction incluse infoReceived() pour que soient utilisées les chaînes localisées et chargées et non les chaînes de départ.

Nous ajoutons à la fonction refreshInformation() le code suivant :

 stringsBundle = document.getElementById("string-bundle");
 var changeString = stringsBundle.getString('changeString') + " ";
 var openString = stringsBundle.getString('openString') + " ";
 var lowString = stringsBundle.getString('lowString') + " ";
 var highString = stringsBundle.getString('highString') + " ";
 var volumeString = stringsBundle.getString('volumeString') + " ";

Ce code fait référence austring bundle en appelant document.getElementById(), et en précisant l'ID "string-bundle". Puis il va chercher toutes les chaînes dont nous avons besoin dans le bundle, une à une, en faisant appel à la méthode getString() pour demander la variable correspondant à chaque chaîne.

Dans notre cas, nous ajoutons également un espace à la fin de chaque chaîne. Il en va seulement ainsi pour l'extension que nous prenons pour exemple, il ne s'agit pas d'une nécessité pour vous.

Ensuite nous replaçons chaque occurrence de la chaîne initiale par la variable appropriée :

 samplePanel.tooltipText = changeString + fieldArray[4] + " | " +
     openString + fieldArray[5] + " | " +
 lowString + fieldArray[6] + " | " +
     highString + fieldArray[7] + " | " +
     volumeString + fieldArray[8];

Ajouter d'autres localisations

Pour ajouter une autre localisation (=une autre langue), il suffit d'écrire une nouvelle ligne au chrome manifest avec la référence de la nouvelle langue. Par exemple, pour ajouter une localisation française, vous écrirez :

 locale stockwatcher2 fr chrome/locale/fr/

Puis créez un sous-répertoire chrome/locale/fr et ajoutez tous les fichiers DTD nécessaires; dans notre exemple, options.dtd et stockwatcher2.dtd. Ces fichiers doivent inclure les entités correspondant aux chaînes utilisées dans l'extension, avec leur traduction française bien entendu.

De même, si nous avons des fichiers properties contenant des chaînes localisées du code JavaScript, nous devons créer des versions françaises de ces fichiers properties dans le répertoire chrome/locale/fr. Seules les chaînes de caractères doivent être localisées ; les noms d'entités doivent être strictement les mêmes pour toutes les localisations.