Internacionalización para desarrolladores

Este documento describe cómo el plugin ADP Car Market Hub gestiona la internacionalización (i18n) para traductores y colaboradores. Cubre el text domain, el mecanismo de carga, los archivos de traducción incluidos con el plugin, las herramientas utilizadas para generar el archivo POT y las convenciones a seguir al añadir nuevas cadenas traducibles.

Cuándo utilizar este documento

Lea este documento cuando necesite:

• Añadir una nueva cadena traducible al código PHP, JavaScript o de plantillas.
• Regenerar el archivo POT después de añadir cadenas.
• Proporcionar una traducción en un nuevo idioma para el plugin.
• Comprender por qué una cadena concreta de la administración o del frontend está o no traducida.

Para notas dirigidas a traductores, consulte el README-i18n.md del repositorio.

Descripción general

El plugin utiliza las API de i18n estándar de WordPress (__(), _e(), _n(), _x(), esc_html__(), esc_attr__(), esc_html_e(), esc_attr_e(), …) con un único text domain.

• Text domain: adp-car-market-hub.
• Ruta del dominio: /languages (declarada en la cabecera del plugin).
• Cargador: load_plugin_textdomain( 'adp-car-market-hub', false, '/languages' ) se llama desde una función acoplada a plugins_loaded con prioridad 1, de modo que las traducciones se cargan antes de que se ejecute el propio trabajo de init del plugin.

Las cadenas de JavaScript utilizadas por los scripts empaquetados del plugin se traducen previamente en PHP y se pasan a JavaScript a través de wp_localize_script(). Actualmente, el plugin no depende de wp_set_script_translations() ni del flujo de trabajo de traducción JSON asociado a este.

Requisitos o prerrequisitos

• Archivos de origen escritos utilizando las funciones de i18n de WordPress con 'adp-car-market-hub' como text domain.
• WP-CLI instalado al regenerar el archivo POT (el script auxiliar utiliza wp i18n make-pot).
• Un editor compatible con POEdit (o cualquier herramienta que entienda GNU gettext) para editar archivos .po.

Archivos de traducción incluidos con el plugin

Todos los archivos de traducción se encuentran bajo /languages y siguen la convención de nomenclatura estándar de WordPress.

Cada idioma incluido contiene tanto un origen .po como un .mo compilado. La lista anterior refleja los archivos presentes actualmente; verifique el conjunto más reciente en la carpeta /languages antes de publicar.

Herramientas

Regenerar el archivo POT

Se proporciona un script auxiliar en el directorio bin/ del repositorio. Llama al comando i18n make-pot de WP-CLI y excluye las carpetas que no deben escanearse (.git, node_modules, vendor, tests, bin).

Para ejecutarlo:

1. Asegúrese de que WP-CLI esté instalado y disponible en PATH.
2. Desde la raíz del repositorio, ejecute el script.
3. El archivo .pot actualizado se escribe en languages/adp-car-market-hub.pot.

Compilar archivos .mo

Después de editar un archivo .po, compile el .mo correspondiente con su editor (la opción "Guardar" de POEdit produce ambos archivos automáticamente) o con msgfmt de gettext.

Instrucciones paso a paso

Añadir una cadena traducible en PHP

1. Envuelva la cadena con la función de i18n de WordPress adecuada y pase 'adp-car-market-hub' como text domain. Por ejemplo, __( 'Lead saved.', 'adp-car-market-hub' ) o esc_html__( 'Vehicles', 'adp-car-market-hub' ).
2. Cuando la cadena esté concatenada con HTML, prefiera las variantes esc_*__ y esc_*_e para combinar el escape y la traducción en una sola llamada.
3. Para la pluralización, utilice _n() o _nx(). Para la desambiguación de contexto, utilice _x().
4. Regenere el archivo POT (ver arriba) para que los traductores puedan incorporar la nueva cadena.

Añadir una cadena traducible utilizada en JavaScript

1. Traduzca primero la cadena en PHP (__( 'Sending…', 'adp-car-market-hub' )).
2. Pásela a JavaScript a través del array wp_localize_script() utilizado por el handle correspondiente. Consulte Frontend Assets y Admin Assets para ver los objetos localizados que ya están en uso (por ejemplo, AS24CI, as24ciCompare, AS24CI_LEADS, AS24CI_BATCH).
3. Lea el valor desde la variable global correspondiente en el código JavaScript.

Proporcionar una nueva traducción

1. Copie languages/adp-car-market-hub.pot a languages/adp-car-market-hub-<locale>.po utilizando el código de idioma de WordPress (por ejemplo, es_ES).
2. Traduzca las cadenas.
3. Compile el archivo .mo junto con el .po.
4. Abra un pull request con ambos archivos.

Notas operativas

• Único text domain. Cada cadena traducible en el plugin utiliza 'adp-car-market-hub'. No introduzca text domains adicionales.
• Mantener el POT actualizado. Cuando un colaborador añada o elimine cadenas, regenere el archivo POT en el mismo cambio para que los archivos de traducción se puedan fusionar de manera limpia.
• Cadenas de JavaScript. Debido a que las cadenas de JS se traducen a través de wp_localize_script(), solo aparecen en el POT cuando está presente la llamada __() correspondiente en el lado de PHP. Traduzca siempre las cadenas de JS primero en PHP.
• Formato adaptado a la configuración regional. El formato de números y monedas se gestiona mediante los helpers de configuración regional propios del plugin. Utilice los helpers expuestos por el plugin en lugar de volver a implementar la lógica de configuración regional en su propio código.
• Plataforma de traducción WordPress. El plugin se puede traducir fuera del repositorio a través de cualquier flujo de trabajo estándar de gettext. No se requiere ningún servicio de traducción externo específico.

Resolución de problemas

• Una cadena no se traduce en el frontend. Confirme que la cadena esté envuelta en una función de i18n con el text domain correcto. Confirme que el idioma esté instalado en WordPress (Ajustes → General → Idioma del sitio) y que exista un archivo .mo para esa configuración regional en /languages.
• Las cadenas recién añadidas no aparecen en el POT. Vuelva a ejecutar el script auxiliar del POT. Verifique que su archivo no se encuentre en una de las carpetas excluidas.
• El texto del lado de JS sigue en inglés después de la traducción en PHP. Confirme que la cadena se esté pasando a través de wp_localize_script() para el handle correspondiente. El plugin no detecta automáticamente las cadenas de JS no traducidas.
• Los plurales recurren a la forma singular. Utilice _n() (o _nx() para el contexto) en lugar de __() para cualquier cadena que varíe con una cantidad.
• Verifique el comportamiento en la versión actual del plugin antes de publicar una integración personalizada. Los nombres de los objetos JavaScript localizados pueden evolucionar entre versiones.

Documentos relacionados

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