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

Rendez votre thème ou extension WordPress prêt pour la traduction. Ce guide couvre les domaines de texte, les fonctions gettext, la génération de fichiers POT et le mécanisme de chargement qui affiche les traductions aux utilisateurs. PTC (Private Translation Cloud) traduit ensuite les fichiers de ressources et effectue une relecture visuelle du thème ou de l'extension rendu dans chaque langue.

Ce guide est destiné aux développeurs qui écrivent le code. Si vous avez déjà un fichier POT ou PO et que vous avez simplement besoin de le traduire, rendez-vous sur la page des fichiers PO pour découvrir le flux de travail en 3 étapes.

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

Correctement internationalisé selon les normes de codage de WordPress.
Traduisible par PTC dans plus de 40 langues.
Distribuable via les packs de langue de WordPress.org.
Vérifiable à chaque version grâce à la relecture visuelle des traductions de PTC.

Qu’est-ce que l’internationalisation de 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 extensions WordPress, l’i18n signifie trois choses :

Encapsuler chaque chaîne destinée à l’utilisateur dans des fonctions gettext afin que WordPress puisse les remplacer au moment de l’exécution.
Définir un domaine de texte 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 disposez de 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 fichiers apparaissent dans tout flux de travail de traduction WordPress. PTC traduit à partir du .pot (votre source) vers les formats .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 répertorie chaque chaîne traduisible sans aucune traduction attachée. Vous transmettez ce fichier à PTC.
PO (Portable Object). Une copie du POT avec les traductions ajoutées pour une langue spécifique. Texte brut, lisible par l’homme. PTC renvoie un PO par langue cible.
MO (Machine Object). La version binaire compilée d’un PO. WordPress lit les fichiers MO au moment de 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 de MO à partir de JavaScript, le pipeline de construction 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 existe aux côtés du fichier MO.

Activez .l10n.php pour les nouveaux projets. Il est strictement meilleur que le 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, elle ne couvre qu’une petite fraction de ce dont la plupart des extensions et thèmes ont besoin. Une analyse de plus de 60.000 extensions 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. Seule une poignée d’extensions disposant d’une base d’utilisateurs massive attirent les traducteurs. La plupart n’en ont pas.
Les traductions peuvent mettre des mois ou des années à apparaître, si elles apparaissent. Si vous voulez que les utilisateurs voient votre extension ou thème dans leur langue dès le premier jour, vous ne pouvez pas compter sur la communauté.

Ce guide suppose 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 propose PTC.

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

Un domaine de texte mal assorti 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éfinissez votre domaine de texte et le chemin du domaine

Chaque thème ou extension a besoin d’un domaine de texte. Le domaine de texte est un identifiant unique qui indique à WordPress quels fichiers de traduction appartiennent à votre projet. 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 :

<?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 de l’extension ou du thème. /languages est la norme.

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

Toute chaîne que vous souhaitez traduire doit être encapsulée dans l’une des fonctions gettext de WordPress. Au moment de l’exécution, ces fonctions recherchent la traduction correcte. Si aucune traduction n’est trouvée, elles reviennent à la chaîne d’origine.

Chaînes de base. Utilisez __() lorsque vous devez renvoyer une chaîne. Pour une 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éordonner les mots pour les langues ayant une syntaxe différente. Utilisez printf() ou sprintf() avec un espace réservé. Ajoutez un commentaire de traducteur 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 d’autres langues. Utilisez _n() pour gérer toutes les règles de pluriel connues de WordPress :

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 : Internationalisez vos chaînes JavaScript

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
);

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 dans le cadre de votre construction.

Étape 4 : Générez 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 dans un seul fichier POT. Si votre équipe utilise Composer, ajoutez cette commande en tant que script Composer. Cela permet de maintenir une utilisation cohérente de WP-CLI 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ère un fichier POT à partir de la source.
`wp i18n update-po`	Synchronise les fichiers PO existants lorsque votre POT change.
`wp i18n make-mo`	Compile les fichiers PO en fichiers MO binaires.
`wp i18n make-json`	Extrait les chaînes JS des fichiers PO vers des fichiers JSON.
`wp i18n make-php`	Génère des 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 gère la traduction et renvoie chaque format de fichier 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 recevez en retour des fichiers de traduction prêts pour la production. L’essai gratuit de 30 jours couvre jusqu’à 20.000 mots dans deux langues.

Configurez votre premier projet de traduction

Téléchargez 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 déployé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 extension. PTC utilise cette description pour générer des traductions avec le ton et le contexte appropriés. Ajoutez les termes spécifiques à votre marque au glossaire à cette étape. Le glossaire permet de garder les noms, les libellés de fonctionnalités et toute autre terminologie cohérents dans toutes les langues.

