Localisation d'un plugin

Cette page est destiné à la localisation d'un plugin, c'est à dire à la création d'un dossier locales puis d'un sous dossier par langue et enfin du fichier main.po qui contiendra la traduction dans une langue d'un plugin.

Guide d'utilisation des fichiers de localisation

Mécanique générale

Chaque plugin contient du texte qui ne doit pas être inscrit en dur dans le code mais doit pouvoir être adapté pour toutes les langues. Pour ce faire, les fichiers avec l'extension "po" sont ajoutés. Ce sont ces fichiers qui, une fois interprétés par le moteur de dotclear2, vont remplacer, en façade de votre blog, les codes tels que

<?php echo __('Maintenance'); ?>

par le mot ou la phrase associée dans la langue du blog. Pour ceci, il faut que le plugin dispose d'une traduction dans la langue souhaitée. Vous trouverez ci-dessous le détail des différents fichiers.

Organisation des fichiers

Le dossier locales

Nommé locales, ce dossier accueille les dossiers contenant les langues vers lesquelles le plugin est traduit. Par exemple il peut contenir :

un dossier fr qui contiendra les fichiers pour la traduction en français
un dossier en qui lui sera pour la version anglaise (facultatif)
etc.

Le fichier main.po

Exemple de localisation :

# French translation of DotClear
# Copyright (C) 2006.
# Olivier Meunier <olivier@dotclear.net>, 2006.
#
msgid ""
msgstr "Content-Type: text/plain; charset=UTF-8\n"
...
#: plugins/maintenance/index.php:74
#, php-format
msgid "Indexing entry %d to %d."
msgstr "Index des billets %d à %d"
...

Les 3 premières lignes contiennent les commentaires du traducteur.

La langue de traduction,
La licence associée au fichier,
Le nom, le mail de l'auteur ainsi que la date de traduction du fichier.

Décomposons ce code pour définir les fonctions de chaque ligne utilisée :

msgid ""
msgstr "Content-Type: text/plain; charset=UTF-8\n"

Ces deux lignes permettent de définir le format du fichier ainsi que la méthode de codage des caractères. Ici, il est de type texte et utilise l'encodage UTF-8. (pour plus d'information sur les encodages : Site du W3C)

#: plugins/maintenance/index.php:74

Cette ligne indique le fichier dans lequel est appelé la traduction et à quelle ligne elle est appelée.

Si il y a plusieurs appels d'une même traduction, il suffit d'indiquer toutes les lignes comme dans l'exemple suivant :

#: plugins/maintenance/index.php:87 plugins/maintenance/index.php:111

Si les appels sont nombreux, vous pouvez également utiliser une syntaxe qui tient sur plusieurs lignes, comme dans cet autre exemple :

#: inc//core/class.dc.blog.php:1497 inc//core/class.dc.blog.php:1503
#: inc//core/class.dc.blog.php:1565
msgid "No such comment ID"
msgstr "Identifiant du commentaire inconnu"

Optionnellement, on peut indiquer que la traduction contient des variables PHP :

#, php-format

Dans notre cas, le %d est une variable PHP de type numérique.

msgid "Indexing entry %d to %d."

Attention :

Notez que d'autres types de variables existent. Par exemple, pour passer une variable de type texte, il faut utiliser %s à la place de %d. Pour en savoir plus sur les types de variables et comment les utiliser, lisez la documentation PHP sur la fonction sprintf.

Le mot-clé msgid associe un identifiant unique à la traduction. Il est donc important de ne jamais donner deux traductions différentes au même identifiant.

msgstr "Index des billets %d à %d"

Enfin le mot-clé msgstr contient la traduction tant attendue.

Si on regarde dans le fichier index.php comme indiqué, à la ligne 74… heu 77

	echo '<p>'.sprintf(__('Indexing entry %d to %d.'),$start,$start+$limit).'</p>';

Voici donc l'appel de la traduction. À la place de "%d to %d", elle contiendra le contenu des variables $start et $start+$limit.

Astuce :

Comme le montre cet exemple, le commentaire concernant la ligne associée à la traduction n'est plus correct, il semblerait que 3 lignes ont été ajoutées depuis au début du fichier index.php du plugin. Il est donc pertinent de mettre à jours son fichier de traduction quand on apporte des modifications aux fichiers qui contiennent des textes à traduire.

À noter également :

Le mot-clé msgid ne peut se terminer par un espace, exemple "Ma chaine" sera trouvée et remplacée par sa traduction mais pas "Ma chaine "
Un script shell permettant de créer un squelette existe voir po_update.sh
Un petit billet de Zeiram membre du forum existe aussi sur l'utilisation de gettext (voir ici)
L'existence d'un plugin de traduction Translater

Le fichier public.po

Il s'écrit de la même manière que le fichier main.po et traduira les chaines qui apparaissent du côté public du blog.

Attention :

Ne pas oublier de rajouter l10n::set(dirname(FILE).'/locales/'.$_lang.'/public'); dans le fichier _public.php du thème/plugin.

Liens connexes :

Ajouter des traductions dans les thèmes (Tips DotAddict)

Les exceptions de certains plugins

Certains plugins préfèrent utiliser les anciennes méthodes utilisées par Dotclear 1 ou encore faire un mélange des deux méthodes. Ces méthodes sont à proscrire donc nous ne ferons qu'effleurer le sujet.

Méthode Dotclear 1

Peut être dans le but d'une adaptation rapide vers Dotclear2 tel que le plugin newsletter,

Le fichier main.lang.php

Même principe que pour Dotclear 2 sauf que tout est réuni en une ligne et qu'on ne sait pas quels sont les fichiers qui l'appellent.

$GLOBALS['__l10n']['Newsletter'] = 'Lettre d\'informations';

Astuce :

Les fichiers *.lang.php sont traités plus rapidement que les fichiers *.po. Il est possible de créer les traductions dans un fichier .po puis de générer un fichier .lang.php correspondant.

Méthode Dotclear 1 & 2

Ils utilisent à la fois le fichier "main.po" et le fichier "main.lang.php" qui sont redondants tel que les plugins ThemeSwitcher, gallery, CSScompress, minialbum.

Astuce :

Il faut savoir que c'est le fichier "main.lang.php" qui a la priorité sur le fichier "main.po". Si l'un des deux n'est pas présent Dotclear2 prend l'autre sinon il prend main.lang.php.

Sans traduction

Ou encore d'autres ne les utilisent pas. Cette méthode est à proscrire bien entendu.