Por Qué Tus Traducciones No Se Muestran en WordPress (Guía de Solución de Problemas)

No hay nada más frustrante en el desarrollo de WordPress que el "Fallo Silencioso".

Lo hiciste todo bien. Tradujiste el archivo .po. Lo compilaste en un archivo .mo. Lo subiste a tu servidor vía FTP. Limpiaste tu caché.

Actualizas la página, esperando ver español, francés o alemán. En cambio, ves... inglés.

Sin mensaje de error, sin pantalla blanca, solo texto obstinado, sin traducir. Antes de que te arranques los pelos, lee esta guía. Aquí están las 5 razones más comunes por las que las traducciones no se cargan en WordPress y cómo solucionarlas.

1. Estás Nombrando Mal el Archivo

WordPress es increíblemente estricto con el nombre de los archivos. Si te falta un carácter, no cargará el archivo.

El formato estándar es: {text-domain}-{locale}.mo

• El Dominio de Texto: Este es el ID único del tema o plugin (por ejemplo, woocommerce, twentytwentyfour, my-custom-plugin).
• La Configuración Regional (Locale): El código de configuración regional de WP (por ejemplo, es_ES para español de España, fr_FR para francés de Francia).

Errores Comunes:

• Nombrar el archivo solo como es_ES.mo (Esto solo funciona para los archivos del núcleo de WordPress, no para los plugins).
• Usar el guion incorrecto: my_plugin_es_ES.mo (Guion bajo) en lugar de my-plugin-es_ES.mo (Guion medio).
• Adivinar el dominio de texto. Debes revisar el código del plugin (cabecera style.css o función load_plugin_textdomain) para encontrar el slug exacto.

2. Pusiste el Archivo en la Carpeta Incorrecta

Dónde subes el archivo importa tanto como el nombre que le das. WordPress busca en directorios específicos en un orden específico.

• La Carpeta del Sistema "Segura": /wp-content/languages/plugins/ o /wp-content/languages/themes/.
  • Pros: Esto está a salvo de las actualizaciones del plugin.
  • Contras: Debes nombrar el archivo textdomain-locale.mo.
• La Carpeta del Autor: /wp-content/plugins/plugin-name/languages/.
  • Pros: Fácil de encontrar.
  • Contras: PELIGRO. Cuando actualizas el plugin, esta carpeta se borra por completo. Tus traducciones desaparecerán.

Mejores Prácticas: Siempre coloca tus archivos .mo personalizados en el directorio global /wp-content/languages/ para evitar la pérdida de datos durante las actualizaciones.

3. El "Asesino Silencioso": Sintaxis Corrupta en el Archivo .po

Este es el problema más difícil de depurar, y ocurre con frecuencia con las herramientas genéricas de traducción de IA.

WordPress lee archivos binarios .mo, que se compilan a partir de archivos de texto .po. Si tu archivo .po contiene errores de sintaxis, el archivo .mo podría generarse, pero estará "roto" internamente.

¿Cómo sucede esto? Si un traductor (humano o IA) estropea el formato Gettext, la cadena se vuelve inválida.

• Ejemplo: Falta una comilla de cierre ".
• Ejemplo: Romper una variable (cambiando %s a % s).
• Ejemplo: Estropear el conteo de msgid_plural.

Cuando WordPress encuentra una entrada rota en el archivo .mo, a menudo la omite o deja de leer el archivo por completo, volviendo al inglés original.

4. Olvidaste Compilar (.po vs .mo)

WordPress no puede leer archivos .po directamente. Es una idea errónea común.

• .po = Legible por humanos (Portable Object).
• .mo = Legible por máquinas (Machine Object).

Si subes un archivo my-theme-es_ES.po pero olvidas generar el archivo .mo correspondiente, no pasará nada. Debes compilarlo.

5. Caché (El Sospechoso Habitual)

Si estás utilizando plugins de caché (WP Rocket, LiteSpeed) o caché del lado del servidor (Varnish, Redis), tu sitio podría estar sirviendo una versión HTML en caché de antes de que subieras la traducción.

Solución: borra todas las cachés, incluyendo la caché de tu navegador y la caché de objetos.

La Solución Definitiva: Archivos Válidos Desde el Principio

Solucionar problemas de rutas de archivos y nombres es fácil. Solucionar problemas de sintaxis corrupta (Razón #3) es una pesadilla.

Si utilizas una herramienta que rompe tus variables de código o corrompe la estructura Gettext, pasarás horas preguntándote por qué el archivo no funciona, sin darte cuenta de que el archivo en sí está "envenenado".

Esta es la razón por la que construimos SimplePoTranslate.

• Bloqueo de Sintaxis: Nos aseguramos de que cada cadena sea sintácticamente válida antes de que la descargues. Bloqueamos variables como %s para que no puedan romperse.
• Formato Perfecto: Generamos archivos .po limpios y estándar que se compilan en archivos .mo funcionales el 100% de las veces.
• No Se Requieren Plugins: Descargas el archivo y sabes que funciona. Solo necesitas subirlo a la carpeta correcta.
• Plugin de WordPress: ¿Prefieres saltarte la subida manual por completo? Nuestro plugin oficial de SimplePoTranslate para WordPress detecta automáticamente los archivos .pot de tu tema y plugin, los traduce en la nube y despliega el resultado en el directorio correcto con el nombre de archivo correcto. No más archivos mal nombrados, ni rutas de carpetas incorrectas: las dos razones más comunes por las que las traducciones no aparecen.

Deja de adivinar por qué tus traducciones son invisibles. Comienza con un archivo en el que puedas confiar.

¿Listo para traducir sin el dolor de cabeza? Comienza gratis en SimplePoTranslate.com