Internationalisation WordPress : comment traduire les thèmes et les plugins

Préparez votre thème ou plugin WordPress pour la traduction. Ce guide couvre les text domains, les fonctions gettext, la génération de POT et le mécanisme de chargement qui présente les traductions aux utilisateurs. PTC (Private Translation Cloud) traduit ensuite les fichiers de ressources et effectue une révision visuelle du thème ou plugin rendu dans chaque langue.

Ce guide s'adresse aux développeurs qui écrivent le code. Si vous avez déjà un fichier POT ou PO et que vous avez juste besoin de le traduire, consultez la page des fichiers PO pour découvrir le flux de travail en 3 étapes.

À la fin de ce guide, votre thème ou plugin sera :

Internationalisé correctement selon les standards de codage de WordPress.
Traduisible par PTC dans plus de 40 langues.
Distribuable via les Language Packs de WordPress.org.
Vérifiable à chaque version grâce à la révision visuelle de PTC.

Qu'est-ce que l'internationalisation WordPress ?

L'internationalisation (i18n) est le travail de préparation de votre code pour qu'il puisse être traduit. La localisation (l10n) est l'étape suivante. Elle produit les chaînes traduites réelles pour des langues spécifiques.

Pour les thèmes et plugins WordPress, l'i18n implique trois choses :

Encapsuler chaque chaîne destinée aux utilisateurs dans des fonctions gettext afin que WordPress puisse les remplacer à l'exécution.
Définir un text domain qui lie vos traductions à votre projet.
Générer un fichier POT à partir duquel les traducteurs (ou PTC) travaillent.

Une fois ce travail terminé, vous avez tout ce dont vous avez besoin pour produire des fichiers PO, MO, JSON et .l10n.php traduits pour n'importe quelle langue.

PTC traduit les fichiers POT en MO, JSON et .l10n.php pour WordPress

Cinq extensions de fichier apparaissent dans tout flux de travail de traduction WordPress. PTC traduit depuis .pot (votre source) vers .po, .mo, .json et .l10n.php pour chaque langue cible. Chaque format a un rôle spécifique :

POT (Portable Object Template). Le fichier source généré à partir de votre code. Il liste chaque chaîne traduisible sans aucune traduction associée. Vous le fournissez à PTC.
PO (Portable Object). Une copie du POT avec les traductions ajoutées pour une langue spécifique. Texte brut, lisible par l'humain. PTC renvoie un PO par langue cible.
MO (Machine Object). La version binaire compilée d'un PO. WordPress lit les fichiers MO à l'exécution car ils se chargent plus rapidement que le texte des PO.
JSON. L'équivalent JavaScript du MO. WordPress ne peut pas lire les MO depuis JavaScript, le pipeline de build produit donc des fichiers JSON pour les chaînes côté navigateur.
.l10n.php. Une alternative plus récente au MO, introduite dans WordPress 6.5. Il se charge plus rapidement et utilise moins de mémoire. WordPress le choisit automatiquement lorsqu'il en existe un aux côtés du fichier MO.

Activez .l10n.php pour les nouveaux projets. Il est strictement supérieur au MO sur les versions de WordPress prises en charge.

Pourquoi la traduction communautaire ne suffit pas

WordPress.org propose la traduction communautaire via GlotPress. En pratique, cela couvre une petite fraction de ce dont la plupart des plugins et thèmes ont besoin. Une analyse de plus de 60 000 plugins et thèmes WordPress a révélé que la traduction communautaire couvre moins de 5 % des besoins de traduction dans 40 langues.

Deux problèmes structurels expliquent cet écart :

Les bénévoles sont rares dans la plupart des locales. Une poignée de plugins avec des bases d'utilisateurs massives attirent les traducteurs. La majorité n'en attire pas.
Les traductions peuvent mettre des mois ou des années à apparaître, si elles apparaissent un jour. Si vous voulez que les utilisateurs voient votre plugin ou thème dans leur langue dès le premier jour, vous ne pouvez pas compter sur la communauté.

Ce guide part du principe que vous souhaitez une couverture de traduction complète et cohérente selon un calendrier de sortie que vous contrôlez. C'est ce que PTC fournit.

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

