Ce document décrit un système d'internationalisation/traduction pour les projets c2cgeoportal/ngeo.

Auteurs : @asaunier et @elemoine.

• Un système "unifié". Il s'agit ici de ne pas avoir, du point de vue de traducteurs, plusieurs systèmes de traduction au sein d'un projet.
• Possibilité d'utiliser un système de traduction externe comme Transifex. (Même si, pour le moment, un tel système ne sera pas utilisé pour geoportail_v3.)
• Les messages à traduire sont extraits automatiquement depuis le code source. Ceci permet aux développeurs de ne pas se soucier des traductions, et, globalement pour le projet, de ne pas oublier des traductions.
• Pouvoir changer la langue de l'interface utilisateur sans recharger la page.

Utilisation d'un système de type "gettext" aussi bien pour les messages "serveur" que pour les messages "client".

Pour les messages "serveur", c-à-d ceux du code Python et des template Mako, c'est le module Python Lingua qui sera utilisé. Lingua est le module préconisé par Pyramid. Son fonctionnement n'est pas différent de celui de Babel, qui était le module précédemment utilisé.

Pour les messages "client", c-à-d ceux du code JavaScript et des templates Angular, c'est angular-gettext qui sera utilisé. C'est grâce à cet outil et les mécanismes de binding d'Angular que la langue pourra être changée sans rechargement de la page. Voici, par exemple, comment un message est marqué "à traduire" avec angular-gettext: <h1 translate>Hello!</h1>.

Pour l'extraction des messages depuis le code "client", et la création du fichier pot, un outil dédié doit être utilisé. Cet outil doit en effet détecter l'utilisation de la directive "translate" dans le code. L'outil utilisé sera angular-gettext-tools. C'est un outil node.

Il faut noter ici que les traductions "client" et "serveur" du projet seront dans des fichiers pot/po différents. Ceci est lié au fait que des outils différents sont utilisés pour extraire les messages. Par ailleurs, il n'est pas souhaitable d'envoyer toutes les traductions ("client" + "serveur") au navigateur. Avec des fichiers po spécifiques pour les messages "client" on sait où sont les traductions à envoyer au navigateur. Nous pensons que ceci ne complique pas la tâche du traducteur, il aura deux fichiers (par langue) à éditer mais ceux-ci auront exactement la même structure. Et avec un système comme Transifex les choses seront encore plus transparentes pour le traducteur.

Les messages (clés) de traduction relatifs aux thèmes, groupes et couches seront dans la base de donnée plutôt que dans le code. Il faut aussi pouvoir extraire ces messages. Pour ceci un extracteur Lingua custom sera développé et utilisé. Cet extracteur Lingua fera des requêtes à la base de donnée pour en extraire les messages.

Les fichiers po sont compilés. Ils seront compilés en fichiers mo dans le cas de Lingua. Ils seront compilés en fichiers json dans le cas d'angular-gettext. L'outil angular-gettext-tools sera utilisé pour la génération des fichiers json.

Pour ne pas charger les traductions de toutes les langues dans le navigateur, les traductions seront chargées à la demande, quand la langue change. Quand la langue change le code JS (angular-gettext) fera une requête Ajax pour récupérer un doc JSON des traductions dans la nouvelle langue.

Nous n'avons parlé que des traductions "projet" jusqu'ici. Les traductions des "libs" (ngeo et c2cgeoportal) seront complètement gérées dans les libs elles mêmes, et ne concerneront pas du tout les traducteurs "projet". En tout cas, les mêmes systèmes et principes seront utilisés pour les traductions des "libs".

Les fichiers json envoyés au navigateur devront contenir les traductions "projet" et les traductions "lib" (ngeo). Pour ceci l'outil de compilation po -> json devra faire un merge des po "lib" et "projet". Ceci veut aussi dire que des conflits entre les traductions "lib" et "projet" sont possibles. Plusieurs stratégies sont alors une possible. En donnant la priorité aux traductions "projet" on autorise la surcharge des traductions "lib" par le traducteur "projet".

Note supplémentaire concernant ngeo : la version standalone de ngeo (ngeo.js) doit contenir angular-gettext.min.js ainsi que toutes les traductions dans toutes les langues supportées par ngeo. On utilisera donc le format "javascript" du compilateur d'angular-gettext-tools plutôt que le format "json" dans ce cas là. Dans le futur on pourra éventuellement permettre de créer des builds ngeo.js qu'avec un sous-ensemble des langues supportées.

This how we can switch language programmatically (in the dev tools console):

$(document.body).scope().mainCtrl.switchLanguage('en')