Internationalisation de WordPress : comment traduire les thèmes et les extensions WordPress

Préparer votre thème ou extension WordPress pour la traduction

Avant de pouvoir traduire quoi que ce soit, vous devez configurer votre code correctement. Cela implique de définir un domaine de texte, d’encapsuler toutes les chaînes destinées à l’utilisateur dans des fonctions gettext et de générer un fichier POT.

Rien de tout cela n’est compliqué, mais les détails comptent. Un domaine de texte mal assorti ou une chaîne non encapsulée signifie que ce texte n’apparaîtra jamais dans votre version traduite.

Chaque thème ou extension a besoin d’un domaine de texte. C’est un identifiant unique qui indique à WordPress quels fichiers de traduction appartiennent à votre projet, et il doit correspondre exactement au slug de votre extension ou thème.

Déclarez-le dans l’en-tête du fichier principal de votre extension :

/**
 * Plugin Name: My Plugin
 * Text Domain: my-plugin
 * Domain Path: /languages
 */

/**
 * Plugin Name: My Plugin
 * Text Domain: my-plugin
 * Domain Path: /languages
 */

Ou dans le style.css de votre thème :

/*
Theme Name: My Theme
Text Domain: my-theme
Domain Path: /languages
*/

/*
Theme Name: My Theme
Text Domain: my-theme
Domain Path: /languages
*/

Le chemin du domaine indique à WordPress où se trouvent vos fichiers de traduction par rapport à la racine de l’extension ou du thème. Le répertoire /languages est la norme.

Toute chaîne que vous souhaitez rendre traduisible doit être encapsulée dans l’une des fonctions gettext de WordPress. Lors de l’exécution, ces fonctions recherchent la traduction correcte et reviennent à la chaîne d’origine si aucune traduction n’est trouvée.

Chaînes de base

Utilisez __() lorsque vous devez renvoyer une chaîne. Pour une sortie HTML (ce qui est presque toujours le cas), utilisez les variantes échappées :

// Return a translated string
$label = __( 'Settings', 'my-plugin' );

// Echo a translated string, escaped for HTML
echo esc_html__( 'Settings saved.', 'my-plugin' );

// Return a translated string
$label = __( 'Settings', 'my-plugin' );

// Echo a translated string, escaped for HTML
echo esc_html__( 'Settings saved.', 'my-plugin' );

Les normes de codage de WordPress recommandent echo esc_html__() plutôt que _e() car cela rend l’échappement de la sortie explicite. C’est une bonne habitude à appliquer systématiquement.

Chaînes avec variables

Si vous concaténez une variable directement dans une chaîne, les traducteurs ne voient que les fragments et non la phrase complète. Cela rend la traduction correcte impossible, en particulier dans les langues où l’ordre des mots est différent. Utilisez plutôt printf() ou sprintf() avec un placeholder, et ajoutez un commentaire pour le traducteur afin qu’il sache ce que %s représente :

printf(
    /* translators: %s: the user's display name */
    esc_html__( 'Welcome back, %s.', 'my-plugin' ),
    esc_html( $display_name )
);

printf(
    /* translators: %s: the user's display name */
    esc_html__( 'Welcome back, %s.', 'my-plugin' ),
    esc_html( $display_name )
);

Formes plurielles

En anglais, les pluriels sont simples : un commentaire, deux commentaires. D’autres langues ne sont pas aussi directes. Certaines possèdent plusieurs formes de pluriel selon le nombre. Utilisez _n() pour gérer cela correctement, quelle que soit la langue dans laquelle votre extension est traduite :

printf(
    esc_html( _n(
        '%s comment',
        '%s comments',
        $count,
        'my-plugin'
    ) ),
    number_format_i18n( $count )
);

printf(
    esc_html( _n(
        '%s comment',
        '%s comments',
        $count,
        'my-plugin'
    ) ),
    number_format_i18n( $count )
);

Chaînes nécessitant un contexte

Certains mots ont des significations différentes selon l’endroit où ils apparaissent. Utilisez _x() pour donner aux traducteurs le contexte dont ils ont besoin pour obtenir la bonne traduction :

// "Export" as a noun (the file) vs. a verb (the action)
echo esc_html_x( 'Export', 'button label', 'my-plugin' );

// "Export" as a noun (the file) vs. a verb (the action)
echo esc_html_x( 'Export', 'button label', 'my-plugin' );

WordPress fournit le paquet wp-i18n afin que vous puissiez utiliser en JavaScript les mêmes fonctions gettext qu’en PHP. Lors de l’enregistrement de votre script, déclarez wp-i18n comme dépendance :

wp_register_script(
    'my-plugin-script',
    plugins_url( 'js/app.js', __FILE__ ),
    array( 'wp-i18n' ),
    '1.0.0',
    true
);

wp_register_script(
    'my-plugin-script',
    plugins_url( 'js/app.js', __FILE__ ),
    array( 'wp-i18n' ),
    '1.0.0',
    true
);

Ensuite, dans votre fichier JavaScript :

const { __, _n, sprintf } = wp.i18n;

const message = __( 'Settings saved.', 'my-plugin' );

const { __, _n, sprintf } = wp.i18n;

const message = __( 'Settings saved.', 'my-plugin' );

Si vous utilisez un bundler comme Webpack, utilisez @wordpress/babel-plugin-makepot pour extraire les chaînes traduisibles de votre bundle dans le cadre de votre processus de build.

Une fois vos chaînes encapsulées, vous devez générer un fichier POT (Portable Object Template). C’est le fichier source à partir duquel PTC (ou tout traducteur) travaille. Il contient toutes vos chaînes traduisibles, mais aucune traduction pour l’instant.

Exécutez cette commande depuis le répertoire racine de votre extension ou thème :

wp i18n make-pot . languages/my-plugin.pot

wp i18n make-pot . languages/my-plugin.pot

WP-CLI analyse vos fichiers PHP, JavaScript et block.json à la recherche d’appels gettext et les compile dans un seul fichier POT. Si vous utilisez Composer, vous pouvez ajouter cela en tant que script Composer afin que la commande reste cohérente pour toute votre équipe et ne nécessite pas d’installation globale de WP-CLI.

La suite complète wp i18n comprend tout ce dont vous aurez besoin plus tard dans le flux de travail :