.po vs .mo vs .pot: Explicación de los Archivos de Traducción de WordPress

Abres la carpeta languages de un tema de WordPress y encuentras tres archivos que parecen casi idénticos: twentytwentyfour.pot, twentytwentyfour-de_DE.po y twentytwentyfour-de_DE.mo. Mismo tema, mismo idioma, tres extensiones diferentes. ¿Cuál editas? ¿Cuál carga realmente WordPress? ¿Y por qué editar el incorrecto hace que tus traducciones desaparezcan silenciosamente?

Si alguna vez te has preguntado qué archivo importa en el debate de los archivos .po vs .mo, no estás solo. Estas tres extensiones son la columna vertebral de cada sitio de WordPress traducido, sin embargo, la diferencia entre ellas confunde tanto a principiantes como a desarrolladores experimentados. Edita el archivo incorrecto y tus visitantes alemanes seguirán viendo el inglés. Edita el correcto pero omite un paso y tampoco cambiará nada.

Esta guía explica exactamente qué son los archivos .pot, .po y .mo, cómo se relacionan dentro del flujo de trabajo de GNU Gettext, dónde residen en WordPress y por qué nunca debes abrir un archivo .mo en un editor de texto. Al final sabrás qué archivo debes tocar y cuál debes dejar en paz.

¿Qué son los archivos .pot, .po y .mo?

En resumen: un archivo .pot es la plantilla en blanco, un archivo .po es tu traducción editable y un archivo .mo es el binario compilado que WordPress lee en tiempo de ejecución. Forman una cadena, y cada eslabón tiene exactamente un trabajo.

Estos tres formatos provienen de GNU Gettext, el sistema de localización en el que confían WordPress, Drupal y miles de proyectos de PHP y C. Gettext separa las cadenas de origen que escribe un desarrollador de las traducciones que proporciona un traductor, para que el mismo código base pueda hablar docenas de idiomas sin tocar una sola línea de PHP.

Piénsalo como una tarjeta de recetas. El .pot es la tarjeta en blanco con ranuras para ingredientes pero sin cantidades. El .po es la tarjeta rellenada para un plato específico. El .mo es la copia laminada y escaneable por máquina que la cocina realmente usa durante el servicio. Escribes en la tarjeta de papel; nunca garabateas en la laminada.

El archivo .pot: La plantilla maestra

Un archivo .pot (Plantilla de Objeto Portátil) contiene cada cadena traducible en un tema o plugin con las traducciones dejadas en blanco. Es la lista maestra que los desarrolladores envían para que los traductores sepan exactamente qué necesita ser traducido. Las líneas msgstr están en blanco porque aún no se ha elegido ningún idioma.

#: includes/checkout.php:42
msgid "Add to Cart"
msgstr ""

#: includes/account.php:108
msgid "Your order has been shipped to %s"
msgstr ""

Observa el msgstr "" vacío. Un .pot es una plantilla, no una traducción. Lo copias una vez por idioma y rellenas los espacios en blanco. Rara vez editas un .pot a mano; se regenera a partir del código fuente cada vez que las cadenas cambian.

El archivo .po: Tu traducción editable por humanos

Un archivo .po (Objeto Portátil) es una copia del .pot con las líneas msgstr rellenadas para un idioma. Este es el archivo que los traductores y desarrolladores realmente editan. Es texto plano, legible por humanos y compatible con el control de versiones.

#: includes/checkout.php:42
msgid "Add to Cart"
msgstr "In den Warenkorb"

#: includes/account.php:108
msgid "Your order has been shipped to %s"
msgstr "Ihre Bestellung wurde an %s versandt"

El msgid es la cadena de origen original en inglés y nunca debe cambiar. El msgstr es tu traducción. El %s es un marcador de posición que debe sobrevivir intacto en la traducción; eliminarlo o reordenarlo es la causa más común de diseños rotos, lo que cubrimos en profundidad en cómo traducir archivos PO sin romper las variables de código.

El archivo .mo: El binario compilado

Un archivo .mo (Objeto Máquina) es la versión compilada y binaria de tu .po. WordPress no puede leer archivos .po de manera eficiente en tiempo de ejecución, por lo que carga el .mo precompilado en su lugar. Abrir un .mo en un editor de texto muestra bytes ilegibles; está destinado a máquinas, no a personas.

Cuando WordPress llama a load_textdomain() o load_theme_textdomain(), busca un archivo .mo, analiza su tabla hash binaria e intercambia cada msgid por el msgstr correspondiente sobre la marcha. Este formato binario hace que las búsquedas sean rápidas incluso en sitios con miles de cadenas.

¿Cómo se relacionan los tres archivos en el flujo de trabajo de Gettext?

Forman una tubería unidireccional: el código fuente se convierte en un .pot, el .pot se convierte en un .po por idioma, y cada .po se compila en un .mo. Las traducciones siempre fluyen cuesta abajo.

Aquí está el ciclo de vida completo en orden:

1. Un desarrollador envuelve las cadenas orientadas al usuario en funciones Gettext como __() y _e() dentro del código fuente de PHP.
2. Una herramienta de escaneo lee el código fuente y genera la plantilla .pot que contiene cada cadena envuelta.
3. Un traductor copia el .pot en un .po específico del idioma (por ejemplo, de_DE.po) y rellena cada msgstr.
4. El .po terminado se compila en un .mo binario.
5. WordPress carga el .mo en tiempo de ejecución y muestra el sitio traducido.

