Documentación · Guía de integración

Guía de traducción y Poedit

Este documento explica cómo el plugin ADP Car Market Hub gestiona los sitios de WordPress multilingües, qué archivos de traducción se proporcionan con el plugin y cómo traducir o actualizar las cadenas del plugin utilizando Poedit o herramientas equivalentes.

Cuándo utilizar este documento

Utilice este documento si:

Está configurando el plugin en un sitio cuyo idioma de WordPress no es el inglés y desea confirmar que las traducciones se cargan correctamente.
Es un concesionario o una agencia que desea añadir o corregir traducciones para un idioma que ya está incluido en el plugin.
Es un desarrollador que desea aportar un nuevo archivo de idioma para una localización que aún no está integrada en el plugin.
Está solucionando problemas con textos del plugin que aparecen en inglés cuando el idioma del sitio está configurado en otra localización.
El público objetivo es un administrador de WordPress o un desarrollador familiarizado con el flujo de trabajo de internacionalización de WordPress y el uso básico de la línea de comandos.

Descripción general

El plugin utiliza el mecanismo de localización estándar de WordPress. Todas las cadenas visibles para el usuario en el código PHP del plugin están envueltas en funciones de traducción de WordPress (__(), _e(), esc_html__() y similares) con el dominio de texto adp-car-market-hub. WordPress carga el archivo de traducción correspondiente desde la carpeta languages/ del plugin cuando se establece el idioma del sitio en Ajustes → General → Idioma del sitio.

Los siguientes archivos de idioma se incluyen con el plugin en el momento de escribir este documento:

Código de localización	Idioma
`de_AT`	Alemán (Austria)
`de_CH`	Alemán (Suiza)
`de_DE`	Alemán (Alemania)
`de_DE_formal`	Alemán (Alemania, tratamiento formal)
`fr_FR`	Francés (Francia)
`it_IT`	Italiano (Italia)
`es_ES`	Español (España)
`nl_NL`	Neerlandés (Países Bajos)

Verifique la lista actual revisando el directorio languages/ dentro de la carpeta del plugin (wp-content/plugins/adp-car-market-hub/languages/). Cada localización tiene un archivo fuente .po (editable por humanos) y, cuando hay un archivo compilado .mo presente, ese archivo es el que WordPress realmente carga en tiempo de ejecución.

Si el sitio utiliza una localización que no está en la lista anterior, el plugin mostrará todas las cadenas en el idioma de reserva, que es el inglés.

Requisitos previos

