Documentation · Guide d'intégration

Guide de traduction et Poedit

Ce document explique comment l'extension ADP Car Market Hub gère les sites WordPress multilingues, quels fichiers de traduction sont fournis avec l'extension, et comment traduire ou mettre à jour les chaînes de l'extension à l'aide de Poedit ou d'outils équivalents.

Quand utiliser ce document

Utilisez ce document si vous :

Configurez l'extension sur un site dont la langue WordPress n'est pas l'anglais et souhaitez confirmer que les traductions sont chargées.
Êtes un concessionnaire ou une agence ajoutant ou corrigeant des traductions pour une langue déjà incluse dans l'extension.
Êtes un développeur contribuant à un nouveau fichier de langue pour une locale qui n'est pas encore intégrée à l'extension.
Dépannez du texte de l'extension qui apparaît en anglais alors que la langue du site est définie sur une autre locale.

Le public cible est un administrateur WordPress ou un développeur à l'aise avec le flux de travail d'internationalisation de WordPress et l'utilisation basique de la ligne de commande.

Aperçu

L'extension utilise le mécanisme de localisation standard de WordPress. Toutes les chaînes visibles par l'utilisateur dans le code PHP de l'extension sont enveloppées dans des fonctions de traduction WordPress (__(), _e(), esc_html__(), et similaires) avec le domaine de texte adp-car-market-hub. WordPress charge le fichier de traduction correspondant depuis le dossier languages/ de l'extension lorsque la langue du site est définie dans Réglages → Général → Langue du site.

Les fichiers de langue suivants sont intégrés à l'extension au moment de la rédaction de ce document :

Code de locale	Langue
`de_AT`	Allemand (Autriche)
`de_CH`	Allemand (Suisse)
`de_DE`	Allemand (Allemagne)
`de_DE_formal`	Allemand (Allemagne, vouvoiement)
`fr_FR`	Français (France)
`it_IT`	Italien (Italie)
`es_ES`	Espagnol (Espagne)
`nl_NL`	Néerlandais (Pays-Bas)

