Comment importer les traductions de thèmes et de plugins dans WordPress.org

Deux voies permettent de mettre les fichiers .po et .mo traduits à la disposition des utilisateurs de WordPress.org. Demandez l'accès CLPTE (4 à 6 jours) ou incluez les fichiers .mo dans votre version (disponible le lendemain). Les deux fonctionnent. Le compromis se situe entre la distribution canonique et la rapidité. Ce guide explique quand utiliser chaque voie et détaille les étapes pour les deux.

Vous avez traduit votre plugin ou thème avec PTC (Private Translation Cloud) et vous disposez des fichiers .po et .mo. Les utilisateurs qui installent votre plugin 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 cadence de publication et de votre public.

Voie 1 : Publier les traductions via les packs de langue 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 plugin dans toutes les langues cibles à partir d'un seul compte. Un compte Éditeur de traduction classique est spécifique à 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. Partager la documentation Polyglots pertinente avec le modérateur et mentionner l'équipe Polyglots sur Slack sont deux actions utiles.

Temps estimé : ~3 à 5 jours (inclut 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 Polyglots de WordPress.org. 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 recevez une notification lorsque votre demande est approuvée.

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

Étape 3 : Importer les fichiers .po traduits

Connectez-vous à https://translate.wordpress.org/ en utilisant votre compte CLPTE.
Allez sur la page du projet de traduction de votre plugin 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 Importer les traductions.
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 rejoignent 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 les packs de langue, les sites utilisant votre plugin commencent à recevoir les nouvelles traductions via les mises à jour automatiques des packs de langue de WordPress. Les utilisateurs ne voient aucune invite de mise à jour. Les traductions apparaissent 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 le processus standard et d'attendre la révision de l'équipe de la 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 prennent généralement 4 à 6 jours au total.

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

Si vous avez besoin que les traductions passent en production 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 plugin 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 plugin ou thème afin que WordPress les trouve lors du chargement de votre text domain :

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 text domain 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 sur les fichiers inclus. Pour vous assurer que votre plugin ou thème utilise plutôt les fichiers .mo inclus, ajoutez le filtre load_textdomain_mofile.

Pour les plugins, ajoutez ceci à votre fichier de plugin principal (par exemple, 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 );

Confirmez également que votre plugin ou thème charge le text domain sur le bon hook :

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

Étape 3 : Vérifier que les traductions incluses se chargent sur un site de test

Installez votre plugin ou thème sur un site de test et passez 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 qui contient 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 correctement pointer WordPress vers vos fichiers .mo inclus.

Faites un commit des fichiers .mo, taguez une version et poussez vers wordpress.org via SVN comme vous le faites normalement.

Le compromis entre rapidité et distribution canonique

Avantage : instantané. Les nouvelles traductions sont en ligne dès que les utilisateurs mettent à jour votre plugin (ou l'installent pour la première fois). Pas d'attente de plusieurs jours pour le CLPTE. Pas de cycle d'approbation par l'équipe Polyglots.
Avantage : vous contrôlez le flux de travail. La cadence de traduction correspond exactement à votre cadence de publication.
Avantage : aucune dépendance au badge du plugin. Les traductions fonctionnent, que votre plugin ait ou non les autorisations CLPTE.
Inconvénient : la taille du fichier du plugin augmente. Chaque .mo est petit (5 à 50 Ko généralement), mais 20 langues ajoutent environ 500 Ko au téléchargement.
Inconvénient : pas de mise à jour automatique des traductions entre les versions du plugin. Avec le CLPTE, les traductions mises à jour sur wordpress.org se propagent aux utilisateurs dans les 48 heures, même si vous ne publiez pas de nouvelle version. Avec l'inclusion des fichiers, les traductions ne sont mises à jour que lorsque vous publiez une nouvelle version.
Inconvénient : pas de badge « traduit ». WordPress.org affiche un badge d'achèvement de traduction sur les fiches des plugins 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 cadence de publication ?

Situation	Recommandation
Distribution canonique à long terme ; vous souhaitez le badge de traduction	CLPTE - passez par la candidature Polyglots
Vous publiez des mises à jour du plugin tous les mois ou plus souvent, et la cadence de traduction peut correspondre	Inclure les fichiers MO
Vous avez besoin que les traductions soient en production cette semaine et ne pouvez pas attendre le CLPTE	Inclure les fichiers MO maintenant, faire une demande CLPTE en parallèle
Vous voulez les deux	Utiliser les deux - ils ne sont pas mutuellement exclusifs

L'approche double est courante : incluez les fichiers MO pour une disponibilité immédiate, et soumettez-les au CLPTE pour une distribution canonique. Les utilisateurs obtiennent les traductions incluses lors de la mise à jour ; la surcouche des packs de langue les actualise entre les versions.

Traduisez la prochaine version de votre plugin avec PTC

Commencez votre essai de 30 jours - 20 000 mots inclus, sans carte bancaire. Générez votre fichier .pot, téléversez-le sur PTC, obtenez les fichiers .po et .mo traduits en quelques minutes, prêts pour le CLPTE ou l'inclusion.