Internationaliser (traduire) un plug-in WordPress

Pour celles et ceux qui ont déjà écrit un plug-in WordPress, il peut être intéressant de le traduire dans différentes langues afin que des utilisateurs du monde entier puissent l’utiliser correctement, dans leur langue maternelle. Le système d’internationalisation (i18n) intégré à WordPress utilise l’utilitaire gettext, et se base sur des catalogues (un par langue). On trouve de la documentation sur Internet, certes, mais ce n’est pas toujours clair ni complet, et surtout pas souvent en français. D’où ce petit article

Identifier les chaînes à traduire

Dans votre code PHP, identifiez les différentes chaînes à traduire et remplacez-les par un appel à une des fonctions PHP suivantes :

• __() : pour récupérer la chaîne traduite (return),
• _e() : pour afficher la chaîne traduite (echo),
• _n() : pour gérer les formes plurielles (return).

Prenons un exemple qui affiche une liste d’éléments. On aimerait l’affichage suivant :

• si la liste est vide : La liste est vide.
• si la liste contient un seul élément : La liste contient un élément.
• si la liste contient plusieurs éléments : La liste contient <n> éléments.

Avant :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

<?php
$elements = array();
$count = count($elements);
?>
<div class="list">
 
   <div class="header">
   <?php if ($count == 0) { ?>
   La liste est vide.
   <?php } else if ($count == 1) { ?>
   La liste contient un élément.
   <?php } else { ?>
   La liste contient <?= $count ?> éléments.
   <?php } ?>
   </div>
 
   <ol class="elements">
   <?php
   foreach ($elements as $elm) {
      ?><li><?= $elm ?></li><?php
   }
   ?>
   </ol>
 
   <form class="add">
      Ajouter un élément :
      <input type="text" name="label" />
      <input type="submit" value="Ajouter" />
   </form>
</div>

On cherche toutes les chaînes de texte et on les remplace par des appels aux fonctions PHP citées ci-dessus.

Après :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

<?php
$elements = array();
$count = count($elements);
?>
<div class="list">
 
   <div class="header">
   <?php
   printf(
      _n(
         "List contains %d element.",	// pour 0 ou 1
         "List contains %d elements.",	// pour 2 ou plus
         $count, // valeur pour différencier les deux cas
         "liste-plugin" // 'text-domain'
      ),
      $count // argument du format du printf (%d)
   );
   ?>
   </div>
 
   <ol class="elements">
   <?php
   foreach ($elements as $elm) {
   ?><li><?= $elm ?></li><?php
   }
   ?>
   </ol>
 
   <form class="add">
      <?php _e("Add element:", "liste-plugin"); ?>
      <input type="text" name="label" />
      <input type="submit" value="<?= __("Add", "liste-plugin") ?>" />
   </form>
 
</div>

• Ligne 10 : appel à _n() pour gérer les formes plurielles. Arguments :
  1. texte si 0 ou 1 élément (ligne 11),
  2. texte si 2 éléments ou plus (ligne 12),
  3. valeur utilisée pour choisir entre le texte 1 ou 2,
  4. text domain : généralement, le nom de votre plug-in.
• Ligne 30 : utilisation de _e() qui fait un echo() ;
• Ligne 32 : utilisation de __() qui retourne la chaîne.

Il est important de ne pas oublier le deuxième argument (ou quatrième pour _n()) correspondant au text domain, qui est généralement le nom de votre plug-in.

On va voir qu’on peut aller assez loin dans les traductions pour fournir un texte différent quand la liste est vide ($count = 0), mais ça ne se gère pas dans le code PHP. Nous aurons donc trois formes plurielles.

Créer le catalogue

Pour cela, nous allons utiliser l’utilitaire libre Poedit (télécharger).

Cet utilitaire, une fois correctement configuré (!), va retrouver les chaînes identifiées par __(), _e() et _n() directement dans le code PHP et créer un catalogue de traduction. Il s’agit d’un fichier texte dont l’extension est .po (d’où le nom de Poedit). Rassurez-vous : Poedit ne touche pas à vos fichiers PHP, il ne fait que les lire.

Allons-y !

1. Lancez Poedit.
2. Menu Fichier > Nouveau catalogue… puis remplissez les champs dans les 3 onglets comme indiqué ci-dessous :

Onglet 1 : quelques informations génériques

• Jeu de caractères : utf-8 (recommandé),
• Jeu de caractères du code source : utf-8 (recommandé),
• Formes plurielles : nplurals=3; plural=n<=1 ? n : 2; (nous allons gérer trois formes plurielles : si 0, si 1, si 2 ou plus).

Onglet 2 : emplacement des fichiers PHP à traduire

• Chemin de base : laissez la valeur proposée (.),
• Chemins : ajoutez l'entrée ... En effet, nous allons enregistrer le catalogue dans un sous-répertoire languages de notre plug-in et Poedit va alors chercher dans les fichiers du répertoire parent.

Onglet 3 : mots-clés permettant d'identifier les chaînes à traduire

Supprimez les entrées existantes de manière à avoir les 3 entrées suivantes :

1. __ (deux underscores)
2. _e
3. _n:1,2

Cliquez sur OK. Poedit vous demande où vous souhaitez enregistrer le catalogue de traduction. Créez un répertoire languages dans le répertoire de votre plug-in puis enregistrer le fichier sous le nom suivant : <nom-de-votre-plugin>-<code_locale>.po (par exemple : nom-du-plugin-fr_FR.po pour le fichier français). Après cela, Poedit va analyser vos fichiers PHP et devrait vous afficher une fenêtre contenant la liste des chaînes à traduire qu'il a trouvées (grâce aux marqueurs indiqués dans l'onglet 3) :

Vous pouvez ensuite traduire les chaînes trouvées dans l'interface principale de Poedit. Concernant les multiples formes plurielles, vous avez plusieurs zones de saisie en bas de la fenêtre pour éditer les différentes valeurs :

Si Poedit ne vous affiche pas ces trois zones de saisie, allez dans le menu Catalogue > Configuration..., vérifiez que le champ Formes plurielles est bien saisi puis cliquez sur OK.

Lorsque vous enregistrez, Poedit génère un autre fichier au même endroit que le fichier .po, avec l'extension .mo : c'est une version compactée (binaire) de votre catalogue, bien plus efficace à lire lors de l'exécution de votre script PHP.

Dans le code PHP

Pour que les traductions soient utilisées par les fonctions __(), _e() et _n(), il faut charger le catalogue de traduction avec la fonction load_plugin_textdomain(). Pour cela, dans votre plug-in WordPress, vous devez ajouter ceci :

1
2
3
4
5

function liste_plugin_load_text_domain() {
   $path = dirname(plugin_basename(__FILE__)) . '/languages/';
   load_plugin_textdomain('liste-plugin', null, $path);
}
add_action('init', 'liste_plugin_load_text_domain');

Puis, lors des appels aux fonctions de traduction, il faut spécifier en deuxième argument (quatrième pour _n()) le nom du text domain, généralement le nom de votre plug-in (ici : liste-plugin).

Traduire dans d'autres langues

Il vous suffit maintenant de dupliquer votre fichier languages/mon-plugin-fr_FR.po pour gérer les traductions dans d'autres langues ! Utilisez les codes de locales complet : mon-plugin-en_US.po, mon-plugin-en_GB.po, mon-plugin-de_DE.po, ... Ouvrez ces fichiers avec Poedit, modifiez les textes et enregistrez. Poedit génèrera alors les fichiers .mo correspondants.

Pour tester, modifiez la constante WP_LANG définie dans le fichier wp-config.php de votre installation de WordPress.