Vérifiez la liste actuelle en consultant le répertoire languages/ à l'intérieur du dossier de l'extension (wp-content/plugins/adp-car-market-hub/languages/). Chaque locale possède un fichier source .po (modifiable par l'homme) et, lorsqu'un fichier compilé .mo est présent, c'est ce fichier que WordPress charge réellement au moment de l'exécution.

Si le site utilise une locale qui n'est pas dans la liste ci-dessus, l'extension affiche toutes les chaînes dans la langue de secours, qui est l'anglais.

Prérequis

Accès administrateur WordPress.
Pour modifier les traductions : Poedit (https://poedit.net/) ou un éditeur de fichiers .po / .mo équivalent, ou l'extension WordPress Loco Translate (https://wordpress.org/plugins/loco-translate/).
Pour générer un nouveau fichier POT : WP-CLI version 2.6 ou supérieure, ou le script make-pot.sh dans bin/make-pot.sh.
Pour compiler des fichiers .mo depuis la ligne de commande : l'utilitaire GNU gettext msgfmt, ou la commande wp i18n make-mo de WP-CLI.

Comment l'extension charge les traductions

L'extension appelle load_plugin_textdomain() sur l'action plugins_loaded à la priorité 1. Cela signifie que le fichier de traduction pour la langue actuelle du site est chargé avant que tout autre code de l'extension ne s'exécute à la priorité par défaut, de sorte que toutes les chaînes de l'administration et du frontend sont disponibles pour la traduction dès l'initialisation de l'extension.

WordPress résout le fichier de langue dans l'ordre suivant :

wp-content/languages/plugins/adp-car-market-hub-{locale}.mo (fichiers de traduction installés par WordPress lui-même ou par un outil de gestion des traductions).
wp-content/plugins/adp-car-market-hub/languages/adp-car-market-hub-{locale}.mo (fichiers intégrés à l'extension).

Les fichiers dans wp-content/languages/plugins/ sont prioritaires. Si vous mettez à jour une traduction intégrée à l'aide d'une extension telle que Loco Translate, le fichier mis à jour est généralement stocké dans le premier chemin, ce qui protège vos modifications contre l'écrasement lors des mises à jour de l'extension.

Instructions étape par étape

Utiliser une traduction intégrée existante

Dans WordPress, ouvrez Réglages → Général.
Définissez la Langue du site sur la locale souhaitée (par exemple Allemand (Suisse) pour de_CH).
Enregistrez les modifications.
Naviguez vers n'importe quelle page d'administration de l'extension ou visitez l'archive des véhicules sur le frontend. Les chaînes de l'extension (libellés, boutons, messages d'erreur) doivent apparaître dans la langue sélectionnée.
Si les chaînes apparaissent toujours en anglais, consultez la section Dépannage ci-dessous.

Modifier ou corriger une traduction existante avec Poedit

Téléchargez et installez Poedit depuis https://poedit.net/.
Localisez le fichier .po pour la locale que vous souhaitez modifier, à l'intérieur du répertoire languages/ de l'extension. Par exemple : wp-content/plugins/adp-car-market-hub/languages/adp-car-market-hub-de_CH.po.
Ouvrez le fichier .po dans Poedit.
Recherchez la chaîne que vous souhaitez modifier dans la liste des chaînes. La colonne Texte source affiche l'original en anglais et la colonne Traduction affiche la valeur traduite actuelle. Cliquez sur une ligne pour modifier la traduction dans le panneau d'édition ci-dessous.
Enregistrez le fichier. Poedit compile automatiquement le fichier .mo correspondant dans le même répertoire.
Recommandé : Copiez les fichiers .po et .mo mis à jour vers wp-content/languages/plugins/ afin que les mises à jour de l'extension ne les écrasent pas : - wp-content/languages/plugins/adp-car-market-hub-de_CH.po - wp-content/languages/plugins/adp-car-market-hub-de_CH.mo
Videz tout cache WordPress susceptible de servir du contenu obsolète, puis vérifiez la modification sur la page de l'extension concernée.

Modifier une traduction existante avec Loco Translate

Installez et activez l'extension Loco Translate depuis le répertoire des extensions WordPress.
Dans WordPress, naviguez vers Loco Translate → Extensions.
Trouvez ADP Car Market Hub dans la liste et cliquez dessus.
Sélectionnez la langue que vous souhaitez modifier.
Modifiez les chaînes dans l'éditeur Loco Translate et enregistrez. Loco Translate compile automatiquement le fichier .mo et stocke vos modifications dans wp-content/languages/plugins/, les protégeant ainsi des mises à jour de l'extension.

Créer une traduction pour une nouvelle langue

Ouvrez le fichier modèle POT : wp-content/plugins/adp-car-market-hub/languages/adp-car-market-hub.pot. Le fichier POT contient toutes les chaînes traduisibles de l'extension sans aucune traduction.
Dans Poedit, choisissez Fichier → Nouveau à partir d'un fichier POT/PO, sélectionnez le fichier .pot, puis choisissez la langue cible.
Traduisez les chaînes.
Enregistrez sous le nom adp-car-market-hub-{locale}.po et compilez en adp-car-market-hub-{locale}.mo. Utilisez le code de locale exact que WordPress utilise pour cette langue (par exemple fr_CH pour le français de Suisse). Vérifiez le code dans Réglages → Général → Langue du site.
Placez les deux fichiers dans wp-content/languages/plugins/ afin qu'ils ne soient pas écrasés par les mises à jour de l'extension.
Définissez la langue du site et vérifiez que la nouvelle traduction se charge correctement.

Mettre à jour les fichiers de traduction après une mise à jour de l'extension

Lorsque l'extension est mise à jour, de nouvelles chaînes peuvent être ajoutées. Les fichiers .po intégrés sont mis à jour par les responsables de l'extension, mais les traductions personnalisées stockées en dehors du répertoire de l'extension ne sont pas automatiquement actualisées.

Pour mettre à jour votre fichier de traduction personnalisé :

Téléchargez le fichier POT mis à jour depuis le répertoire languages/ de l'extension.
Dans Poedit, ouvrez votre fichier .po personnalisé, puis choisissez Traduction → Mettre à jour depuis un fichier POT et sélectionnez le nouveau fichier .pot. Poedit fusionne les nouvelles chaînes dans votre fichier, en signalant les chaînes non traduites qui nécessitent votre attention.
Traduisez les nouvelles chaînes.
Enregistrez et compilez.

Si vous utilisez WP-CLI, mettez à jour un fichier .po avec msgmerge :

msgmerge --update languages/adp-car-market-hub-de_CH.po languages/adp-car-market-hub.pot

Compilez le fichier mis à jour :

msgfmt -o languages/adp-car-market-hub-de_CH.mo languages/adp-car-market-hub-de_CH.po

Ou compilez tous les fichiers .po en une seule fois avec WP-CLI :

wp i18n make-mo languages/

Référence de configuration

Il n'y a pas de page de réglages de traduction dédiée dans l'administration de l'extension. La traduction est entièrement gérée via le réglage de langue du site de WordPress et le système de localisation standard de WordPress.

Ce qu'il faut configurer	Où
Langue du site qui détermine quel fichier de traduction est chargé	Réglages → Général → Langue du site
Modifier les traductions intégrées sans perdre les modifications lors des mises à jour	Utilisez Loco Translate, qui stocke les modifications dans `wp-content/languages/plugins/`
Générer un fichier POT mis à jour à partir des sources PHP de l'extension	Exécutez `./bin/make-pot.sh` ou `wp i18n make-pot` (voir le fichier README i18n)

Notes opérationnelles

Domaine de texte. Chaque chaîne traduisible dans l'extension utilise le domaine de texte adp-car-market-hub. Ce domaine de texte est déclaré dans l'en-tête de l'extension et doit correspondre au préfixe du nom de fichier des fichiers de traduction (par exemple adp-car-market-hub-de_DE.mo). Une non-correspondance entre le domaine de texte et le nom de fichier est la raison la plus courante pour laquelle les chaînes ne se traduisent pas.
Les fichiers .mo compilés sont requis au moment de l'exécution. WordPress lit les fichiers .mo compilés, et non les fichiers sources .po lisibles par l'homme. Compilez toujours un fichier .po nouveau ou mis à jour en .mo avant d'espérer voir les modifications dans le navigateur.
Allemand formel vs informel. La locale de_DE_formal fournit un style de vouvoiement (Sie) pour l'allemand. Choisissez cette locale sur les sites où une formulation formelle est attendue.
Les chaînes du frontend et de l'administration sont toutes deux couvertes. Le domaine de texte de l'extension comprend des chaînes pour les pages d'administration (réglages, état de l'importation, journaux) et pour l'affichage du frontend (libellés des véhicules, libellés des filtres, messages du formulaire de contact, calculateur de financement). Les deux ensembles de chaînes se trouvent dans le même fichier .po / .mo.
Packs de langue WordPress. Si le système de packs de langue de WordPress dispose d'une traduction communautaire pour adp-car-market-hub pour la locale sélectionnée, WordPress peut proposer de la télécharger automatiquement. Les fichiers obtenus de cette manière sont stockés dans wp-content/languages/plugins/ et sont mis à jour en même temps que le cœur de WordPress. Vérifiez que la traduction communautaire est complète avant de vous y fier pour la production.
Mise en cache. Si les traductions n'apparaissent pas après une modification, videz tout cache d'objet WordPress, cache de page ou cache d'opcode. Le bytecode mis en cache des anciens fichiers .mo peut persister jusqu'à ce que le cache soit vidé.
Fichiers de documentation. La documentation dans docs/ est rédigée en anglais uniquement. Il n'existe pas de fichiers de documentation traduits. La traduction des chaînes PHP de l'extension (telle que décrite dans ce guide) et la traduction de la documentation sont des sujets distincts.

Dépannage

Symptôme	Cause probable	Ce qu'il faut vérifier
Les chaînes de l'extension apparaissent en anglais alors que la langue du site est correctement définie.	Le fichier `.mo` pour la locale sélectionnée est manquant ou non compilé.	Vérifiez que les fichiers `.po` et `.mo` existent dans `wp-content/plugins/adp-car-market-hub/languages/` ou `wp-content/languages/plugins/`. Le fichier `.mo` doit être présent.
Poedit enregistre le fichier `.po` mais les chaînes ne changent pas dans WordPress.	Poedit a compilé le `.mo` à côté du `.po`, mais WordPress charge un `.mo` depuis un chemin différent.	Vérifiez à la fois le répertoire `languages/` de l'extension et `wp-content/languages/plugins/`. Le fichier dans `wp-content/languages/plugins/` est prioritaire.
Certaines chaînes se traduisent mais d'autres restent en anglais.	Ces chaînes ont été ajoutées dans une version ultérieure à la dernière mise à jour de la traduction.	Mettez à jour le fichier `.po` par rapport au fichier POT actuel comme décrit ci-dessus, traduisez les nouvelles chaînes et recompilez.
Après une mise à jour de l'extension, les traductions reviennent à l'anglais.	La mise à jour de l'extension a écrasé le fichier `.mo` dans le propre répertoire `languages/` de l'extension.	Déplacez vos fichiers de traduction personnalisés vers `wp-content/languages/plugins/`. Les fichiers s'y trouvant ne sont pas touchés par les mises à jour de l'extension.
Le réglage de la langue du site indique qu'aucun fichier `.mo` compilé n'existe pour une locale particulière.	Seul un fichier source `.po` est intégré, sans `.mo` compilé.	Compilez le fichier `.po` avec `msgfmt` ou avec Poedit, puis placez le fichier `.mo` résultant dans le même répertoire.
Loco Translate affiche des avertissements "pas de référence" sur certaines chaînes.	La chaîne existe dans la traduction mais n'est plus présente dans le code source de l'extension.	Ces chaînes orphelines sont inoffensives ; elles n'affectent pas le comportement au moment de l'exécution. Vous pouvez les supprimer dans Loco Translate pour garder le fichier propre.