Localisation

Cette traduction est incomplète. Aidez à traduire cet article depuis l'anglais.

Le SDK supporte la localisation des chaînes figurant dans:

Il ne le fait pas dans le CSS, les scripts anexe, ou les champs titre et description qui apparaissent dans le gestionnaire de modules complémentaires. Voir Limitations ci-dessous.

Chaînes localisées

Les chaînes traduites sont conservées dans un répertoire appelé "locale" sous votre répertoire principale de l'add-on , avec un fichier pour chaque langue. Les dossiers:

  • utiliser .properties Format
  • sont nommés "xx-YY.properties", où "xx-YY" est le nom locale en question (en français, uniquement "fr.properties")
  • contienent une entrée pour chaque chaîne que vous voulez localiser, constitué d'un identifiant pour la chaîne et sa traduction dans cette langue, dans le format identifier=translation
  • utilisent UTF-8 sans codage BOM
  • Les lignes commençant par "#" (après espaces optionnels) sont des commentaires

Supposons que votre add-on contient une seule chaîne localisable, représentée en anglais comme "Hello!", Et que vous souhaitez fournir les localisations Français FRANCAIS et anglais ETATS-UNIS.

Vous souhaitez ajouter deux fichiers au répertoire "locale" :

my-addon/
         data
         lib
         locale/
                en-US.properties
                fr.properties

"en-US.properties" contient ceci:

hello_id= Hello!

"fr.properties" contient ceci:

hello_id= Bonjour!

Maintenant, chaque fois que votre JavaScript ou HTML demande au système de localisation la traduction de l'identifiant hello_id, il obtiendra la traduction correcte pour la localisation en cours.

Utilisation de chaînes localisées en HTML

Cet exemple utilise l'API button_action, qui est uniquement disponible à partir de Firefox 29.

Pour référencer des chaînes localisées du HTML, ajouter un attribut data-l10n-id à la balise HTML où vous voulez que la chaîne localisée apparaisse, et assignez y l'identifiant :

<html>
  <body>
    <h1 data-l10n-id="hello_id"></h1>
  </body>
</html>

Ensuite, vous pouvez utiliser ce fichier HTML pour construire votre interface, par exemple à l'intérieur d'un panel :

var button = require("sdk/ui/button/action").ActionButton({
  id: "localized-hello",
  label: "Localized hello",
  icon: "./icon-16.png",
  onClick: function() {
    hello.show();
  }
});

var hello = require("sdk/panel").Panel({
  height: 75,
  width: 150,
  contentURL: require("sdk/self").data.url("my-panel.html")
});

Compte tenu de fichiers locaux pour "en-US" et "fr" qui fournissent les traductions de hello_id, le panneau affichera désormais "Bonjour!" ou "Hello!", selon la localisation en cours:

La traduction est inséré dans le nœud qui a l'attribut data-l10n-id défini. Tout contenu existant précédemment est simplement remplacé.

La chaîne est insérée sous forme de texte, de sorte que vous ne pouvez pas insérer du code HTML en utilisant une déclaration comme:

# Ne fonctionne pas. Les balises HTML sont insérés sous forme de texte.
hello_id= <blink>Hello!</blink>

Attributs d'Elément Localisation

Cette fonction est nouvelle dans Firefox 39

Vous pouvez localiser certains attributs d'éléments avec un l10n-id en définissant sa valeur avec l10n-id.attributeName dans le fichier de propriétés comme:

hello_id.accesskey= H

Les attributs suivants sont supportés:

  • accesskey
  • alt
  • label
  • title
  • placeholder

En outre, la localisation avec les attributs ARIA aria-label , aria-valuetex et aria-moz-hint sont pris en charge avec les mêmes alias que sur Firefox OS :

  • ariaLabel
  • ariaValueText
  • ariaMozHint

Utilisation de chaînes localisées en JavaScript

Pour référencer les chaînes localisées à partir de votre code d'add-on principale, faites ceci:

var _ = require("sdk/l10n").get;
console.log(_("hello_id!"));

L'affectation de "_" n'est pas nécessaire, mais pour travailler avec les outils gettext qui attendent "_" pour indiquer les chaînes localisables, cela est préférable.

  1. Importez le module l10n, et assigner sa fonction get à "_"(underscore).
  2. Enveloppez toutes les références aux chaînes localisables avec la fonction _().

Si vous l'exécutez, vous verrez le résultat attendu pour la localisation en cours:

info: Hello!
info: Bonjour!

Notez que parce que vous ne pouvez pas appeler des modules avec require() dans les content_scripts, vous ne pouvez pas encore référencer les chaînes localisées à partir des content_scripts.

Pluriels

Le module l10n prend en charge les formes plurielles. Plusieurs langues ont des règles différentes pour la formation des pluriels. Par exemple, l'anglais a deux formes: une forme singulière pour "un", et une forme plurielle pour "tout le reste, y compris zéro":

