Lorsqu’un plugin ou un thème WordPress est développé pour l’internationalisation i18n, c’est-à-dire avec les fonctions gettext()
de WordPress, telles que __()
, _e()
, esc_html__()
, …, il faut créer un fichier .pot
ou un fichier .po
pour traduire les chaînes.
Fichiers .pot
, .po
, .mo
Un fichier .pot
Portable Object Template, est un fichier texte qui contient toutes les chaînes du plugin ou du thème WordPress à traduire. Il ne comporte aucune traduction. C’est le fichier que l’on donne aux traducteurs, pour créer un fichier texte .po
Portable Object et un fichier compilé .mo
Machine Object pour un langage.
Un article de ce site traîte de la mise en place d’un fichier .po
pour un nouveau plugin en partant de rien. Il est possible d’obtenir un fichier .pot
à partir d’un fichier .po
, mais le mieux est de faire le contraire, le fichier .pot
étant le point de départ de toute traduction.
WP CLI
WP CLI
Command Line Interface est un ensemble d’outils en ligne de commande permettant d’effectuer un certain nombre d’actions intéressantes pour WordPress. Il permet en particulier de créer automatiquement un fichier .pot
pour un thème ou un plugin, que l’on pourra éditer avec un outil gratuit tel que POEdit.
Installation
On télécharge le fichier avec curl
:
1 |
xavier@machine:~$ curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar |
On vérifie le fichier téléchargé :
1 |
xavier@machine:~$ php wp-cli.phar --info |
On rend le fichier exécutable, et on le déplace dans /usr/local/bin
en le renommant wp
, on aura alors la commande wp
disponible :
1 2 |
xavier@machine:~$ chmod +x wp-cli.phar xavier@machine:~$ sudo mv wp-cli.phar /usr/local/bin/wp |
Vérification
On vérifie que cela fonctionne :
1 2 3 4 5 6 7 8 9 10 11 12 13 |
xavier@machine:~$ wp --info OS: Linux 4.15.0-117-generic #118-Ubuntu SMP Fri Sep 4 20:02:41 UTC 2020 x86_64 Shell: /bin/bash PHP binary: /usr/bin/php7.4 PHP version: 7.4.10 php.ini used: /etc/php/7.4/cli/php.ini WP-CLI root dir: phar://wp-cli.phar/vendor/wp-cli/wp-cli WP-CLI vendor dir: phar://wp-cli.phar/vendor WP_CLI phar path: /home/xavier WP-CLI packages dir: WP-CLI global config: WP-CLI project config: WP-CLI version: 2.4.0 |
La commande wp
est disponible globalement.
Créer un fichier .pot
Pour créer le fichier modèle de traduction .pot
, on se rend dans le répertoire principal du plugin ou du thème. On crée, si ce n’est déjà fait, le répertoire des fichiers de langages défini avec load_plugin_textdomain()
ou load_theme_textdomain()
. La plupart du temps, on le nomme languages/
ou lang
/.
Dans le répertoire principal du plugin ou du thème, on lance la commande :
Pour un plugin
textdomain
est défini dans la fonction load_plugin_textdomain()
, c’est-à-dire le nom donné par plugin_basename( __FILE__ )
dans le fichier php
où est déclaré le plugin dans la zone des commentaires au début du fichier. On ajoute le paramètre locale
en_US
car un plugin ou un thème est développé pour i18n
en utilisant des chaînes en anglais américain.
1 |
xavier@machine:~$ wp i18n make-pot . languages/textdomain-en_US.pot |
Pour un theme
1 |
xavier@machine:~$ wp i18n make-pot . languages/en_US.pot |
Voir cet article pour le nommage des fichiers .po
avec le textdomain
et le paramètre locale
.
Exemple
Pour un plugin murviel-info-beziers
, on charge le textdomain
avec le crochet hook init
dans le fichier principal php
:
1 |
load_plugin_textdomain( 'mib', false, dirname( plugin_basename( __FILE__ ) ) . '/languages' ); |
__FILE__
est le chemin au fichier principal du plugin dans lequel on se trouve, soit /var/www/.../wp-content/plugins/murviel-info-beziers/murviel-info-beziers.php
.
plugin-basename( __FILE__ )
est le chemin relatif du fichier principal du plugin dans le dossier des plugins de WordPress, soit murviel-info-beziers/murviel-info-beziers.php
.
dirname( plugin_basename( __FILE__ )
est le nom du dossier soit murviel-info-beziers
.
mib
est le textdomain
.
On se place dans le dossier murviel-info-beziers
, le sous-dossier languages
existe. Et l’on entre la commande suivante :
1 2 3 4 5 |
xavier@machine:/var/.../wp-content/plugins/murviel-info-beziers$ wp i18n make-pot . languages/mib-en_US.pot Plugin file detected. Warning: The string "Your account has been blocked, you must wait %s!" contains placeholders but has no "translators:" comment to clarify their meaning. (includes/class-failed-login.php:69) Warning: The string "Murviel Info Beziers is missing requirements and has been <a href="%s">deactivated</a>. Please make sure all requirements are available." contains placeholders but has no "translators:" comment to clarify their meaning. (murviel-info-beziers.php:301) Success: POT file successfully generated! |
Le fichier .pot
est créé. Les avertissements sont des faux positifs, car le placeholder
dans la fonction __()
est le résultat d’une fonction.
1 |
$default_message = sprintf( __( 'Murviel Info Beziers is missing requirements and has been <a href="%s">deactivated</a>. Please make sure all requirements are available.', 'mib' ), admin_url( 'plugins.php' ) ); |
Entête du fichier .pot
Le début du fichier .pot
, ou l’entête du fichier et les premières lignes à traduire, créé par WP_CLI est le suivant :
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 36 37 |
# Copyright (C) 2020 Xavier Birnie-Scott # This file is distributed under the same license as the Clionautes Manager plugin. msgid "" msgstr "" "Project-Id-Version: Clionautes Manager 2.1.1\n" "Report-Msgid-Bugs-To: https://wordpress.org/support/plugin/clio-manager\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" "Language-Team: LANGUAGE <LL@li.org>\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "POT-Creation-Date: 2020-09-29T10:43:58+02:00\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "X-Generator: WP-CLI 2.4.0\n" "X-Domain: cliomanager\n" #. Plugin Name of the plugin msgid "Clionautes Manager" msgstr "" #. Plugin URI of the plugin msgid "http://murviel-info.com/wp-plugin/cliomanager" msgstr "" #. Description of the plugin msgid "Styles and scripts for Clionautes sites" msgstr "" ... #: clio-manager.php:276 msgid "Clio Manager is missing requirements and has been <a href=\"%s\">deactivated</a>. Please make sure all requirements are available." msgstr "" #: includes/class-admin.php:180 msgid "Clio Medium" msgstr "" |
L’entête est ce qui permettra aux logiciels de traduction, POEdit en particulier, de mettre à jour le catalogue qui est essentiel à la traduction. Il doit indiquer, outre le titre du projet, le nom du traducteur, le jeu de caractères utilisé …, le chemin relatif pour accéder aux fichiers, les instructions ou fonctions de traduction, la forme des pluriels … La langue de traduction sera demandée lors du chargement du fichier afin de gérer les différents langages et la génération des fichiers .po
et .mo
. Une fois le fichier .po
créé, il suffira de lancer ce fichier pour compléter une traduction.
Changer et compléter l’entête pour POEdit :
Changement du nom du traducteur ou de l’équipe :
1 2 |
"Last-Translator: xavier bs <xavier_bs@murviel-info.com>\n" "Language-Team: xavier bs <xavier_bs@murviel-info.com>\n" |
Chemin relatif des fichiers php
:
1 |
"X-Poedit-Basepath: ..\n" |
Chemin de recherche pour POEdit :
1 |
"X-Poedit-SearchPath-0: .\n" |
Jeu de caractères :
1 |
"X-Poedit-SourceCharset: UTF-8\n" |
Liste des fonctions php
de traduction :
1 2 3 |
"X-Poedit-KeywordsList: __;_e;_n:1,2;_x:1,2c;_ex:1,2c;_nx:4c,1,2;esc_attr__;" "esc_attr_e;esc_attr_x:1,2c;esc_html__;esc_html_e;esc_html_x:1,2c;_n_noop:1,2;" "_nx_noop:3c,1,2;__ngettext_noop:1,2\n" |
La forme des pluriels :
La forme des pluriels peut changer selon les langues. En français, on n’accorde pas 0, comme dans 0 article. En anglais, cela s’accorde : 0 posts. Il faudra alors changer cela en fonction des langages. Pour le français :
1 |
"Plural-Forms: nplurals=2; plural=(n > 1);\n" |
Pour l’anglais, cela sera :
1 |
"Plural-Forms: nplurals=2; plural=(n != 1);\n" |
Chaînes d’origine et traduite :
La chaîne d’origine est indiquée avec la variable ou le paramètre msgid
, la chaîne traduite par msgstr
. En commentaire, devant la définition des chaînes, on trouve le titre ou l’emplacement de la chaîne dans le code, voir l’exemple plus haut. Pour les pluriels, la variable du pluriel est msgid_plural
, les chaînes traduites sont un tableau msgstr[0]
, msgstr[1]
. La variable indiquant le contexte pour le traducteur (dans la fonction _x()
par exemple) est msgctxt
.
Et hop, le fichier modèle .pot
est prêt, on peut traduire le plugin avec POEdit. Lorsque le plugin sera fini, il ne faudra pas oublier de regénérer un fichier .pot
pour la version de production, disponible aux traducteurs.