Comment importer les traductions de thèmes et d’extensions sur WordPress.org

Deux voies permettent de mettre des fichiers .po et .mo traduits à la disposition des utilisateurs de WordPress.org. Demandez un accès CLPTE (1 à 2 semaines) ou incluez les fichiers .mo dans votre version (dès le lendemain). Les deux solutions fonctionnent. Le compromis se joue entre la distribution canonique et la rapidité. Ce guide explique quand utiliser chaque voie et détaille les étapes pour chacune d’elles.

Vous avez traduit votre extension ou votre thème avec PTC (Private Translation Cloud) et vous disposez des fichiers .po et .mo. Les utilisateurs qui installent votre extension depuis WordPress.org ne voient pas ces traductions par défaut. Les packs de langue de WordPress.org et vos fichiers inclus sont deux canaux de distribution distincts. Choisissez-en un en fonction de votre rythme de publication et de votre audience.

Voie 1 : Publier les traductions via les packs de langue de WordPress.org (CLPTE)

Temps total : 4 à 6 jours.

Étape 1 : Créer un compte CLPTE

Le rôle CLPTE (Cross-Locale Project Translation Editor) vous permet de soumettre des traductions au nom de votre thème ou extension pour toutes les langues cibles à partir d’un seul compte. Un compte d’éditeur de traduction classique (PTE) est limité à une langue ; le CLPTE ne l’est pas.

Si vous possédez déjà un compte sur WordPress.org, vous pourriez rencontrer un problème où votre nouveau compte CLPTE est désactivé. WordPress n’autorise pas les comptes multiples. Pour résoudre ce problème, envoyez un e-mail à forum-password-resets@wordpress.org et expliquez que vous essayez de créer un compte CLPTE. Le fait de partager la documentation Polyglots pertinente avec le modérateur et d’interpeller l’équipe Polyglots sur Slack peut aider.

Temps estimé : ~3 à 5 jours (incluant le temps d’attente si votre nouveau compte est désactivé).

Étape 2 : Demander l’accès CLPTE sur le blog Polyglots

Une fois votre compte activé, publiez une demande sur le blog WordPress.org Polyglots. Suivez leur modèle :

PTE/CLPTE Request

Plugin URL: https://wordpress.org/plugins/my-plugin/
Authors / Editors: @your-wp-username
Type of request: CLPTE

Vous recevrez une notification lorsque votre demande sera approuvée.

Temps estimé : ~1 jour (l’équipe globale Polyglots examine les demandes par lots).

Étape 3 : Importer les fichiers .po traduits

Connectez-vous à https://translate.wordpress.org/ avec votre compte CLPTE.
Accédez à la page du projet de traduction de votre extension ou thème (par exemple, translate.wordpress.org/projects/wp-plugins/{your-plugin-slug}/).
Ouvrez le projet local pour chaque langue que vous avez traduite.
Faites défiler vers le bas et cliquez sur Import Translations.
Téléversez votre fichier .po (ou .mo).
Marquez les chaînes importées comme « current » dans l’éditeur de traduction. Les chaînes approuvées rejoindront la prochaine génération de packs de langue (généralement quotidienne).
Répétez l’opération pour chaque langue cible. Chaque locale possède sa propre page de traduction.

Temps estimé : ~10 à 30 minutes par langue.

Après un délai de 24 à 48 heures pour la génération du pack de langue, les sites utilisant votre extension commenceront à recevoir les nouvelles traductions via les mises à jour automatiques des packs de langue de WordPress. Les traductions s’affichent tout simplement.

Ce que le CLPTE fera et ne fera pas pour vous

Vous ne pouvez pas remplacer les traductions communautaires existantes. Seules les chaînes non traduites sont importées. La mise à jour d’une traduction communautaire existante nécessite de suivre le processus standard et d’attendre la révision par l’équipe locale.
Les mises à jour nécessitent des téléversements manuels pour chaque version. Chaque nouvelle version implique une nouvelle série de téléversements.
La création et l’approbation du compte peuvent prendre jusqu’à une semaine.

Voie 2 : Inclure les fichiers .mo dans votre extension ou thème

Si vous avez besoin que les traductions soient en ligne plus rapidement que ne le permet le CLPTE, ou si vous préférez ne pas dépendre du pipeline de distribution de WordPress.org, incluez les fichiers .mo directement dans la version de votre extension ou thème. Temps total : 15 à 30 minutes.

Étape 1 : Ajouter les fichiers .mo au répertoire /languages/

Placez vos fichiers .mo compilés dans le répertoire /languages/ de votre extension ou thème afin que WordPress les trouve lors du chargement de votre domaine de texte :

my-plugin/
├─ my-plugin.php
├─ readme.txt
├─ languages/
│  ├─ my-plugin-es_ES.mo
│  ├─ my-plugin-es_ES.po
│  ├─ my-plugin-fr_FR.mo
│  ├─ my-plugin-fr_FR.po
│  ├─ my-plugin-de_DE.mo
│  └─ my-plugin-de_DE.po

Utilisez le même domaine de texte dans les noms de vos fichiers de traduction et dans vos appels à load_plugin_textdomain() ou load_theme_textdomain().

Étape 2 : Privilégier vos fichiers inclus par rapport aux traductions communautaires

Par défaut, WordPress donne la priorité aux traductions communautaires de WordPress.org par rapport aux fichiers inclus. Pour vous assurer que votre extension ou thème utilise plutôt les fichiers .mo inclus, ajoutez le filtre load_textdomain_mofile.

