Comment fonctionne la traduction multilangue dans Yacs

Le texte dans les programmes php

Lorsqu'un programme php de Yacs a besoin d'afficher un texte, il utilise la fonction "s" du fichier i18n / i18n.php

Par exemple :

$label = i18n::s('My text in english');

A l'execution du fichier .php, si la traduction existe, cette fonction va renvoyer la phrase dans la langue du visiteur (celle paramétrée dans son profil de membre s'il est connecté, ou celle de son navigateur sinon).

Si aucune traduction n'est trouvée, le terme initial est affiché ("My text in english").

Dans le code php des programmes, on ne s'occupe donc pas des traductions mais on se contente :

• d'utiliser la fonction i18n::s à chaque fois qu'un texte est défini
• d'écrire le texte en anglais

Préparation des traductions

Afin de pouvoir traduire les textes, on va lancer un programme qui va analyser tous les fichiers .php pour y trouver tous les textes à traduire (ceux qui font appellent à la fonction i18n::s).

On trouve ce programme dans /tools/ :

• build_i18n.bat (pour windows)
• build_i18n.sh (pour linux)

Ce programme va parcourir les différents dossiers d'origine de Yacs, parcourir tous les fichiers .php et générer des fichiers .pot qui sont stockés dans / i18n / templates / (1 fichier par dossier et dont le nom correspond au dossier. Par exemple : articles.pot).

Ces fichiers .pot  recensent les différents textes à traduire en indiquant, en commentaire, dans quelles lignes de quels fichiers ils ont été trouvés :

<p> #: sections/delete.php:117 sections/duplicate.php:156</p>
msgid "The action has not been confirmed."

signifie que le texte "The action has not been confirmed." a été trouvé à la ligne 117 du fichier sections/delete.php et à la ligne 156 de : sections/duplicate.php.

Si l'on a créé de nouveaux dossiers à analyser dans /yacs, il faudra modifier le programme build_i18n pour qu'il les prenne également en compte.

Le programme génère également, à partir des fichiers .pot, des fichiers .po qui serviront pour les traductions et qui sont stockées dans les dossiers /i18n/locale/en (pour l'anglais) et /i18n/locale/fr (pour le français). Là aussi, les fichiers créés reprennent le nom du dossier correspondant (par exemple : articles.po).

Traductions

Pour réaliser les traductions, on utilise le logiciel Poedit à télécharger gratuitement sur Internet.

Poedit permet d'ouvrir les fichiers .po et de compléter les traductions des termes en anglais :

Une fois les traductions réalisées et les fichiers .po enregistrés, un fichier .mo est créé (ou mis à jour) par Poedit. Il s'agit d'un fichier contenant les traductions sous un format "compilé" plus rapide à lire par yacs.

Termes à traduire manquants

Si vous constatez qu'il manque des termes à traduire, il a probablement eu un problème lors de la construction du fichier .pot

Pour s'en assurer, changez le nom du .pot correspondant (dans le dossier /i18n/templates). Relancer le programme de génération des .pot (/tools/build_i18n.bat) et vérifier si un nouveau fichier .pot a été reconstruit. Dans le cas contraire, recherchez l'origine du problème.

Pour cela (sous Windows), ouvrir une console "DOS" et exécutez manuellement les commandes du fichier build_i18n.bat qui concerne le module posant problème.
Après chaque exécution de commande, regardez s'il n'y a pas un message d'erreur.

Par exemple : 

<p>xgettext: Non-ASCII string at images/manage.php:75.</p>
Please specify the source encoding through --from-code.

xgettext: Non-ASCII string at

Ce type d'erreur peut être causé par la présence d'un caractère accentué (y compris un caractères accentué dans un commentaire précédant la ligne indiquée !)

Traduction au format php

Yacs est capable de récupérer les textes traduits dans les fichiers .mo

Cependant, Yacs peut être encore plus rapide en utilisant des fichiers .mo.php qui chargent en mémoire les termes traduits, en les affectant directement dans le tableau $_SESSION['l10n'] :

<p> ...
 $_SESSION['l10n']['fr']['Add a file']='Ajouter un fichier';</p>
<p>$_SESSION['l10n']['fr']['Add a link']='Ajouter un lien';
 ...</p>
 

C'est ce grand tableau qui est lu à chaque fois que Yacs à besoin d'obtenir la traduction d'un terme.

Ces fichiers .mo.php sont automatiquement générés par / i18n / i18n.php lorsque le module yacs correspondant est appelé... à condition que l'on soit en mode debug ! (sinon, c'est une ancienne version stockée qui est chargée, pour éviter de reconstruire à chaque fois le fichier .mo.php)

Pour passer en mode debug : 

Modification d'un texte

Pour modifier la traduction d'un texte, ouvrir le fichier .po correspondant dans / i18n / local / fr /

Recherche le terme, le modifier et enregistrer.

Régénérer ensuite le fichier .mo.php en repassant temporairement en mode debug.

Vous pouvez parfois constater que le terme affiché n'a pas changé . Cela signifie que ce même terme a déjà été traduit dans un autre fichier .po. Or, un terme traduit est stocké de manière unique dans le tableau des traductions. Un même terme anglais utilisé dans 2 modules yacs différents ne pourra pas avoir 2 traductions différentes.

Conclusion : soit il s'agit d'un terme mal traduit et dans ce cas, il faut modifier sa traduction dans tous les .po où il est déclaré (sans que rien n'indique dans quel .po il est présent )

Soit il s'agit d'un terme différent de celui utilisé dans les autres .po et dans ce cas, il faut modifier le texte en anglais dans le fichier .php qui l'utilise. On relance ensuite le programme / tools / build_i18n.xx puis on réalise la traduction avec Poedit et l'on régénère le .mo.php en repassant en "mode debug".

Dans tous les cas, ne sachant pas dans quels fichiers donc dans quel contexte sont utilisé les textes traduits, on a toujours intérêt à ce que la traduction correspondant effectivement au texte en anglais pour éviter les mauvaises surprises...