Localisation

This is an archived page. It's not actively maintained.

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