Localisation d'applications Firefox OS

Dans cet article, nous discuterons de la manière de localiser votre application Firefox OS en utilisant les librairies actuellement employées pour la localisation dans la couche Gaia de Firefox OS, telle que L10n.js. Gaia englobe toutes les applications web incluses dans le système d'exploitation, incluant le Dialer et le Contacts Manager, il fournit donc un bon modèle dont s'inspirer.

Les applications Firefox OS sont utilisées dans le monde entier — Espagne, Pologne, Colombie, Venezuela avec beaucoup d'autres pays à venir — donc il est important de prendre en compte la localisation de votre application dès le début. Cependant, le web ouvert étant ce qu'il est, il y a de nombreux choix de frameworks et technologies lorsqu'il s'agit de localisation. Par exemple, la librairie Jed Gettext-style est une option classique populaire. Il y a aussi de nouvelles plate-formes de localisation en développement qui étendent les capacités des librairies actuelles. Par exemple, chez Mozilla, nous avons un projet de localisation très prometteur qui étend L10n avec une multitude de nouvelles fonctionnalités intéressantes. Pour en apprendre plus, allez voir le groupe Mozilla Tools.

Note: Si vous décidez d'utiliser cette approche, gardez à l'esprit que certaines fonctionnalités de la librairie (par exemple la méthode non-standard toLocaleFormat de l10n_date.js) ne sont pas compatibles avec tous les navigateurs et que Gaia adoptera probablement L20n dans le futur.

Commençons et regardons la localisation avec L10n.js.

L10n.js

Actuellement, Gaia, de Firefox OS, utilise une version modifiée de la librairie L10n.js pour localiser les applications qui sont disponibles par défaut dans Firefox OS. L10n.js est disponible dans l'arborescence des sources Gaia.

Pour illustrer comment cela fonctionne, examinons l'application Bluetooth, qui est utilisée pour transférer des fichiers. Les fichiers des propriétés de l'application sont structurés de la manière suivante:

L'application contient des fichiers de propriétés pour quatre locales (ar, en-US, fr et zh-TW). Une portion du fichier bluetooth.en-US.properties est listée dessous:

bluetooth = Bluetooth
confirmation = Confirmation
bluetooth-status-description = Bluetooth is disabled
turn-bluetooth-on = Do you want to turn Bluetooth on?
cancel = Cancel
turn-on = Turn On

Comme vous pouvez le voir, c'est un simple fichier de propriétés clé/valeur contenant des chaînes de caractères à localiser.

Faire un lien vers les ressources

Afin que les ressources soient utilisées pour localiser votre fichier HTML, vous avez besoin de les lier à l'élément HTML <head>:

<link rel="localization" href="locales/bluetooth.{locale}.properties" />

L10n.js utilise le schéma URL Template, où la partie {locale} du chemin sera remplacée par le code local sélectionné en tant que résultat de la détermination du langage.

En plus de cela, vous avez besoin de lister toutes les locales disponibles et la locale par défaut à utiliser dans le fichier manifest.webapp. D'abord, liez le fichier comme suit:

<link rel="manifest" href="./manifest.webapp" />

Ensuite ajoutez vos locales à votre manifeste. Les parties pertinentes à mettre à jour sont les champs default_locale et locales, qui sont plutôt intuitifs à modifier:

"default_locale": "en",
"locales": {
  "es": {
    "name" : "Probador de traducción",
    "description" : "Para ayudar con la localización"
  }
}

Alternativement, vous pouvez lister les locales disponibles et les locales par défaut au sein du fichier HTML en utilisant les éléments <meta>:

<meta name="locales" content="en-US, fr, de">
<meta name="default_locale" content="en-US">

L10n.js fera la négociation du langage entre les langages sélectionnés par l'utilisateur (voir NavigatorLanguage.languages) et la liste des langages disponibles fournis dans le manifeste, la sélection du langage de secours et le chargement des ressources pour la locale préférée.

L'élément attribut L10n