Un text domain incohérent ou une chaîne non encapsulée signifie que ce texte n'apparaîtra jamais dans votre résultat traduit. Les détails comptent.

Étape 1 : Définir votre text domain et votre chemin du domaine

Chaque thème ou plugin a besoin d'un text domain. Le text domain est un identifiant unique qui indique à WordPress quels fichiers de traduction appartiennent à votre projet. Il doit correspondre exactement au slug de votre plugin ou thème.

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

<?php
/**
 * Plugin Name: My Plugin
 * Description: An example plugin.
 * Version: 1.0.0
 * Text Domain: my-plugin
 * Domain Path: /languages
 */

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

/*
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 du plugin ou du thème. /languages est le standard.

Étape 2 : Encapsuler vos chaînes PHP dans des fonctions gettext

Toute chaîne que vous souhaitez rendre traduisible doit être encapsulée dans l'une des fonctions gettext de WordPress. À l'exécution, ces fonctions recherchent la traduction correcte. Si aucune n'est trouvée, elles se replient sur la chaîne d'origine.

Chaînes de base. Utilisez __() lorsque vous devez renvoyer une chaîne. Pour la sortie HTML, utilisez les variantes échappées. Les normes de codage de WordPress recommandent echo esc_html__() plutôt que _e(). La forme échappée rend l'échappement de la sortie explicite et empêche les failles XSS au point de sortie :

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

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

Chaînes avec variables. Ne concaténez pas de variables dans les chaînes. Les traducteurs ne voient que des fragments et ne peuvent pas réorganiser les mots pour les langues ayant une syntaxe différente. Utilisez printf() ou sprintf() avec un espace réservé. Ajoutez un commentaire pour que les traducteurs sachent ce que %s représente :

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

Formes plurielles. Les pluriels anglais sont simples (un commentaire, deux commentaires). Ce n'est pas le cas des autres langues. Utilisez _n() pour gérer toutes les règles de pluriel que WordPress connaît :

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 :

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

Étape 3 : Internationaliser vos chaînes JavaScript

WordPress fournit le paquet wp-i18n pour que vous puissiez utiliser en JavaScript les mêmes fonctions gettext que vous utilisez 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
);

Puis dans votre fichier JavaScript :

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

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

Si vous utilisez un bundler comme Webpack, installez @wordpress/babel-plugin-makepot. Il extrait les chaînes traduisibles de votre bundle lors de votre build.

Étape 4 : Générer votre fichier POT

Une fois vos chaînes encapsulées, générez un fichier POT. Le POT est le fichier source à partir duquel PTC (ou tout traducteur) travaille. Il contient chaque chaîne traduisible mais aucune traduction.

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

WP-CLI analyse vos fichiers PHP, JavaScript et block.json à la recherche d'appels gettext. Il les compile en un seul POT. Si votre équipe utilise Composer, ajoutez cette commande en tant que script Composer. Cela permet de garder une utilisation de WP-CLI cohérente au sein de l'équipe sans installation globale.

La suite complète de commandes wp i18n couvre le reste du pipeline :

Commande	Ce qu'elle fait
`wp i18n make-pot`	Générer un fichier POT à partir de la source.
`wp i18n update-po`	Synchroniser les fichiers PO existants lorsque votre POT est modifié.
`wp i18n make-mo`	Compiler les fichiers PO en fichiers MO binaires.
`wp i18n make-json`	Extraire les chaînes JS du PO vers des fichiers JSON.
`wp i18n make-php`	Générer les fichiers `.l10n.php` (WordPress 6.5+).

Vous n'avez pas besoin de Poedit. Tout dans ce flux de travail passe par WP-CLI et PTC. WP-CLI gère la génération du POT et la compilation MO/JSON. PTC s'occupe de la traduction et renvoie tous les formats de fichiers dont WordPress a besoin. Poedit est un éditeur de bureau utile pour la traduction manuelle, mais il ne fait pas partie de ce flux de travail.

Traduire des fichiers POT avec PTC

PTC est conçu pour les développeurs WordPress. Commencez avec un fichier POT et récupérez des fichiers de traduction prêts pour la production. L'essai de 30 jours couvre jusqu'à 20 000 mots dans deux langues.

Configurer votre premier projet de traduction

Téléversez votre fichier POT. Choisissez les formats de sortie dont vous avez besoin. PTC renvoie n'importe quelle combinaison de :

Fichiers .po pour chaque langue cible.
Fichiers .mo, compilés et prêts à être publiés.
Fichiers .json pour vos chaînes JavaScript.
Fichiers .l10n.php pour un chargement plus rapide sur WordPress 6.5+.

L'assistant de configuration vous demande de décrire votre thème ou plugin. PTC utilise la description pour générer des traductions avec le bon ton et le bon contexte. Ajoutez les termes spécifiques à la marque au glossaire à ce stade. Le glossaire maintient la cohérence des noms, des libellés de fonctionnalités et de toute autre terminologie dans toutes les langues.

PTC analyse la structure gettext lors du téléversement. Il reconnaît les espaces réservés (%s, %1$s, %d), les formes plurielles (les entrées extraites de _n() avec leur ligne d'en-tête Plural-Forms) et les contextes (les entrées _x() avec msgctxt). Il génère ensuite les catégories de pluriel correctes par langue. Le polonais obtient one / few / many / other. Le japonais n'obtient que other. L'arabe obtient six formes.

Passer à la localisation continue

Une fois vos premiers fichiers traduits, passez à Pay-As-You-Go. Connectez PTC à votre dépôt GitHub, GitLab ou Bitbucket. À partir de ce moment, vous ne téléversez plus de fichiers manuellement.

Faites un commit d'un fichier .ptc-config.yml indiquant votre fichier source et l'emplacement des traductions :

# .ptc-config.yml
source_locale: en
files:
  - file: languages/my-plugin.pot
    output: languages/my-plugin-{{lang}}.po
    additional_translation_files:
      - type: mo
        path: languages/my-plugin-{{lang}}.mo

Ajoutez ensuite l'action PTC Translate à votre flux de travail. Elle intègre une version épinglée de la CLI PTC, de sorte que votre compilation ne télécharge rien à l'exécution :

# .github/workflows/translate.yml
name: Regenerate POT for PTC
on:
  push:
    branches: [main]
    paths:
      - 'languages/my-plugin.pot'
  workflow_dispatch: {}

jobs:
  translate:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - name: Generate POT
        run: |
          wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin
      - uses: OnTheGoSystems/ptc-action@v1
        with:
          api-token: ${{ secrets.PTC_API_TOKEN }}
          create-pr: true

Vous avez deux façons d'automatiser cela. Avec l'intégration Git, PTC surveille votre dépôt et ouvre une merge request avec les traductions mises à jour chaque fois que le fichier source est modifié. Pour exécuter la traduction dans votre propre tâche CI, utilisez plutôt la CLI PTC : elle téléverse le fichier modifié, attend que la traduction se termine et télécharge les fichiers traduits. Des modèles de flux de travail prêts à l'emploi pour GitHub Actions, GitLab CI et Bitbucket Pipelines se trouvent dans le guide de configuration du pipeline CI/CD.

L'un ou l'autre flux fournit une merge request ou un téléchargement avec les fichiers .po, .mo, .json et .l10n.php mis à jour. Consultez la référence de l'API PTC pour l'API REST et les webhooks complets.

Le fait de commiter les fichiers .mo dans votre dépôt dépend des règles de votre équipe. De nombreux plugins les génèrent plutôt au moment de la publication. L'intégration CI de PTC les produit à chaque exécution de la traduction. Ne les ajoutez au contrôle de version que si vous souhaitez conserver les fichiers traduits dans l'historique des versions.

Chargement des traductions dans WordPress

Une fois les fichiers traduits en main, placez-les correctement et indiquez à WordPress où les trouver. Le nom du fichier vient en premier. WordPress recherche les fichiers de traduction en utilisant un modèle de nommage spécifique. Si le nom de fichier ne correspond pas, le fichier ne se chargera pas.

Nommer correctement vos fichiers

Les codes de locale suivent le format language_COUNTRY. de_DE correspond à l'allemand (Allemagne). fr_FR correspond au français (France). pt_BR correspond au portugais (Brésil). zh_CN correspond au chinois simplifié. Le portail de traduction de WordPress répertorie chaque locale prise en charge.

Le nom de fichier attendu dépend de l'endroit où vous placez le fichier :

Emplacement	Modèle	Exemple
Dossier `/languages/` du plugin	`{text-domain}-{locale}.mo`	`my-plugin-de_DE.mo`
Dossier `/languages/` du thème	`{locale}.mo`	`de_DE.mo`
Répertoire global des langues de WordPress (`/wp-content/languages/`)	`{text-domain}-{locale}.mo`	`my-plugin-de_DE.mo`

Les thèmes utilisent une convention de nommage plus courte lorsque les fichiers sont intégrés au thème. Dans le répertoire global des langues, les plugins comme les thèmes utilisent le modèle {text-domain}-{locale}.

Chargement des traductions pour les plugins (PHP)

Déclarez les traductions auprès de WordPress sur le hook init. N'utilisez pas plugins_loaded. Il déclenche un avertissement de dépréciation dans les versions actuelles de WordPress :

add_action( 'init', function () {
    load_plugin_textdomain(
        'my-plugin',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages/'
    );
} );

Chargement des traductions pour les thèmes (PHP)

Utilisez load_theme_textdomain() attaché à after_setup_theme :

add_action( 'after_setup_theme', function () {
    load_theme_textdomain( 'my-theme', get_template_directory() . '/languages' );
} );

Chargement des traductions JavaScript

Après avoir déclaré votre script (Étape 3 ci-dessus), appelez wp_set_script_translations(). WordPress charge alors les traductions JSON pour ce script handle :

add_action( 'init', function () {
    wp_set_script_translations(
        'my-plugin-script',
        'my-plugin',
        plugin_dir_path( __FILE__ ) . 'languages'
    );
} );

Vérifier le chargement

Définissez la langue de votre site WordPress sur une locale cible. Le réglage se trouve sous Réglages > Général > Langue du site.
Rechargez le front-end et les pages d'administration qu'affiche votre plugin ou votre thème.
Les chaînes encapsulées dans __() ou esc_html__() devraient apparaître dans la nouvelle langue.

S'il manque quelque chose, consultez Les traductions de plugins WordPress ne s'affichent pas ? Corriger les traductions manquantes pour connaître les causes les plus courantes.

Langues écrites de droite à gauche et mises en page bidirectionnelles

Le flux de travail de traduction est le même pour les langues écrites de droite à gauche (RTL). L'arabe, l'hébreu, le persan et l'ourdou utilisent le même pipeline POT/PO/MO.

L'étape supplémentaire consiste à s'assurer que votre thème prend en charge les styles RTL. WordPress charge automatiquement un fichier rtl.css s'il en existe un dans le répertoire de votre thème. Utilisez la fonction is_rtl() pour appliquer conditionnellement des styles ou des scripts spécifiques à RTL.

Localisation des dates, des nombres et des devises

Une chaîne traduite ne fait pas tout. Les dates, les nombres et les devises doivent également respecter la locale de l'utilisateur. Utilisez les fonctions de formatage intégrées de WordPress au lieu des fonctions natives de PHP :

date_i18n() formate les dates en fonction de la locale active.
number_format_i18n() formate les nombres avec des séparateurs de milliers et de décimales adaptés à la locale.

Ces fonctions ne font pas partie du flux de travail des fichiers de traduction. Elles sont importantes pour offrir une expérience entièrement localisée.

Internationalisation des blocs de l'Éditeur de blocs (Gutenberg)

Les blocs ajoutent deux étapes supplémentaires au pipeline standard :

Les traductions JavaScript nécessitent un fichier .json par locale. Générez-le à partir du .po avec wp i18n make-json.
Le script de l'éditeur du bloc nécessite wp_set_script_translations() en PHP. Cela indique à WordPress de servir le JSON au bloc.

La sortie rendue par le bloc sur le front-end utilise les mêmes appels __() que votre autre code PHP. Aucun travail supplémentaire n'est requis ici.

Traduire votre README et votre fiche WordPress.org

Votre readme.txt n'est pas un fichier de ressources. WP-CLI ne le détectera pas lors de la génération d'un POT. Pour le traduire, utilisez la fonctionnalité Paste to Translate de PTC. Collez le contenu, choisissez vos langues cibles et téléchargez le résultat. Les e-mails destinés aux clients envoyés depuis le plugin et la description de la page du plugin sur WordPress.org se traduisent de la même manière, tous dans le même projet afin que la terminologie reste cohérente.

Si votre plugin ou thème est répertorié sur WordPress.org, la description traduite apparaît dans l'onglet Détails du plugin dans la langue de l'utilisateur. Pour y mettre en ligne les traductions, suivez le processus d'importation de WordPress.org.

Traduire le contenu utilisateur du plugin avec l'API PTC

Les plugins qui stockent des données générées par les utilisateurs (plugins de forum, plugins d'avis, plugins de commentaires) peuvent traduire ce contenu au fur et à mesure de son arrivée. L'API REST PTC traduit les publications, commentaires et avis des utilisateurs à la demande avec une authentification par jeton Bearer, en utilisant le même glossaire et la même voix de marque que vos fichiers .po.

Révision visuelle de votre thème ou plugin rendu - déployez sans contrôle qualité manuel par langue

Un fichier .po traduit est nécessaire, mais il n'est pas suffisant. Le thème ou plugin traduit a toujours besoin d'être vérifié :

Un libellé traduit peut déborder d'un bouton de la page de paramètres en allemand.
« Submit » peut être traduit par un nom en français alors que l'action d'administration nécessitait un verbe.
Une chaîne en anglais codé en dur en dehors de __() sera rendue non traduite, quel que soit le nombre de langues que vous déployez.

La révision visuelle de la traduction de PTC remplace la passe de contrôle qualité manuel. Les thèmes et plugins WordPress sont rendus dans le navigateur (à la fois wp-admin et le front-end). La bonne variante est l'extension de navigateur.

Installez-la une seule fois. Enregistrez un parcours guidé de votre thème ou plugin sur un site de test. Couvrez les pages de paramètres, les actions d'administration et la sortie sur le front-end. PTC rejoue l'enregistrement dans chaque langue cible après chaque mise à jour de traduction. Il capture chaque écran et signale deux types de corrections :

Des corrections dans les fichiers .po lorsque PTC les contrôle. PTC retraduit un sens erroné, choisit un synonyme plus court qui tient dans un bouton ou régénère une forme plurielle.
Des prompts Cursor ou Claude Code lorsque le problème se trouve dans votre code PHP ou JavaScript. Les exemples incluent un wrapper __() manquant, une chaîne en anglais codée en dur ou une phrase construite par concaténation qui devrait utiliser sprintf( __( ... ) ).

Vous déployez un plugin multilingue et vérifié à chaque version. Le reliquat de contrôle qualité manuel disparaît.

Tarification : essai de 30 jours, puis Pay-As-You-Go

L'essai couvre 20 000 mots dans 2 langues sans carte bancaire. À la fin de l'essai, PTC propose le Pay-As-You-Go. Aucun abonnement. Aucun engagement minimum. Les 500 premiers mots de chaque mois sont gratuits. Vous ne payez que le reste. La page de tarification propose un calculateur de coûts. Inscrivez-vous avec une adresse e-mail professionnelle pour un essai entreprise prolongé.

Prêt à déployer un plugin ou thème vérifié ?

PTC génère les traductions et révise le plugin rendu. Vous confirmez le résultat et publiez. La boucle complète s'exécute sans contrôle qualité manuel :

Générez votre fichier .pot avec wp i18n make-pot.
Téléversez-le sur PTC et récupérez vos fichiers .po, .mo, .l10n.php et .json en quelques minutes.
Installez l'extension de navigateur pour vérifier le plugin en cours d'exécution dans chaque langue cible.

Commencez votre essai de 30 jours - 20 000 mots inclus, aucune carte bancaire requise.

Internationalisation WordPress : comment traduire les thèmes et les plugins

Qu'est-ce que l'internationalisation WordPress ?