Internationnalisation (i18n)

Le code de Galette est entièrement traduit à l’aide des possibilités offertes par GNU Gettext. L’intégralité des chaînes contenues dans le code source doivent être en anglais.

Le répertoire lang contient un certain nombre de fichiers :

  • Makefile, make_lang_l12n.py, xgettext.py : fichiers de génération divers,
  • *.pot : fichiers de template des traductions, un par domaine,
  • *.po : fchiers de traduction, un par langue et par domaine,
  • *.php : fichier de traduction PHP (générés depuis les fichiers de langue gettext).

Les traductions de Galette en elles-mêmes sont effectuées via la plate forme Zanata.

Syntaxe

Deux types de syntaxes différentes peuvent être rencontrées :

  • la syntaxe PHP,
  • la syntaxe Smarty.

PHP

Pour la syntaxe PHP, on utilise la function « _T » :

<?php
echo _T("Hello world!");
echo _T("Hello world!", "galette"); //galette is the default domain
?>

Le second paramètre est le domaine de traduction, le domaine par défaut sera utilisé si rien n’est précisé.

Il est souvent nécessaire d’utiliser des variables à remplacer dans les chaînes à traduire. Via PHP, on utilisera simplement une fonction du type str_replace ou preg_replace pour arriver à nos fins :

<?php
echo str_replace('%name', $adh->name, _T("Hello %name!"));
?>
<?php
$search = array(
   '/%name/',
   '/%surname/',
   '/%town/'
);
$replace = array(
   $adh->name,
   $adh->surname,
   $adh->town
);
echo preg_replace(
   $search,
   $replace,
   _T("Hello %name %surname from %town")
);
?>

Une fonction __() est également disponible ; la seule différence avec _T(), c’est que les chaînes non traduites ne seront pas marquées comme telles (utilisé principalement pour les routes).

Bien entendu, les patterns sont laissés à votre entière discrétion ; pensez seulement que la personne qui traduira pourra mieux contextualiser la chaîne si les variables à remplacer sont un minimum identifiée (nous aurions par exemple pu choisir %s au lieu de %name ; mais ça aurait été moins explicite :-) ).

Smarty

La syntaxe smarty se base sur un plugin développé pour la cause, on l’utilisera de la façon suivante :

<p>{_T string="Hello world!"}</p>
<p>{_T string="Hello world!" domain="galette"}</p>

Smarty propose des modifiers pour par exemple effectuer des remplacements. Le problème ; c’est que le remplacement est effectué avant que le texte ait été récupéré, la traduction n’est donc jamais trouvée. Pour pallier à ce problème, notre plugin smarty prend en charge deux attributs supplémentaires : un pattern et une valeur de remplacement ; qui ne seront appliquées qu’une fois la chaîne traduite récupérée :

<p>{_T string="Hello %name!" pattern="/%name/" replace=$adh->name}</p>

La note concernant le nommage des patterns du précédent paragraphe s’applique ici aussi, bien entendu ;-)

Domaines de traduction

Nouveau dans la version 0.9.

Les traductions dans Galette utilisent un système de domaine pour éviter que les chaînes provenant de différentes sources n’entrent en collision. Le domaine par défaut (utilisé si rien n’est spécifié) se nomme galette. Un domaine galette_routes (spécifique aux… routes :D) est également disponible.

Chaque plugin fournira son propre domaine à minima (la plupart des plugins officiels fournissent également un domaine spécifique pour leurs routes).

Lors de l’appel aux fonctions de traduction, il faudra donc spécifier le domaine :

<?php
echo _T('Hello, you'); //utilisation du domaine Galette ; la traduction sera 'Bonjour, vous'
echo _T('Hello, you', 'another'); //utilisation du domaine another ; la traduction sera 'Salut, toi'

Le même exemple, avec Smarty :

{_T string="Hello, you!"}
{_T string="Hello, you!" domain="another"}

Génération des fichiers de langue

La mise à jour des traductions de Galette se décompose en plusieurs étapes :

  • Extraction des chaînes du code source et mise à jour des templates de traduction,
  • Envoi des ouveaux templates sur Zanata,
  • Récupération des traductions depuis Zanata,
  • Génération des fichiers MO et PHP.
$ cd galette/lang
$ make extract
$ cd ../../
$ zanata-cli push

Il est possible de générer les fichiers PO en local avec la commande make po, mais le système est prévu pour qu’ils soient générés automatiquement par Zanata lors de la récupération des données.

$ zanata-cli pull
$ cd galette/lang
$ make mo lang check

Note

Chaque domaine de traduction est stocké dans ses propres fichiers.