Pour les extensions, ajoutez ceci à votre fichier principal (ex. : my-plugin.php) :

function my_plugin_load_embedded_translation_file( $mofile, $domain ) {
    if ( 'my-domain' === $domain && false !== strpos( $mofile, WP_LANG_DIR . '/plugins/' ) ) {
        $locale = apply_filters( 'plugin_locale', determine_locale(), $domain );
        $local_mofile = WP_PLUGIN_DIR . '/' . dirname( plugin_basename( __FILE__ ) ) .
                        '/languages/' . $domain . '-' . $locale . '.mo';

        if ( file_exists( $local_mofile ) ) {
            return $local_mofile;
        }
    }
    return $mofile;
}
add_filter( 'load_textdomain_mofile', 'my_plugin_load_embedded_translation_file', 10, 2 );

Pour les thèmes, ajoutez ceci au fichier functions.php de votre thème :

function my_theme_load_embedded_translation_file( $mofile, $domain ) {
    if ( 'my-domain' === $domain && false !== strpos( $mofile, WP_LANG_DIR . '/themes/' ) ) {
        $locale = apply_filters( 'theme_locale', determine_locale(), $domain );
        $local_mofile = get_template_directory() . '/languages/' . $locale . '.mo';

        if ( file_exists( $local_mofile ) ) {
            return $local_mofile;
        }
    }
    return $mofile;
}
add_filter( 'load_textdomain_mofile', 'my_theme_load_embedded_translation_file', 10, 2 );

Vérifiez également que votre extension ou thème charge le domaine de texte sur le bon hook :

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

Étape 3 : Vérifier le chargement des traductions incluses sur un site de test

Installez votre extension ou thème sur un site de test et basculez WordPress dans l’une des langues que vous avez fournies :

Allez dans Réglages > Général > Langue du site et sélectionnez une langue dont le fichier .mo se trouve dans votre dossier /languages/.
Chargez une page ou un écran contenant des chaînes que vous savez traduites.
Confirmez que les chaînes apparaissent dans la bonne langue et correspondent aux traductions que vous avez ajoutées.

Si vous voyez toujours d’anciennes traductions communautaires, revoyez l’extrait de code de l’étape 2. Il doit diriger correctement WordPress vers vos fichiers .mo inclus.

Commitez les fichiers .mo, créez un tag de version et poussez sur WordPress.org via SVN comme vous le faites habituellement.

Le compromis entre rapidité et distribution canonique

Avantage : instantané. Les nouvelles traductions sont en ligne dès que les utilisateurs mettent à jour votre extension (ou l’installent pour la première fois). Pas d’attente de 1 à 2 semaines pour le CLPTE. Pas de cycle d’approbation par l’équipe Polyglots.
Avantage : vous contrôlez le flux de travail. Le rythme de traduction correspond exactement à votre rythme de publication.
Avantage : pas de dépendance au badge de l’extension. Les traductions fonctionnent, que votre extension dispose ou non des permissions CLPTE.
Inconvénient : la taille du fichier de l’extension augmente. Chaque fichier .mo est petit (généralement 5 à 50 ko), mais 20 langues ajoutent environ 500 ko au téléchargement.
Inconvénient : pas de mise à jour automatique des traductions entre les versions de l’extension. Avec le CLPTE, les traductions mises à jour sur WordPress.org se propagent aux utilisateurs sous 48 heures, même si vous ne publiez pas de nouvelle version. Avec l’inclusion directe, les traductions ne sont mises à jour que lorsque vous publiez une nouvelle version.
Inconvénient : pas de badge « traduit ». WordPress.org affiche un badge de complétion de traduction sur les fiches d’extensions en fonction de la couverture des packs de langue, et non des fichiers .mo inclus. L’inclusion seule ne permet pas d’obtenir le badge.

Quelle voie correspond à votre rythme de publication

Situation	Recommandation
Distribution canonique à long terme ; vous voulez le badge de traduction	CLPTE - passez par la demande Polyglots
Vous publiez des mises à jour d’extension mensuellement ou plus souvent, et le rythme de traduction peut suivre	Inclure les fichiers MO
Vous avez besoin que les traductions soient en ligne cette semaine et ne pouvez pas attendre le CLPTE	Incluez les fichiers MO maintenant, demandez le CLPTE en parallèle
Vous voulez les deux	Utilisez les deux - ils ne sont pas mutuellement exclusifs

L’approche double est courante : inclure les fichiers MO pour une disponibilité immédiate, et soumettre au CLPTE pour la distribution canonique. Les utilisateurs bénéficient des traductions incluses lors de la mise à jour ; la surcouche du pack de langue les actualise entre les versions.

Traduisez votre prochaine version d’extension avec PTC

Commencez votre essai gratuit de 30 jours - 20.000 mots offerts, sans carte bancaire. Générez votre fichier .pot, téléversez-le sur PTC, obtenez des fichiers .po et .mo traduits en quelques minutes, prêts pour le CLPTE ou l’inclusion directe.

Voir aussi :

Internationalisation de WordPress : comment traduire des thèmes et des extensions - le tutoriel parent couvrant la génération de fichiers POT, les domaines de texte et le chargement des traductions.
Les traductions de l’extension WordPress ne s’affichent pas ? Corriger les traductions manquantes - guide de dépannage pour les problèmes de chargement les plus courants.
GlotPress vs PTC pour la traduction d’extensions/thèmes WordPress - quand choisir la traduction communautaire ou PTC.
Manuel de demande PTE/CLPTE sur WordPress.org Polyglots - le processus officiel de demande CLPTE.