Acceso de administrador de WordPress.
Para editar traducciones: Poedit (https://poedit.net/) o un editor de archivos .po / .mo equivalente, o el plugin de WordPress Loco Translate (https://wordpress.org/plugins/loco-translate/).
Para generar un nuevo archivo POT: WP-CLI versión 2.6 o superior, o el script make-pot.sh en bin/make-pot.sh.
Para compilar archivos .mo desde la línea de comandos: la utilidad GNU gettext msgfmt, o el comando wp i18n make-mo de WP-CLI.

Cómo carga el plugin las traducciones

El plugin llama a load_plugin_textdomain() en la acción plugins_loaded con prioridad 1. Esto significa que el archivo de traducción para el idioma actual del sitio se carga antes de que se ejecute cualquier otro código del plugin con la prioridad por defecto, por lo que todas las cadenas de la administración y del frontend están disponibles para su traducción desde el momento en que se inicializa el plugin.

WordPress resuelve el archivo de idioma en el siguiente orden:

wp-content/languages/plugins/adp-car-market-hub-{locale}.mo (archivos de traducción instalados por el propio WordPress o por una herramienta de gestión de traducciones).
wp-content/plugins/adp-car-market-hub/languages/adp-car-market-hub-{locale}.mo (archivos incluidos con el plugin).

Los archivos en wp-content/languages/plugins/ tienen prioridad. Si actualiza una traducción integrada utilizando un plugin como Loco Translate, el archivo actualizado se guardará normalmente en la primera ruta, lo que protege sus cambios de ser sobrescritos cuando se actualice el plugin.

Instrucciones paso a paso

Uso de una traducción integrada existente

En WordPress, abra Ajustes → General.
Establezca el Idioma del sitio en la localización deseada (por ejemplo, Alemán (Suiza) para de_CH).
Guarde los ajustes.
Navegue a cualquier página de administración del plugin o visite el archivo de vehículos en el frontend. Las cadenas del plugin (etiquetas, botones, mensajes de error) deberían aparecer en el idioma seleccionado.
Si las cadenas siguen apareciendo en inglés, consulte la sección de Resolución de problemas más abajo.

Edición o corrección de una traducción existente con Poedit

Descargue e instale Poedit desde https://poedit.net/.
Localice el archivo .po para la localización que desea editar, dentro del directorio languages/ del plugin. Por ejemplo: wp-content/plugins/adp-car-market-hub/languages/adp-car-market-hub-de_CH.po.
Abra el archivo .po en Poedit.
Busque la cadena que desea cambiar en la lista de cadenas. La columna Texto de origen muestra el original en inglés y la columna Traducción muestra el valor traducido actual. Haga clic en una fila para editar la traducción en el panel de edición inferior.
Guarde el archivo. Poedit compila automáticamente el archivo .mo correspondiente en el mismo directorio.
Recomendado: Copie los archivos .po y .mo actualizados a wp-content/languages/plugins/ para que las actualizaciones del plugin no los sobrescriban: - wp-content/languages/plugins/adp-car-market-hub-de_CH.po - wp-content/languages/plugins/adp-car-market-hub-de_CH.mo
Borre cualquier caché de WordPress que pueda estar sirviendo contenido obsoleto y, a continuación, verifique el cambio en la página correspondiente del plugin.

Edición de una traducción existente con Loco Translate

Instale y active el plugin Loco Translate desde el directorio de plugins de WordPress.
En WordPress, navegue a Loco Translate → Plugins.
Busque ADP Car Market Hub en la lista y haga clic en él.
Seleccione el idioma que desea editar.
Edite las cadenas en el editor de Loco Translate y guarde los cambios. Loco Translate compila el archivo .mo automáticamente y guarda sus cambios en wp-content/languages/plugins/, protegiéndolos de las actualizaciones del plugin.

Creación de una traducción para un nuevo idioma

Abra el archivo plantilla POT: wp-content/plugins/adp-car-market-hub/languages/adp-car-market-hub.pot. El archivo POT contiene todas las cadenas traducibles del plugin sin ninguna traducción.
En Poedit, elija Archivo → Nuevo desde un archivo POT/PO, seleccione el archivo .pot y elija el idioma de destino.
Traduzca las cadenas.
Guarde como adp-car-market-hub-{locale}.po y compile a adp-car-market-hub-{locale}.mo. Utilice el código de localización exacto que WordPress utiliza para ese idioma (por ejemplo, fr_CH para francés de Suiza). Verifique el código en Ajustes → General → Idioma del sitio.
Coloque ambos archivos en wp-content/languages/plugins/ para que no se sobrescriban con las actualizaciones del plugin.
Establezca el idioma del sitio y verifique que la nueva traducción se cargue correctamente.

Actualización de los archivos de traducción tras una actualización del plugin

Cuando se actualiza el plugin, es posible que se añadan nuevas cadenas. Los archivos .po integrados son actualizados por los mantenedores del plugin, pero las traducciones personalizadas almacenadas fuera del directorio del plugin no se actualizan automáticamente.

Para poner al día su archivo de traducción personalizado:

Descargue el archivo POT actualizado desde el directorio languages/ del plugin.
En Poedit, abra su archivo .po personalizado, luego elija Traducción → Actualizar desde archivo POT y seleccione el nuevo archivo .pot. Poedit fusionará las nuevas cadenas en su archivo, marcando las cadenas no traducidas para que les preste atención.
Traduzca las nuevas cadenas.
Guarde y compile.

Si utiliza WP-CLI, actualice un archivo .po con msgmerge:

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

Compile el archivo actualizado:

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

O compile todos los archivos .po a la vez con WP-CLI:

wp i18n make-mo languages/

Referencia de configuración

No existe una página de ajustes de traducción dedicada en la administración del plugin. La traducción se gestiona por completo a través del ajuste de idioma del sitio de WordPress y el sistema de localización estándar de WordPress.

Qué configurar	Dónde
Idioma del sitio que determina qué archivo de traducción se carga	Ajustes → General → Idioma del sitio
Editar traducciones integradas sin perder los cambios al actualizar	Utilice Loco Translate, que almacena las ediciones en `wp-content/languages/plugins/`
Generar un archivo POT actualizado a partir del código fuente PHP del plugin	Ejecute `./bin/make-pot.sh` o `wp i18n make-pot` (consulte el archivo README de i18n)

Notas de funcionamiento

Dominio de texto. Cada cadena traducible en el plugin utiliza el dominio de texto adp-car-market-hub. Este dominio de texto se declara en la cabecera del plugin y debe coincidir con el prefijo del nombre de archivo de los archivos de traducción (por ejemplo, adp-car-market-hub-de_DE.mo). Una discrepancia entre el dominio de texto y el nombre del archivo es la razón más común por la que las cadenas no se traducen.
Se requieren archivos .mo compilados en tiempo de ejecución. WordPress lee archivos .mo compilados, no los archivos fuente .po legibles por humanos. Compile siempre un archivo .po nuevo o actualizado a .mo antes de esperar ver los cambios en el navegador.
Alemán formal frente a informal. La localización de_DE_formal proporciona un estilo de tratamiento formal (Sie) para el alemán. Elija esta localización en los sitios donde se espere una redacción formal.
Se cubren tanto las cadenas del frontend como las de la administración. El dominio de texto del plugin incluye cadenas tanto para las páginas de administración (ajustes, estado de importación, registros) como para la salida del frontend (etiquetas de vehículos, etiquetas de filtros, mensajes del formulario de contacto, calculadora de financiación). Ambos conjuntos de cadenas se encuentran en el mismo archivo .po / .mo.
Paquetes de idioma de WordPress. Si el sistema de paquetes de idioma de WordPress dispone de una traducción comunitaria para adp-car-market-hub para la localización seleccionada, WordPress puede ofrecer su descarga automática. Los archivos obtenidos de esta forma se almacenan en wp-content/languages/plugins/ y se actualizan junto con el núcleo de WordPress. Verifique que la traducción comunitaria esté completa antes de confiar en ella para entornos de producción.
Caché. Si las traducciones no aparecen después de realizar un cambio, borre cualquier caché de objetos de WordPress, caché de página o caché de opcode. El código de bytes almacenado en caché de los archivos .mo antiguos puede persistir hasta que se vacíe la caché.
Archivos de documentación. La documentación en docs/ está escrita únicamente en inglés. No existen archivos de documentación traducidos. La traducción de las cadenas PHP del plugin (como se describe en esta guía) y la traducción de la documentación son procesos independientes.

Resolución de problemas

Síntoma	Causa probable	Qué comprobar
Las cadenas del plugin aparecen en inglés a pesar de que el idioma del sitio está configurado correctamente.	El archivo `.mo` para la localización seleccionada falta o no está compilado.	Compruebe que existen tanto los archivos `.po` como `.mo` en `wp-content/plugins/adp-car-market-hub/languages/` o `wp-content/languages/plugins/`. El archivo `.mo` debe estar presente.
Poedit guarda el archivo `.po` pero las cadenas no cambian en WordPress.	Poedit compiló el `.mo` junto al `.po`, pero WordPress está cargando un `.mo` desde una ruta diferente.	Compruebe tanto el directorio `languages/` del plugin como `wp-content/languages/plugins/`. El archivo en `wp-content/languages/plugins/` tiene prioridad.
Algunas cadenas se traducen pero otras permanecen en inglés.	Esas cadenas se añadieron en una versión posterior a la última actualización de la traducción.	Actualice el archivo `.po` con respecto al archivo POT actual como se ha descrito anteriormente, traduzca las nuevas cadenas y vuelva a compilar.
Tras una actualización del plugin, las traducciones vuelven al inglés.	La actualización del plugin sobrescribió el archivo `.mo` en el propio directorio `languages/` del plugin.	Mueva sus archivos de traducción personalizados a `wp-content/languages/plugins/`. Los archivos allí ubicados no se ven afectados por las actualizaciones del plugin.
El ajuste de idioma del sitio muestra que no existe ningún archivo `.mo` compilado para una localización concreta.	Solo se incluye un archivo fuente `.po`, sin un `.mo` compilado.	Compile el archivo `.po` con `msgfmt` o con Poedit, y luego coloque el archivo `.mo` resultante en el mismo directorio.
Loco Translate muestra advertencias de "sin referencia" en algunas cadenas.	la cadena existe en la traducción pero ya no está en el código fuente del plugin.	Estas cadenas huérfanas son inofensivas; no afectan al comportamiento en tiempo de ejecución. Puede eliminarlas en Loco Translate para mantener limpio el archivo.