Cuando el desarrollador añade nuevas cadenas más tarde, el .pot se regenera, las nuevas entradas se fusionan en cada .po existente (conservando las traducciones antiguas), el traductor rellena los huecos y el .po se vuelve a compilar a .mo. El ciclo se repite durante la vida del proyecto.

La clave fundamental: edita el .po y luego compila a .mo. Nunca edites el .mo directamente, y nunca traduzcas dentro del .pot. Si quieres una visión más profunda de principio a fin, la guía definitiva de localización de WordPress te guía a través de todo el proceso con ejemplos.

Convenciones de Nomenclatura y Dónde Residen los Archivos

WordPress es estricto con los nombres de archivo. Si te equivocas en la nomenclatura, tu .mo perfectamente traducido simplemente será ignorado, porque WordPress busca una coincidencia exacta basada en el dominio de texto y el idioma.

El patrón de nomenclatura para traducciones de temas y plugins es:

# Pattern: textdomain-locale.po / .mo
twentytwentyfour-de_DE.po      # German (Germany) translation
twentytwentyfour-de_DE.mo      # compiled binary WordPress loads
twentytwentyfour-fr_FR.po      # French (France)
twentytwentyfour.pot           # template, no locale suffix

El textdomain coincide con la cadena pasada como segundo argumento a funciones de Gettext como __( 'Add to Cart', 'twentytwentyfour' ). El locale es un código de idioma de WordPress como de_DE, fr_FR o pt_BR. La plantilla .pot no lleva sufijo de idioma porque es independiente del idioma.

La ubicación importa tanto como la nomenclatura. WordPress busca en algunas rutas predecibles:

• Las traducciones de temas se encuentran en la propia carpeta wp-content/themes/your-theme/languages/ del tema.
• Las traducciones de plugins se encuentran en wp-content/plugins/your-plugin/languages/.
• Las traducciones de translate.wordpress.org y las anulaciones de usuario se encuentran en los directorios globales wp-content/languages/themes/ y wp-content/languages/plugins/, que tienen prioridad y sobreviven a las actualizaciones.

Coloca un de_DE.mo con el nombre correcto en la carpeta adecuada y los visitantes alemanes verán el alemán. Colócalo una carpeta demasiado profunda, o escribe mal el dominio de texto, y WordPress volverá silenciosamente al inglés sin mensaje de error. Si tus traducciones no aparecen, un error de nomenclatura o de ruta es el culpable habitual, y la guía de solución de problemas para traducciones que no aparecen cubre todas las causas comunes.

Por qué nunca debes editar un archivo .mo directamente

Debido a que un .mo es un binario compilado, no hay una forma segura de editarlo a mano, y cualquier cambio que fuerces será sobrescrito la próxima vez que el .po se vuelva a compilar. El .po es la fuente de la verdad; el .mo es un artefacto de compilación desechable.

Esta única regla explica una gran parte de los tickets de soporte de "mi traducción cambió pero el sitio no se actualizó". Alguien ajusta una cadena, guarda el .po y olvida recompilar el .mo. WordPress sigue cargando el binario antiguo, por lo que la nueva redacción nunca aparece. La solución es siempre: editar el .po, recompilar a .mo, recargar.

Hermano hay una segunda razón por la que la regla es importante: los archivos .mo no son amigables para las diferencias en el control de versiones. Debido a que son binarios, un pequeño cambio de redacción produce un blob opaco en tu historial de Git que ningún revisor puede leer. Mantener el .po como la fuente de verdad rastreada y tratar el .mo como un artefacto generado mantiene tu repositorio revisable y tus traducciones auditables.

Hacer esto manualmente en docenas de idiomas es tedioso y propenso a errores. Aquí es donde un flujo de trabajo en la nube ahorra tiempo real. Herramientas como SimplePoTranslate traducen tus cadenas .po y devuelven un único ZIP que contiene el .po y .mo correspondientes juntos, ya compilados, correctamente nombrados y listos para ser colocados en wp-content/languages/. No hay nada que compilar manualmente y no hay posibilidad de un .mo obsoleto.

También aplica el Bloqueo de Sintaxis, que congela cada marcador de posición como %s, %1$s y {name}, además de las etiquetas HTML, antes de la traducción. Tus variables sobreviven intactas, por lo que nunca enviarás un .mo que rompa un diseño. Y debido a que se ejecuta completamente en la nube, no hay ningún plugin adicional que ralentice tu sitio: subes un archivo y descargas traducciones terminadas y compiladas.

Recopilando todo

Una vez que la distinción entre archivos .po vs .mo hace clic, todo el sistema de traducción de WordPress deja de parecer misterioso. El .pot es la plantilla del desarrollador, el .po es la copia de trabajo editable del traductor, y el .mo es el binario compilado que WordPress realmente sirve a los visitantes. Las traducciones fluyen en una dirección — plantilla a .po a .mo — y solo editas manualmente el del medio.

Recuerda las tres reglas que previenen el noventa por ciento de los dolores de cabeza de traducción: nunca traduzcas dentro de un .pot, siempre vuelve a compilar el .mo después de editar un .po, y haz coincidir exactamente la nomenclatura textdomain-locale. Sigue estas reglas y tus cadenas traducidas aparecerán siempre.

¿Listo para dejar de luchar con la compilación y la nomenclatura manual de archivos de traducción? Prueba SimplePoTranslate gratis — no se requiere tarjeta de crédito. Sube tu .po o .pot y obtén un paquete .po + .mo listo para usar en el nivel gratuito en minutos.