PTC analyse la structure gettext lors du téléchargement. Il reconnaît les espaces réservés (%s, %1$s, %d), les formes plurielles (entrées extraites par _n() avec leur en-tête Plural-Forms) et les contextes (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.

Passez à la localisation continue

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

# .github/workflows/translate.yml
name: Regenerate POT for PTC
on:
  push:
    branches: [main]
    paths:
      - 'languages/my-plugin.pot'
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate POT
        run: |
          wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin
      - name: Trigger PTC translation
        run: |
          curl -X POST https://api.ptc.wpml.org/v1/projects/${{ secrets.PTC_PROJECT_ID }}/sync \
            -H "Authorization: Bearer ${{ secrets.PTC_API_KEY }}"

Vous avez deux façons d’automatiser cela. Avec l’intégration Git, PTC surveille votre dépôt et ouvre une pull request avec les traductions mises à jour chaque fois que le fichier source change. Pour exécuter la traduction à l’intérieur de votre propre tâche CI, utilisez le CLI de PTC — il télécharge 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 pull 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 connaître l’intégralité du webhook et de l’API REST.

Le fait de commiter les fichiers .mo dans votre dépôt dépend de la politique de votre équipe. De nombreuses extensions les génèrent plutôt au moment de la sortie. L’intégration CI de PTC les produit à chaque exécution de traduction. Ne les validez que si vous souhaitez avoir 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. Un nom de fichier qui ne correspond pas signifie que le fichier ne sera pas chargé.

Bien nommer vos fichiers

Les codes de locale suivent le format langue_PAYS. de_DE est l’allemand (Allemagne). fr_FR est le français (France). pt_BR est le portugais (Brésil). zh_CN est le chinois simplifié. Le portail de traduction de WordPress répertorie toutes les locales prises en charge.

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

Emplacement	Modèle	Exemple
Dossier `/languages/` de l’extension	`{text-domain}-{locale}.mo`	`my-plugin-de_DE.mo`
Dossier `/languages/` du thème	`{locale}.mo`	`de_DE.mo`
Répertoire de langues global 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 inclus dans le thème. Dans le répertoire de langues global, les extensions et les thèmes utilisent tous deux le modèle {text-domain}-{locale}.

Chargement des traductions pour les extensions (PHP)

Enregistrez les traductions auprès de WordPress sur le hook init. N’utilisez pas plugins_loaded. Cela déclenche un avertissement d’obsolescence 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() accroché à 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 enregistré votre script (étape 3 ci-dessus), appelez wp_set_script_translations(). WordPress charge alors les traductions JSON pour ce handle de script :

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

Vérifiez le chargement

Définissez la langue de votre site WordPress sur une locale cible. Le réglage se trouve dans Réglages > Général > Langue du site.
Rechargez le front-end et les pages d’administration que votre extension ou thème affiche.
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 l’extension WordPress ne s’affichent pas ? Corriger les traductions manquantes pour connaître les causes les plus courantes.

Langues de droite à gauche et mises en page bidirectionnelles

Le flux de travail de traduction est le même pour les langues s’écrivant 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 au 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 suivre 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 selon la locale active.
number_format_i18n() formate les nombres avec des séparateurs de décimales et de milliers adaptés à la locale.

Ces fonctions ne font pas partie du flux de travail des fichiers de traduction. Elles sont essentielles pour 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.

Le rendu du bloc sur le front-end utilise les mêmes appels __() que votre autre code PHP. Aucun travail supplémentaire n’est nécessaire ici.

Traduire votre README et votre fiche WordPress.org

Votre fichier readme.txt n’est pas un fichier de ressources. WP-CLI ne le prendra pas en compte lors de la génération d’un POT. Pour le traduire, utilisez la fonctionnalité Coller pour traduire 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 par l’extension et la description de la page de l’extension sur WordPress.org se traduisent de la même manière, le tout dans le même projet afin que la terminologie reste cohérente.

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

Traduire le contenu utilisateur de l’extension avec l’API PTC

Les extensions qui stockent des données générées par les utilisateurs (extensions de forum, de relecture, de commentaires) peuvent traduire ce contenu au fur et à mesure qu’il arrive. L’API REST de 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.

Relecture visuelle de votre thème ou extension 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 l’extension traduit doit encore être vérifié :

Un libellé traduit peut déborder d’un bouton de page de réglages en allemand.
« Submit » peut être traduit par un nom en français alors que l’action d’administration nécessite un verbe.
Une chaîne en anglais codée en dur en dehors de __() s’affichera non traduite, quel que soit le nombre de langues que vous proposez.

La relecture visuelle des traductions de PTC remplace l’étape de contrôle qualité manuel. Les thèmes et extensions WordPress s’affichent dans le navigateur (à la fois dans wp-admin et sur le front-end). La version appropriée est l’extension de navigateur.

Installez-la une fois. Enregistrez un parcours guidé de votre thème ou extension sur un site de test. Couvrez les pages de réglages, les actions d’administration et le rendu 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 :

Corrections dans les fichiers .po lorsque PTC les contrôle. PTC corrige une traduction erronée, choisit un synonyme plus court qui tient dans un bouton ou régénère une forme plurielle.
Prompts Cursor ou Claude Code lorsque le problème réside dans votre code PHP ou JavaScript. Les exemples incluent une encapsulation __() manquante, une chaîne en anglais codée en dur ou une phrase construite par concaténation qui devrait utiliser sprintf( __( ... ) ).

Vous déployez une extension multilingue vérifiée à chaque version. La phase de contrôle qualité manuel disparaît.

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

L’essai gratuit couvre 20.000 mots dans 2 langues sans carte bancaire. À la fin de l’essai, PTC propose le Pay-As-You-Go. Pas d’abonnement. Pas d’engagement minimum. Les 500 premiers mots de chaque mois sont gratuits. Vous ne payez que pour le reste. La page de tarification dispose d’un calculateur de coût. Inscrivez-vous avec une adresse e-mail professionnelle pour bénéficier d’un essai professionnel prolongé.

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

PTC génère les traductions et relit l’extension rendue. 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échargez-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 l’extension en cours d’exécution dans chaque langue cible.

Commencez votre essai gratuit de 30 jours — 20.000 mots offerts, aucune carte bancaire requise.