Internationalisation pour les développeurs

Ce document décrit comment l'extension ADP Car Market Hub gère l'internationalisation (i18n) pour les traducteurs et les contributeurs. Il couvre le text domain, le mécanisme de chargement, les fichiers de traduction fournis avec l'extension, les outils utilisés pour générer le fichier POT et les conventions à suivre lors de l'ajout de nouvelles chaînes traduisibles.

Quand utiliser ce document

Lisez ce document lorsque vous devez :

• Ajouter une nouvelle chaîne traduisible dans le code PHP, JavaScript ou les modèles.
• Régénérer le fichier POT après avoir ajouté des chaînes.
• Fournir une nouvelle traduction de langue pour l'extension.
• Comprendre pourquoi une chaîne d'administration ou du front-end spécifique est ou n'est pas traduite.

Pour les notes destinées aux traducteurs, consultez le README-i18n.md du dépôt.

Aperçu

L'extension utilise les API d'i18n standard de WordPress (__(), _e(), _n(), _x(), esc_html__(), esc_attr__(), esc_html_e(), esc_attr_e(), …) avec un seul text domain.

• Text domain : adp-car-market-hub.
• Chemin du domaine : /languages (déclaré dans l'en-tête de l'extension).
• Chargeur : load_plugin_textdomain( 'adp-car-market-hub', false, '/languages' ) est appelé depuis une fonction hookée à plugins_loaded avec une priorité de 1, de sorte que les traductions soient chargées avant que le propre travail de init de l'extension ne s'exécute.

Les chaînes JavaScript utilisées par les scripts intégrés de l'extension sont pré-traduites en PHP et transmises à JavaScript via wp_localize_script(). L'extension ne s'appuie pas actuellement sur wp_set_script_translations() et le flux de travail de traduction JSON qui lui est associé.

Configuration requise ou prérequis

• Fichiers sources écrits à l'aide des fonctions d'i18n de WordPress avec 'adp-car-market-hub' comme text domain.
• WP-CLI installé lors de la régénération du fichier POT (le script d'aide utilise wp i18n make-pot).
• Un éditeur compatible avec POEdit (ou tout outil comprenant GNU gettext) pour éditer les fichiers .po.

Fichiers de traduction fournis avec l'extension

Tous les fichiers de traduction se trouvent sous /languages et suivent la convention de nommage standard de WordPress.

Chaque langue fournie comprend à la fois une source .po et un fichier compilé .mo. La liste ci-dessus reflète les fichiers actuellement présents ; vérifiez le dernier ensemble dans le dossier /languages avant de publier.

Outils

Régénérer le fichier POT

Un script d'aide est fourni dans le répertoire bin/ du dépôt. Il appelle la commande i18n make-pot de WP-CLI et exclut les dossiers qui ne doivent pas être analysés (.git, node_modules, vendor, tests, bin).

Pour l'exécuter :

1. Assurez-vous que WP-CLI est installé et disponible sur PATH.
2. Depuis la racine du dépôt, exécutez le script.
3. Le fichier .pot mis à jour est écrit dans languages/adp-car-market-hub.pot.

Compiler les fichiers .mo

Après avoir modifié un fichier .po, compilez un fichier .mo correspondant avec votre éditeur (l'action "Enregistrer" de POEdit produit automatiquement les deux fichiers) ou avec msgfmt de gettext.

Instructions étape par étape

Ajouter une chaîne traduisible en PHP

1. Enveloppez la chaîne avec la fonction d'i18n de WordPress appropriée et passez 'adp-car-market-hub' comme text domain. Par exemple, __( 'Lead saved.', 'adp-car-market-hub' ) ou esc_html__( 'Vehicles', 'adp-car-market-hub' ).
2. Lorsque la chaîne est concaténée avec du HTML, préférez les variantes esc_*__ et esc_*_e pour combiner l'échappement et la traduction en un seul appel.
3. Pour la gestion du pluriel, utilisez _n() ou _nx(). Pour lever l'ambiguïté liée au contexte, utilisez _x().
4. Régénérez le fichier POT (voir ci-dessus) afin que les traducteurs puissent récupérer la nouvelle chaîne.

Ajouter une chaîne traduisible utilisée en JavaScript

1. Traduisez d'abord la chaîne en PHP (__( 'Sending…', 'adp-car-market-hub' )).
2. Transmettez-la à JavaScript via le tableau wp_localize_script() utilisé par le handle concerné. Consultez Frontend Assets et Admin Assets pour les objets localisés déjà utilisés (par exemple AS24CI, as24ciCompare, AS24CI_LEADS, AS24CI_BATCH).
3. Lisez la valeur à partir de la variable globale correspondante dans le code JavaScript.

Fournir une nouvelle traduction

1. Copiez languages/adp-car-market-hub.pot vers languages/adp-car-market-hub-<locale>.po en utilisant le code de langue WordPress (par exemple es_ES).
2. Traduisez les chaînes.
3. Compilez le fichier .mo aux côtés du .po.
4. Ouvrez une pull request avec les deux fichiers.

Notes opérationnelles

• Text domain unique. Chaque chaîne traduisible de l'extension utilise 'adp-car-market-hub'. N'introduisez pas de text domains supplémentaires.
• Maintenir le POT à jour. Lorsqu'un contributeur ajoute ou supprime des chaînes, régénérez le fichier POT dans la même modification afin que les fichiers de traduction puissent être fusionnés proprement.
• Chaînes JavaScript. Étant donné que les chaînes JS sont traduites via wp_localize_script(), elles n'apparaissent dans le POT que lorsque l'appel __() correspondant côté PHP est présent. Traduisez toujours les chaînes JS en PHP en premier.
• Formatage sensible à la localisation. Le formatage des nombres et des devises est géré par les propres assistants de localisation de l'extension. Utilisez les assistants exposés par l'extension plutôt que de réimplémenter une logique de localisation dans votre propre code.
• Plateforme de traduction WordPress. L'extension peut être traduite en dehors du dépôt via n'importe quel flux de travail gettext standard. Aucun service de traduction externe spécifique n'est requis.

Dépannage

• Une chaîne n'est pas traduite sur le front-end. Confirmez que la chaîne est enveloppée dans une fonction d'i18n avec le bon text domain. Confirmez que la langue est installée dans WordPress (Réglages → Général → Langue du site) et qu'un fichier .mo pour cette langue existe dans /languages.
• Les chaînes nouvellement ajoutées n'apparaissent pas dans le POT. Réexécutez le script d'aide POT. Vérifiez que votre fichier ne se trouve pas sous l'un des dossiers exclus.
• Le texte côté JS est toujours en anglais après la traduction PHP. Confirmez que la chaîne est transmise via wp_localize_script() pour le handle concerné. L'extension ne détecte pas automatiquement les chaînes JS non traduites.
• Les pluriels reviennent à la forme singulière. Utilisez _n() (ou _nx() pour le contexte) au lieu de __() pour toute chaîne qui varie avec un nombre.
• Vérifiez le comportement dans la version actuelle de l'extension avant de publier une intégration personnalisée. Les noms d'objets JavaScript localisés peuvent évoluer entre les versions.

Documents connexes

• Frontend Assets
• Admin Assets
• Coding Standards
• Repository Structure
• Contribution Guidelines