Documentación · Documentación técnica

Internacionalización y Poedit

Este documento explica cómo el plugin ADP Car Market Hub gestiona las traducciones, dónde residen los archivos de idioma y cómo actualizar o añadir traducciones utilizando Poedit (o cualquier editor gettext compatible).

Cuándo utilizar este documento

Lea este documento si necesita:

Traducir el plugin a un nuevo idioma.
Actualizar una traducción existente después de actualizar el plugin.
Verificar qué locales están incluidos y cómo se cargan.
Diagnosticar cadenas que aparecen sin traducir en el administrador o en el front-end.

Descripción general

El plugin utiliza los mecanismos estándar de internacionalización (i18n) de WordPress:

Todas las cadenas traducibles están envueltas en funciones gettext (__(), _e(), _n(), _x(), etc.) utilizando el dominio de texto adp-car-market-hub.
Las traducciones se cargan desde la carpeta languages/ del plugin a través de load_plugin_textdomain() en plugins_loaded con prioridad 1, antes de que se renderice cualquier cadena visible para el usuario.
Se incluye una plantilla POT (adp-car-market-hub.pot) con el plugin, la cual se puede abrir o regenerar con Poedit o WP-CLI.

El dominio de texto coincide con el slug de la carpeta del plugin (adp-car-market-hub), por lo que las traducciones de las cadenas de herramientas al estilo de translate.wordpress.org se detectan automáticamente cuando se entregan en las ubicaciones estándar.

Archivos en `languages/`

La carpeta integrada languages/ contiene:

adp-car-market-hub.pot: plantilla de traducción generada por i18n make-pot de WP-CLI (visible en la cabecera del POT).
adp-car-market-hub-de_DE.po: alemán (Alemania).
adp-car-market-hub-de_DE_formal.po / adp-car-market-hub-de_DE_formal.mo: alemán (formal).
adp-car-market-hub-de_AT.po: alemán (Austria).
adp-car-market-hub-de_CH.po: alemán (Suiza).
adp-car-market-hub-fr_FR.po: francés (Francia).
adp-car-market-hub-it_IT.po: italiano (Italia).

Verifique la lista exacta de archivos .po y .mo en la versión actual del plugin antes de publicar textos de cara al cliente. WordPress carga el archivo .mo que coincide con el locale activo del sitio; los archivos .po por sí solos no son suficientes en tiempo de ejecución.

Requisitos o prerrequisitos

Un editor gettext: Poedit es la herramienta GUI recomendada. La edición gratuita es suficiente.
Opcional: WP-CLI con el comando i18n, utilizado para regenerar el archivo POT desde el código fuente.
Acceso de escritura a la carpeta languages/ del plugin (o a una ubicación de anulación, ver más abajo).

Instrucciones paso a paso

Traducir a un nuevo locale

Abra Poedit y elija Archivo → Nuevo desde archivo POT/PO.
Seleccione languages/adp-car-market-hub.pot.
Elija el locale de destino. Guarde el archivo como adp-car-market-hub-<locale>.po dentro de la misma carpeta languages/, donde <locale> es el código de locale de WordPress (por ejemplo, es_ES, nl_NL).
Traduzca las cadenas en el editor.
Guarde. Poedit escribe automáticamente un archivo .mo coincidente junto al archivo .po.
Establezca el idioma del sitio en WordPress a su nuevo locale y recargue las páginas de administración y del front-end para verificar las traducciones.

Actualizar una traducción existente después de una actualización del plugin

Abra el archivo .po existente en Poedit.
Elija Catálogo → Actualizar desde archivo POT y seleccione el nuevo adp-car-market-hub.pot.
Traduzca cualquier cadena nueva o modificada (Poedit las resaltará como no traducidas o dudosas).
Guarde. El archivo .mo se regenera automáticamente.

Regenerar la plantilla POT desde el código fuente (opcional)

Si mantiene el código fuente del plugin y necesita actualizar el POT usted mismo, puede hacerlo con WP-CLI:

wp i18n make-pot . languages/adp-car-market-hub.pot --domain=adp-car-market-hub

Ejecute esto desde el directorio raíz del plugin. La cabecera del archivo registra la versión de WP-CLI que lo produjo.

Utilizar traducciones desde fuera de la carpeta del plugin

WordPress también busca traducciones en wp-content/languages/plugins/adp-car-market-hub-<locale>.mo. Coloque un archivo .mo personalizado allí si desea que las traducciones sobrevivan a las actualizaciones del plugin que sobrescriben languages/.

Notas operativas

El dominio de texto se carga con la prioridad 1 de plugins_loaded, que es intencionadamente antes de que se ejecute la devolución de llamada principal init() del plugin en la prioridad por defecto. Esto asegura que cada cadena traducible registrada posteriormente ya tenga acceso al archivo .mo cargado.
Guarde siempre de nuevo el archivo .po con Poedit (o compile el archivo .mo con msgfmt) después de editarlo; WordPress lee el archivo binario .mo en tiempo de ejecución, no el archivo de texto .po.
Los códigos de locale distinguen entre mayúsculas y minúsculas en sistemas de archivos que distinguen entre mayúsculas y minúsculas. Utilice el identificador de locale exacto de WordPress.
Las actualizaciones de traducción no deben modificar ningún archivo de origen; esta tarea de documentación las excluye explícitamente.
Algunas cadenas (por ejemplo, los identificadores de modelos de proveedores en el AI Assistant o las etiquetas de opciones técnicas) se mantienen intencionadamente en inglés. Traduzca los textos visibles para el usuario y deje los identificadores intactos.

Resolución de problemas

Una cadena sigue apareciendo en inglés: confirme que existe un archivo .mo para el locale activo en languages/ (o en wp-content/languages/plugins/), que el archivo coincide con el dominio de texto del plugin (adp-car-market-hub), y que el idioma de su sitio en WordPress está configurado correctamente.
Una nueva traducción no se carga hasta que se borra la caché: algunos plugins de caché de objetos almacenan en caché las traducciones. Vacíe la caché de objetos de WordPress después de implementar nuevos archivos .mo.
Poedit muestra muchas cadenas dudosas (fuzzy) después de una actualización: esto es lo esperado cuando cambia el texto de origen. Revise cada entrada dudosa, corrija la traducción y desmárquela como dudosa.
Las traducciones personalizadas se sobrescriben con las actualizaciones del plugin: almacene las traducciones personalizadas en wp-content/languages/plugins/ en lugar de en la carpeta languages/ del plugin.