Vous définissez les éléments qui ont besoin d'une traduction en leur donnant l'attribut data-l10n-id, qui est la clé définit dans le fichier de propriétés. Par exemple, un entête qui a besoin de localisation ressemblera à ceci:

<h2 data-l10n-id="label1">Label One</h2>

La valeur de l'attribut label1 sert de clé dans le fichier de propriétés. Une chaîne de caractères peut être créée dans les fichiers de propriétés en utilisant la substitution d'argument et la macro plurielle, les deux étant décrits ci-dessous.

Le lien entre chaque l10n-id et son HTMLElement associé, est un modèle exclusif, un pour un. Ces associations ne devraient pas être réutilisées car bien qu'elles puissent avoir la même valeur dans votre langage d'origine, des contextes différents nécessiteront souvent des traductions différentes.

Les éléments localisables devraient aussi n'avoir aucun contenu ou élément enfant car la localisation les réécrira.

Substitution d'argument

La substitution d'argument est réalisée en encadrant l'argument avec une double paire d'accolades {{arg}}. Un message peut alors être personnalisé pour un utilisateur spécifique en utilisant une syntaxe similaire à ce qui suit:

label1 = Hello {{ user }}, glad you decided to visit

Les valeurs par défaut des arguments peuvent être assignées avec l'attribut data-l10n-args. Cet attribut attend une valeur avec le format JSON. Dans l'exemple ci-dessus, une valeur par défaut pourrait être mise pour l'argument user en utilisant le code HTML ci-dessous:

<h2 data-l10n-id="label1" data-l10n-args='{ "user": "Guest" }'></h2>

Le résultat sera que le contenu de l'élément s'affichera comme "Hello Guest, glad you decided to visit".

Vous pouvez aussi renseigner d'autres valeurs de la même manière:

brandShortName = Firefox OS
helloWorld = Welcome to {{ brandShortName }}

Macro plurielle

L10n.js a actuellement un support très limité des fonctionnalités des macros et des chaînes de caractères variables.

La macro plurielle peut-être utilisée pour personnaliser les messages à partir de la valeur d'un argument. La macro prend un nombre en valeur et retourne zéro, un, deux, peu, beaucoup ou autre. La valeur de retour dépend de la valeur passée et de la règle de l'actuelle locale selon l'Unicode Plural Rules. En tant qu'exemple, un message personnalisé pour une boîte de messagerie pour la locale en-US pourrait ressembler à ceci:

mailMessage = {[ plural(n) ]}
mailMessage[zero]  = you have no messages
mailMessage[one]   = you have one message
mailMessage[two]   = you have two messages
mailMessage[other] = you have {{ n }} messages
<h3 data-l10n-id="mailMessage" data-l10n-args='{ "n": "6" }'></h3>

Référence au script L10n

La plupart des applications par défaut de Firefox OS utilise un élément <script> similaire à ce qui suit pour charger la librairie L10n.js:

<script defer src="/shared/js/l10n.js" charset="utf-8"></script>

Pour utiliser cette librairie dans votre propre application, vous aurez besoin de copier le fichier l10n.js dans votre projet en local et de changer l'attribut src pour qu'il corresponde.

Une fois chargée, la librairie L10n.js exposera un objet navigator.mozL10n qui peut être utilisé pour la localisation côté client.

Localiser HTML avec JavaScript: bonnes pratiques

Le meilleur moyen de localiser des éléments d'UI à partir de JavaScript est de placer l'attribut data-l10n-id sur un élément:

document.getElementById('myelement').setAttribute('data-l10n-id', 'label1');

L10n.js a MutationObserver qui réagira à ce changement et localisera l'élément. Vous pouvez aussi placer data-l10n-args comme montré ici:

var elem = document.getElementById('myelement');
elem.setAttribute('data-l10n-id', 'label1');
elem.setAttribute('data-l10n-args', JSON.stringify({'name': 'John'}));