one tomato
no tomatoes
two tomatoes

Mais le Russe a des formes différentes pour les numéros se terminant par 1 (sauf 11), numéros se terminant par 2-4 (sauf 12-14) et les autres numéros:

один помидор     // one tomato
два помидора     // two tomatoes
пять помидоров   // five tomatoes

Le SDK utilise les données de Unicode CLDR pour décrire les différentes formes plurielles utilisés dans les différentes langues.

Formes plurielles de Unicode CLDR

Le projet Unicode CLDR définit un schéma pour décrire les règles de pluriel d'une langue particulière. Dans ce schéma, une langue peut se distinguer par un maximum de six formes, identifié par les catégories suivantes : zero, one, two, few, many et other.

L'englais a deux formes, qui peuvent être décrits par les categories "1" à "one" et "everything else" à "other":

one   → n is 1;
other → everything else

Le russe utilise quatre formes, qui peuvent être décrits comme suit:

one   → n mod 10 is 1 and n mod 100 is not 11;
few   → n mod 10 in 2..4 and n mod 100 not in 12..14;
many  → n mod 10 is 0 or n mod 10 in 5..9 or n mod 100 in 11..14;
other → everything else

Les règles de pluriel pour toutes les langues peuvent être trouvés dans le CLDR Langue règles pluriel (ce tableau est mis à jour par rapport à la source XML CLDR).

Formes plurielles dans le SDK

Dans le code, vous pouvez fournir un paramètre supplémentaire à côté de l'identifiant, en décrivant combien d'articles il y a :

var _ = require("sdk/l10n").get;
console.log(_("tomato_id"));
console.log(_("tomato_id", 1));
console.log(_("tomato_id", 2));
console.log(_("tomato_id", 5));
console.log(_("tomato_id", .5));

Dans le fichier .properties pour chaque langue, vous pouvez définir une localisation différente pour chaque forme plurielle possible dans cette langue, en utilisant les mots-clés de CLDR. Donc, en anglais, nous pourrions avoir deux localisations pluriel (à noter que la catégorie «other» ne prendre pas le mot-clé CLDR):

# en-US translations
tomato_id[one]= %d tomato
tomato_id= %d tomatoes

En Russe, nous pourrions avoir quatre localisations pluriel:

# ru-RU translations
tomato_id[one]= %d помидор
tomato_id[few]= %d помидора
tomato_id[many]= %d помидоров
tomato_id= %d помидоры

Le module de localisation comprend les définitions de CLDR pour chaque langue, ce qui lui permet de faire la différence entre, par exemple, "2" dans le code et "few" dans ru-RU.properties. Ensuite, il récupère et renvoie la localisation pour le compte que vous avez fourni.

Espaces réservés

Le module l10n prend en charge des espaces réservés, vous permettant d'insérer une chaîne qui ne devrait pas être localisé. Dans le code qui suit les fichiers "en-US" et "fr" ".properties" incluent des espaces réservés :

# en-US translations
hello_id= Hello %s!
# fr translations
hello_id= Bonjour %s !

Pour utiliser les espaces réservés, fournir la chaîne de réservation après l'identifiant:

var _ = require("sdk/l10n").get;
console.log(_("hello_id", "Bob"));
console.log(_("hello_id", "Alice"));

Dans la localisation "en-US", cela nous donne:

info: Hello Bob!
info: Hello Alice!

Dans "fr" nous obtenons:

info: Bonjour Bob !
info: Bonjour Alice !

Commande espaces réservés

Quand une chaîne localisable peut prendre deux ou plusieurs espaces réservés, les traducteurs peuvent définir l'ordre dans lequel les espaces réservés sont insérés, sans affecter le code.

Principalement, ce qui est important c'est que les différentes langues ont des règles différentes pour l'ordre des mots. Même au sein de la même langue, cependant, les traducteurs doivent avoir la liberté de définir l'ordre des mots.

Par exemple, supposons que nous voulons inclure une chaîne localisée nommer ville natale d'une personne. Il y a deux espaces réservés: le nom de la personne et le nom de la ville natale :

var _ = require("sdk/l10n").get;
console.log(_("home_town_id", "Bob", "London"));

Un traducteur anglais pourrait vouloir choisir entre les ordres suivantes:

"<town_name> is <person_name>'s home town."
"<person_name>'s home town is <town_name>"

Pour choisir la première option, le fichier .properties peut commander les espaces réservés comme suit:

home_town_id= %2s is %1s's home town.

Cela nous donne le résultat suivant:

info: London is Bob's home town.

Utilisation de chaînes localisées dans les Préférences

En incluant une structure "preferences" dans votre fichier "package.json", vous pouvez définir des préférences pour votre add-on que l'utilisateur peut voir et modifier à l'aide de Firefox Add-ons Manager.

