diff options
Diffstat (limited to 'files/fr/mozilla/add-ons/sdk/tutorials/l10n/index.html')
| -rw-r--r-- | files/fr/mozilla/add-ons/sdk/tutorials/l10n/index.html | 383 |
1 files changed, 383 insertions, 0 deletions
diff --git a/files/fr/mozilla/add-ons/sdk/tutorials/l10n/index.html b/files/fr/mozilla/add-ons/sdk/tutorials/l10n/index.html new file mode 100644 index 0000000000..4b9ca669e7 --- /dev/null +++ b/files/fr/mozilla/add-ons/sdk/tutorials/l10n/index.html @@ -0,0 +1,383 @@ +--- +title: Localisation +slug: Mozilla/Add-ons/SDK/Tutorials/l10n +translation_of: Archive/Add-ons/Add-on_SDK/Tutorials/l10n +--- +<p>Le SDK supporte la localisation des chaînes figurant dans:</p> + +<ul> + <li><a href="/fr/docs/Mozilla/Add-ons/SDK/Tutorials/l10n#Using_Localized_Strings_in_JavaScript">Le code JavaScript dans le main ou l'index de l'add-on</a></li> + <li><a href="/fr/docs/Mozilla/Add-ons/SDK/Tutorials/l10n#Using_Localized_Strings_in_HTML">Les fichiers HTML emballés avec votre add-on</a></li> + <li><a href="/fr/docs/Mozilla/Add-ons/SDK/Tutorials/l10n#Using_Localized_Strings_in_Preferences">Les champs <code>title</code> et <code>description</code> de votre add-on</a>.</li> +</ul> + +<p>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 <a href="/fr/docs/Mozilla/Add-ons/SDK/Tutorials/l10n#Limitations" title="/fr/Add-ons/SDK/Tutorials/l10n#Limitations">Limitations</a> ci-dessous.</p> + +<h2 id="Chaînes_localisées">Chaînes localisées</h2> + +<p>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:</p> + +<ul> + <li>utiliser <a href="http://fr.wikipedia.org/wiki/.properties" title="http://en.wikipedia.org/wiki/.properties"> <code>.properties</code> Format</a></li> + <li>sont nommés "xx-YY.properties", où "xx-YY" est le <a href="https://wiki.mozilla.org/L10n:Locale_Codes" title="https://wiki.mozilla.org/L10n:Locale_Codes">nom locale</a> en question (en français, uniquement "fr.properties")</li> + <li>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 <code>identifier=translation</code></li> + <li>utilisent UTF-8 sans codage BOM</li> + <li>Les lignes commençant par "#" (après espaces optionnels) sont des commentaires</li> +</ul> + +<p>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.</p> + +<p>Vous souhaitez ajouter deux fichiers au répertoire "locale" :</p> + +<pre>my-addon/ + data + lib + locale/ + en-US.properties + fr.properties +</pre> + +<p>"en-US.properties" contient ceci:</p> + +<pre>hello_id= Hello! +</pre> + +<p>"fr.properties" contient ceci:</p> + +<pre>hello_id= Bonjour! +</pre> + +<p>Maintenant, chaque fois que votre JavaScript ou HTML demande au système de localisation la traduction de l'identifiant <code>hello_id</code>, il obtiendra la traduction correcte pour la localisation en cours.</p> + +<h2 id="Utilisation_de_chaînes_localisées_en_HTML">Utilisation de chaînes localisées en HTML</h2> + +<div class="note"> +<p>Cet exemple utilise l'API <a href="https://developer.mozilla.org/fr/docs/Mozilla/Add-ons/SDK/Low-Level_APIs/ui_button_action" title="https://developer.mozilla.org/fr/Add-ons/SDK/Low-Level_APIs/ui_button_action">button_action</a>, qui est uniquement disponible à partir de Firefox 29.</p> +</div> + +<p>Pour référencer des chaînes localisées du HTML, ajouter un attribut <code>data-l10n-id</code> à la balise HTML où vous voulez que la chaîne localisée apparaisse, et assignez y l'identifiant :</p> + +<pre class="brush: html"><html> + <body> + <h1 data-l10n-id="hello_id"></h1> + </body> +</html> +</pre> + +<p>Ensuite, vous pouvez utiliser ce fichier HTML pour construire votre interface, par exemple à l'intérieur d'un panel :</p> + +<pre class="brush: js">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") +});</pre> + +<p>Compte tenu de fichiers locaux pour "en-US" et "fr" qui fournissent les traductions de <code>hello_id</code>, le panneau affichera désormais "Bonjour!" ou "Hello!", selon la localisation en cours:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/7663/bonjour.png" style="height: 160px; width: 255px;"><img alt="" src="https://mdn.mozillademos.org/files/7665/hello.png" style="height: 160px; width: 255px;"></p> + +<p>La traduction est inséré dans le nœud qui a l'attribut <code>data-l10n-id</code> défini. Tout contenu existant précédemment est simplement remplacé.</p> + +<p>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:</p> + +<pre class="brush: bash"># Ne fonctionne pas. Les balises HTML sont insérés sous forme de texte. +hello_id= <blink>Hello!</blink> +</pre> + +<h3 id="Attributs_d'Elément_Localisation">Attributs d'Elément Localisation</h3> + +<div class="geckoVersionNote">Cette fonction est nouvelle dans Firefox 39</div> + +<p>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:</p> + +<pre>hello_id.accesskey= H</pre> + +<p>Les attributs suivants sont supportés:</p> + +<ul> + <li><strong>accesskey</strong></li> + <li><strong>alt</strong></li> + <li><strong>label</strong></li> + <li><strong>title</strong></li> + <li><strong>placeholder</strong></li> +</ul> + +<p>En outre, la localisation avec les attributs <a href="/fr/docs/Web/Accessibility/ARIA" title="/fr/docs/Web/Accessibility/ARIA">ARIA</a> <strong> aria-label </strong>, <strong>aria-valuetex</strong> et <strong> aria-moz-hint </strong> sont pris en charge avec les mêmes alias que sur Firefox OS :</p> + +<ul> + <li><strong>ariaLabel</strong></li> + <li><strong>ariaValueText</strong></li> + <li><strong>ariaMozHint</strong></li> +</ul> + +<h2 id="Utilisation_de_chaînes_localisées_en_JavaScript">Utilisation de chaînes localisées en JavaScript</h2> + +<p>Pour référencer les chaînes localisées à partir de votre code d'add-on principale, faites ceci:</p> + +<pre class="brush: js">var _ = require("sdk/l10n").get; +console.log(_("hello_id!"));</pre> + +<p><span>L'affectation de "<code>_</code>" n'est pas nécessaire, mais pour travailler avec les outils <a href="https://www.gnu.org/software/gettext/gettext.html" title="https://www.gnu.org/software/gettext/gettext. html">gettext</a> qui attendent "<code>_</code>" pour indiquer les chaînes localisables, cela est préférable.</span></p> + +<ol> + <li>Importez le module <code>l10n</code>, et assigner sa fonction <code>get</code> à "<code>_</code>"(underscore).</li> + <li>Enveloppez toutes les références aux chaînes localisables avec la fonction <code>_()</code>.</li> +</ol> + +<p>Si vous l'exécutez, vous verrez le résultat attendu pour la localisation en cours:</p> + +<pre>info: Hello! +</pre> + +<pre>info: Bonjour! +</pre> + +<p>Notez que parce que vous ne pouvez pas appeler des modules avec <code>require()</code> dans les content_scripts, vous ne pouvez pas encore référencer les chaînes localisées à partir des content_scripts.</p> + +<h3 id="Pluriels">Pluriels</h3> + +<p>Le module <code>l10n</code> 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":</p> + +<pre>one tomato +no tomatoes +two tomatoes +</pre> + +<p>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:</p> + +<pre>один помидор // one tomato +два помидора // two tomatoes +пять помидоров // five tomatoes +</pre> + +<p>Le SDK utilise les données de <a href="http://cldr.unicode.org/index" title="http://cldr.unicode.org/index">Unicode CLDR</a> pour décrire les différentes formes plurielles utilisés dans les différentes langues.</p> + +<h4 id="Formes_plurielles_de_Unicode_CLDR">Formes plurielles de Unicode CLDR</h4> + +<p>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 : <em>zero</em>, <em>one</em>, <em>two</em>, <em>few</em>, <em>many</em> et <em>other</em>.</p> + +<p>L'englais a deux formes, qui peuvent être décrits par les categories "1" à "<em>one</em>" et "everything else" à "<em>other</em>":</p> + +<pre>one → n is 1; +other → everything else +</pre> + +<p>Le russe utilise quatre formes, qui peuvent être décrits comme suit:</p> + +<pre>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 +</pre> + +<p>Les règles de pluriel pour toutes les langues peuvent être trouvés dans le CLDR <a href="http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html" title="http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html"> Langue règles pluriel</a> (ce tableau est mis à jour par rapport à la <a href="http://unicode.org/repos/cldr/trunk/common/supplemental/plurals.xml">source XML CLDR</a>).</p> + +<h4 id="Formes_plurielles_dans_le_SDK">Formes plurielles dans le SDK</h4> + +<p>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 :</p> + +<pre class="brush: js">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));</pre> + +<p>Dans le fichier <code>.properties</code> 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 «<em>other</em>» ne prendre <strong>pas</strong> le mot-clé CLDR):</p> + +<pre># en-US translations +tomato_id[one]= %d tomato +tomato_id= %d tomatoes +</pre> + +<p>En Russe, nous pourrions avoir quatre localisations pluriel:</p> + +<pre># ru-RU translations +tomato_id[one]= %d помидор +tomato_id[few]= %d помидора +tomato_id[many]= %d помидоров +tomato_id= %d помидоры +</pre> + +<p>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 <code>ru-RU.properties</code>. Ensuite, il récupère et renvoie la localisation pour le compte que vous avez fourni.</p> + +<h3 id="Espaces_réservés">Espaces réservés</h3> + +<p>Le module <code>l10n</code> 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 :</p> + +<pre class="brush: bash"># en-US translations +hello_id= Hello %s! +</pre> + +<pre class="brush: bash"># fr translations +hello_id= Bonjour %s ! +</pre> + +<p>Pour utiliser les espaces réservés, fournir la chaîne de réservation après l'identifiant:</p> + +<pre class="brush: js">var _ = require("sdk/l10n").get; +console.log(_("hello_id", "Bob")); +console.log(_("hello_id", "Alice"));</pre> + +<p>Dans la localisation "en-US", cela nous donne:</p> + +<pre>info: Hello Bob! +info: Hello Alice! +</pre> + +<p>Dans "fr" nous obtenons:</p> + +<pre>info: Bonjour Bob ! +info: Bonjour Alice ! +</pre> + +<h3 id="Commande_espaces_réservés">Commande espaces réservés</h3> + +<p>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.</p> + +<p>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.</p> + +<p>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 :</p> + +<pre class="brush: js">var _ = require("sdk/l10n").get; +console.log(_("home_town_id", "Bob", "London"));</pre> + +<p>Un traducteur anglais pourrait vouloir choisir entre les ordres suivantes:</p> + +<pre>"<town_name> is <person_name>'s home town." +</pre> + +<pre>"<person_name>'s home town is <town_name>" +</pre> + +<p>Pour choisir la première option, le fichier <code>.properties</code> peut commander les espaces réservés comme suit:</p> + +<pre>home_town_id= %2s is %1s's home town. +</pre> + +<p>Cela nous donne le résultat suivant:</p> + +<pre>info: London is Bob's home town. +</pre> + +<h2 id="Utilisation_de_chaînes_localisées_dans_les_Préférences">Utilisation de chaînes localisées dans les Préférences</h2> + +<p>En incluant une <a href="/fr/docs/Mozilla/Add-ons/SDK/High-Level_APIs/simple-prefs" title="/fr/Add-ons/SDK/High-Level_APIs/simple-prefs">structure <code>"preferences"</code> dans votre fichier "package.json"</a>, vous pouvez définir des préférences pour votre add-on que l'utilisateur peut voir et modifier à l'aide de Firefox <a href="https://support.mozilla.org/fr/kb/Using%20extensions%20with%20Firefox#w_how-to-change-extension-settings" title="https://support.mozilla.org/fr/kb/Using%20extensions%20with%20Firefox#w_how-to-change-extension-settings">Add-ons Manager</a>.</p> + +<p>Les préférences ont obligatoirement des champs <code>title</code> et <code>description</code>. 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.</p> + +<ul> + <li> + <p>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 <code>_title</code>, et dont la valeur est le titre localisé.</p> + </li> + <li> + <p>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 <code>_description</code>, et dont la valeur est la description localisée.</p> + </li> +</ul> + +<p>Par exemple, supposons que votre "package.json" définit une seule préférence:</p> + +<pre>{ + "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" +} +</pre> + +<p>Dans votre fichier "en-US.properties", inclure ces deux éléments :</p> + +<pre>monster_name_title= Name +monster_name_description= What is the monster's name? +</pre> + +<p>Dans votre fichier "fr.properties", inclure la traduction française:</p> + +<pre>monster_name_title= Nom +monster_name_description= Quel est le nom du monstre ? +</pre> + +<p>Quand la configuration locale du navigateur est "en-US", les utilisateurs voient dans le gestionnaire de modules complémentaires:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/6525/preference-us.png" style="height: 77px; width: 571px;"></p> + +<p>Lorsque la configuration locale du navigateur est "fr", ils voient ceci:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/6523/preference-french.png"></p> + +<p>Les types <code>menulist</code> et <code>radio</code> de préférences ont des options. L'attribut <code>label</code> 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 <code>label</code> 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.</p> + +<h2 id="Utilisation_de_l'identificateurs">Utilisation de l'identificateurs</h2> + +<p>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.</p> + +<p>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 <code>.properties</code> pour toutes les langues supplémentaires que vous souhaitez soutenir.</p> + +<p>Par exemple, dans le cas ci-dessus, vous pouvez utiliser "Bonjour!" comme identificateur, et juste avoir un <code>.properties</code> pour la locale "fr":</p> + +<pre>Hello!= Bonjour! +</pre> + +<p>Puis, quand la locale "en-US", le système ne parviennent pas à trouver un <code>.properties</code>, et revoit "Bonjour!".</p> + +<div class="warning"> +<p>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.</p> +</div> + +<h2 id="Locale_Updater">Locale Updater</h2> + +<p>L'add-on <a href="https://github.com/downloads/ochameau/locale-updater/locale-updater.xpi" title="https://github.com/downloads/ochameau/locale-updater/locale-updater.xpi">locale updater (paramètres régionaux de mise à jour)</a> 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é :</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/6515/locale-updater.png"></p> + +<p>Cliquez sur le bouton et vous serez invité à entrer un nouveau fichier <code>.properties</code> 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.</p> + +<h2 id="Limites">Limites</h2> + +<p>Le support de la localisation actuelle est un premier pas vers la prise en charge complète, et contient un certain nombre de limitations.</p> + +<ul> + <li> + <p>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 <code>require()</code>.</p> + </li> + <li> + <p>Il n'y a pas de soutien pour localiser <a href="/fr/docs/Mozilla/Add-ons/Install_Manifests#name" title="/fr/Add-ons/Install_Manifests#name">name</a> ou <a href="/fr/docs/Mozilla/Add-ons/Install_Manifests#description" title="/fr/Add-ons/Install_Manifests#description">description</a> de l'add-on : votre seule option étant de modifier le fichier install.rdf après la construction du XPI. Voir <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=1218719" title="https://bugzilla.mozilla.org/show_bug.cgi?id=1218719">bug 1218719</a>.</p> + </li> + <li> + <p>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 <code>informal.js</code> ne peut pas spécifier que "hello_id" survenant dans son code doit être traduit par "Salut!".</p> + </li> + <li> + <p>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.</p> + </li> + <li> + <p>Le développeur de l'add-on doit assembler manuellement l'ensemble des chaînes localisables qui composent les fichiers locaux.</p> + </li> +</ul> + +<h2 id="Voir_aussi_-_pour_les_développeurs_qui_cherchent_à_localiser_les_add-ons_non-SDK">Voir aussi - pour les développeurs qui cherchent à localiser les add-ons non-SDK</h2> + +<ul> + <li>Comment localiser les pages HTML, les fichiers XUL, et les fichiers js/jsm des add-ons bootstrapped : <a href="/fr/docs/Mozilla/Add-ons/Bootstrapped_extensions#Localization_%28L10n%29" title="/fr/Add-ons/Bootstrapped_extensions#Localization_%28L10n%29">Bootstrapped Extensions::Localization(l10n)</a></li> + <li>Tutoriel Localisation XUL School : <a href="/fr/docs/Mozilla/Tech/XUL/Tutorial/Localization" title="/fr/docs/Mozilla/Tech/XUL/Tutorial/Localization">XUL : Localisation</a> et <a href="/fr/docs/Mozilla/Tech/XUL/Tutorial/Property_Files" title="/fr/docs/Mozilla/Tech/XUL/Tutorial/Property_Files">Les fichiers de propriétés</a></li> + <li><a href="/fr/docs/Mozilla/Localization/Localizing_an_extension">Localisation d'une extension</a></li> +</ul> |