Bien qu'il semble tentant d'utiliser HTMLElement.dataset l10nId ou l10nArgs ici, nous ne recommandons pas cela. Non seulement setAttribute est plus rapide, mais il représente aussi une approche plus pérenne car le préfixe data- est utilisé seulement temporairement et une fois que l'effort de standardisation de WebAPI progressera, data-l10n-id sera remplacé par un attribut l10n-id.

La méthode setAttributes

La manière d'initialiser l10n-id et l10n-args est si commune que l10n.js fournit une fonction pour faire cela:

navigator.mozL10n.setAttributes(elem, 'label1', {'name': 'John'});

La méthode getAttributes

Afin de retrouver les attributs de localisation, vous pouvez utiliser la fonction getAttributes:

var l10nAttrs = navigator.mozL10n.getAttributes(elem); // {id: 'label1', args: { 'name': 'John' }}

Supprimer une localisation

L10n.js ne fournit actuellement aucune fonction de suppression, donc quand vous voulez rendre un élément non localisable, vous avez besoin de supprimer l'attribut data-l10n-id et de vider le contenu de votre nœud:

elem.removeAttribute('data-l10n-id');
elem.textContent = '';

La méthode get (dépréciée)

La méthode get est utilisée pour traduire une chaîne de caractères pour la locale en cours. La méthode prend un paramètre key et un paramètre optionnel args. Le paramètre key spécifie la clé définie pour le fichier de propriétés.

get ne sera bientôt plus supporté et devrait être évité. Il y a actuellement trois cas d'utilisation dans lesquels cette méthode est toujours nécessaire:

  1. UI de widget non-HTML, comme les alertes et fenêtres de confirmation.
  2. Formatage Date/Heure.
  3. Fragment DOM — quand vous avez besoin de localiser tout un bloc d'HTML en utilisant une seule chaîne de caractères pour la localisation.

Dans tous les autres cas, il est sûrement plus sûr d'utiliser l10n-id sur un HTML Element:

navigator.mozL10n.get("mylabel")

Le paramètre args peut être passé sous un formatage JSON pour une chaîne de caractères qui contient des arguments.

//properties file
welcome = Welcome {{user}}!

//JavaScript
alert( navigator.mozL10n.get(“welcome”,  { user: "Martin" }));

La méthode once

La méthode once vous permet de définir un rappel qui se déclenche quand la localisation pour le document en cours est complète.

var button1 = document.querySelector("#button1");
button1.setAttribute('data-l10n-id', 'label1');

navigator.mozL10n.once(function() {
  button1.style.display = 'block';
});

Parce que la localisation est asynchrone, l10n-id peut être placé sur le bouton avant que les ressources l10n ne soient prêtes. Dans ce cas la localisation se déclenchera seulement lorsque les ressources seront chargées.

once vous permet d'exécuter du code seulement quand la localisation est complétée et les ressources disponibles.

 Il devrait protéger tout code qui veut utiliser la méthode get et le code qui affiche l'interface utilisateur localisée.

La propriété language

La propriété language contient un getter et un setter pour le code langue. La propriété language contient aussi un getter pour le sens de lecture de la langue, pour le support des langues de la droite vers la gauche (Arabe ou Hébreu) et de la gauche vers la droite.

var mycode = navigator.mozL10n.language.code;
navigator.mozL10n.language.code = "fr";
navigator.mozL10n.language.direction //returns rtl or ltr

Script l10n_date

Pour la manipulation de la date et de l'heure, les applications Gaia étendent les capacités de L10n.js avec la librairie l10n_date.js., si bien qu'avec la librairie l10n.js, certaines fonctionnalités implémentées peuvent ne pas être compatibles avec tous les navigateurs. l10n_date.js est disponible dans l'arborescence des sources Gaia et utilise la même structure de propriétés décrite dans la section L10n.js de cet article. Les applications Gaia qui utilisent cette librairie comptent toutes sur un jeu partagé de fichiers de propriétés. Les fichiers de propriétés de locale spécifique sont situés dans le dossier date. Ces fichiers de propriétés définissent les formats et les chaînes de caractères pour les items comme le jour commençant la semaine, le format raccourci de la date, ou encore le noms des mois. Pour utiliser cette librairie dans votre application, vous aurez besoin de copier tous les fichiers dans votre projet.