Les préférences ont obligatoirement des champs title et description. Ce sont des chaînes qui apparaissent aux côtés de la préférence dans le Gestionnaire Add-ons, pour expliquer à l'utilisateur ce que signifie la préférence.

  • Pour fournir la forme localisée du titre de la préférence, inclure une entrée dans votre fichier "propriétés" dont l'identifiant est le nom de la préférence suivie par _title, et dont la valeur est le titre localisé.

  • Pour fournir la forme localisée de la description de la préférence, inclure une entrée dans votre fichier "propriétés" dont l'identifiant est le nom de la préférence suivie par _description, et dont la valeur est la description localisée.

Par exemple, supposons que votre "package.json" définit une seule préférence:

{
    "preferences": [
        {
            "type": "string", 
            "name": "monster_name", 
            "value": "Gerald",
            "title": "Name"
        }
    ], 
    "name": "monster-builder", 
    "license": "MPL 2.0", 
    "author": "me", 
    "version": "0.1", 
    "fullName": "Monster Builder", 
    "id": "monster-builder@me.org", 
    "description": "Build your own monster"
}

Dans votre fichier "en-US.properties", inclure ces deux éléments :

monster_name_title= Name
monster_name_description= What is the monster's name?

Dans votre fichier "fr.properties", inclure la traduction française:

monster_name_title= Nom
monster_name_description= Quel est le nom du monstre ?

Quand la configuration locale du navigateur est "en-US", les utilisateurs voient dans le gestionnaire de modules complémentaires:

Lorsque la configuration locale du navigateur est "fr", ils voient ceci:

Les types menulist et radio de préférences ont des options. L'attribut label de chaque option est affichée à l'utilisateur. Si le fichier de paramètres régionaux a une entrée avec la valeur de l'élément label préfixé «{name}_options." comme clé (où {name} est le nom de la préférence), sa valeur est utilisée comme étiquette localisée.

Utilisation de l'identificateurs

Si le système de localisation ne peut pas trouver une entrée pour un identifiant particulier en utilisant la localisation en cours, elle retourne juste l'identifiant lui-même.

C'est intéressante car vous pouvez écrire du code "localisable", entièrement fonctionnel sans avoir à écrire des fichiers locaux. Vous pouvez simplement utiliser les chaînes de langue par défaut et fournir ultérieurement les fichiers .properties pour toutes les langues supplémentaires que vous souhaitez soutenir.

Par exemple, dans le cas ci-dessus, vous pouvez utiliser "Bonjour!" comme identificateur, et juste avoir un .properties pour la locale "fr":

Hello!= Bonjour!

Puis, quand la locale "en-US", le système ne parviennent pas à trouver un .properties, et revoit "Bonjour!".

Cependant, cette approche rend difficile le maintien d'une add-on qui a de nombreuses localisations, parce que vous utilisez les chaînes de langue par défaut en tant que chaînes de l'interface utilisateur et que les clés recherchent vos traductions. Cela signifie que si vous voulez changer le libellé d'une chaîne dans la langue par défaut, ou corriger une faute de frappe, alors vous cassez tous vos fichiers de paramètres régionaux.

Locale Updater

L'add-on locale updater (paramètres régionaux de mise à jour) rend plus facile la mise à jour des fichiers locaux. Une fois que vous l'avez installé, ouvrez le Gestionnaire de modules complémentaires, et vous verrez un nouveau bouton "Update l10n" à côté de chaque add-on que vous avez installé :

Cliquez sur le bouton et vous serez invité à entrer un nouveau fichier .properties pour cette add-on. Si vous fournissez un nouveau fichier, les données locales de l'add-on seront mis à jour avec le nouveau fichier.

Limites

Le support de la localisation actuelle est un premier pas vers la prise en charge complète, et contient un certain nombre de limitations.

  • Il n'y a pas de soutien pour les scripts de contenu ou des fichiers CSS: pour le moment, vous ne pouvez localiser les chaînes apparaissant dans les fichiers JavaScript qui sont appelés avec require().

  • Il n'y a pas de soutien pour localiser name ou description de l'add-on : votre seule option étant de modifier le fichier install.rdf après la construction du XPI. Voir bug 1218719.

  • L'ensemble des fichiers locaux sont globaux à travers une add-on. Cela signifie qu'un module n'est pas en mesure de remplacer une traduction plus générale: si un module informal.js ne peut pas spécifier que "hello_id" survenant dans son code doit être traduit par "Salut!".

  • Les outils SDK compilent les fichiers de localisation dans un format JSON lors de la production d'un XPI. Cela signifie que les traducteurs ne peuvent pas travailler directement sur le XPI, mais doivent avoir accès à la source de l'add-on.

  • Le développeur de l'add-on doit assembler manuellement l'ensemble des chaînes localisables qui composent les fichiers locaux.

Voir aussi - pour les développeurs qui cherchent à localiser les add-ons non-SDK

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : Romaric, jmh
 Dernière mise à jour par : Romaric,