<link rel="localization" href="locales/date.{locale}.properties" />
<script defer src="js/l10n_date.js"></script>

En utilisant les méthodes de formatage de l10n_date, les chaînes de caractères dans les fichiers de propriétés peuvent utiliser les codes de formatage de date/heure standards de C++.  Comme exemple de cela, examinons le fichier de propriétés de l'application Clock de Gaia. Ce fichier contient l'entrée suivante pour dateFormat dans la locale en-US:

dateFormat = %A, %B %e

En utilisant la méthode formatLocale au sein de la librairie l10n_date, cela retournera:

“Full Weekday Name” “Full Month Name” “Day of the Month” (Thursday January 29).

La version française du fichier de propriétés définit la même clé de la manière suivante:

dateFormat = %A %e %B

Cela produit:

“Full Weekday Name” “Day of the Month” “Full Month” (jeudi 25 janvier).

Lorsque vous incluez la librairie l10n_date, une nouvelle méthode est disponible pour l'objet mozL10n: navigator.mozL10n.DateTimeFormat(). Une fois instancié, cet objet a plusieurs méthodes qui peuvent être utilisées pour localiser des dates. Les plus utiles sont les suivantes:

La méthode localeFormat

La méthode localeFormat prend en paramètre un objet date et un pattern format et retourne la date formatée comme spécifiée dans le pattern. Cette méthode devrait être utilisée en conjonction avec la méthode get de L10n.js pour formater une date localisée.

button3.onclick = function () {
    navigator.mozL10n.language.code = "fr";
    navigator.mozL10n.ready( function() {
        var d = new Date();
        var f = new navigator.mozL10n.DateTimeFormat();
        var format = navigator.mozL10n.get('dateFormat');
        var formatted = f.localeFormat(d, format);
        alert( formatted );
    });    
}

Les méthodes localeDateString, localeTimeString et localeString

Ces trois méthodes sont juste des variations de la méthode localeFormat qui retournent des dates formatées en se basant sur les valeurs des clés suivantes au sein des fichiers de propriétés de date:

//en-US
//localeString returns
dateTimeFormat_%c = %a %b %e %Y %I:%M:%S %p
//localeDateString returns
dateTimeFormat_%x = %m/%d/%Y
//localeTimeString returns
dateTimeFormat_%X = %I:%M:%S %p

La méthode fromNow

La méthode fromNow prend en paramètre une date et une heure puis retourne une chaîne de caractères localisée exprimant la différence de temps entre la date/heure actuelle et la date/heure passée en paramètre. La chaîne de caractères formatée sera basée sur les chaînes de caractères définies dans le fichier des propriétés date. Par exemple:

//Executed on 7/25/2013 12:11:00
var d = new Date("July 25, 2013 11:13:00");
var f = new navigator.mozL10n.DateTimeFormat();
alert( f.fromNow(d));

Cela créerait une alerte “58 Minutes Ago” en locale en-US. La chaîne de caractères sera formatée en utilisant la clé "minutes-ago-long" dans le fichier de propriétés date.

minutes-ago-long={[ plural(value) ]}
minutes-ago-long[zero] = just now
minutes-ago-long[one] = a minute ago
minutes-ago-long[two] = {{ value }} minutes ago
minutes-ago-long[few] = {{ value }} minutes ago
minutes-ago-long[many] = {{ value }} minutes ago
minutes-ago-long[other] = {{ value }} minutes ago

Apprenez plus et impliquez-vous!

Pour plus de lecture sur les bonnes pratiques de localisation, voyez Créez des applications web localisables.

Et après que vous ayez fini de localiser votre application Firefox OS, pourquoi ne pas aider avec la localisation de Firefox OS lui-même? Jetez un œil à Localiser Firefox OS pour avoir plus d'informations sur la façon dont vous pouvez contribuer.

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : BiiO, cdaijardin
 Dernière mise à jour par : BiiO,