Por qué sus traducciones no aparecen en WordPress (Guía de solución de problemas)

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

Hizo todo bien. Tradujo el archivo .po. Lo compiló en un archivo .mo. Lo subió a su servidor a través de FTP. Borró su caché.

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

Sin mensaje de error, sin pantalla blanca, solo texto obstinado y sin traducir. Antes de arrancarse el pelo, lea 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á Nombrando Mal el Archivo

WordPress es increíblemente estricto con la nomenclatura de archivos. Si le falta un carácter, no cargará el archivo.

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

• El Dominio de Texto (Text Domain): Esta es la identificación única del tema o complemento (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).

Errores Comunes:

• Nombrar el archivo solo es_ES.mo (Esto solo funciona para archivos globales del núcleo de WordPress, no para complementos).
• Usar el guion incorrecto: my_plugin_es_ES.mo (Guion bajo) en lugar de my-plugin-es_ES.mo (Guion).
• Adivinar el dominio de texto. Debe verificar el código del complemento (encabezado style.css o función load_plugin_textdomain) para encontrar el slug exacto.

2. Puso el Archivo en la Carpeta Incorrecta

Dónde sube el archivo importa tanto como cómo lo nombra. 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 es seguro contra actualizaciones de complementos.
  • Contras: Debe nombrar el archivo textdomain-locale.mo.
• La Carpeta del Autor: /wp-content/plugins/plugin-name/languages/.
  • Pros: Fácil de encontrar.
  • Contras: PELIGRO. Cuando actualiza el complemento, esta carpeta se borra. Sus traducciones desaparecerán.

Mejor Práctica: Ponga siempre sus 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 sucede con frecuencia con herramientas de traducción de IA genéricas.

WordPress lee archivos binarios .mo, que se compilan a partir de archivos de texto .po. Si su 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) arruina el formato Gettext, la cadena se vuelve inválida.

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

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

4. Olvidó Compilar (.po vs .mo)

WordPress no puede leer archivos .po directamente. Es un concepto erróneo común.

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

Si sube un archivo my-theme-es_ES.po pero olvida generar el archivo .mo correspondiente, no pasará nada. Debe compilarlo.

5. Caché (El Sospechoso Habitual)

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

Solución: borre todos los cachés, incluido el caché de su navegador y el caché de objetos.

La Solución Definitiva: Archivos Válidos desde el Inicio

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

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

Es por eso que construimos SimplePoTranslate.

• Bloqueo de Sintaxis: Nos aseguramos de que cada cadena sea sintácticamente válida antes de que la descargue. Bloqueamos variables como %s para que no se puedan romper.
• Formato Perfecto: Generamos archivos .po limpios y estándar que se compilan en archivos .mo que funcionan el 100% del tiempo.
• No Requiere Complementos: Descarga el archivo y sabe que funciona. Solo necesita subirlo a la carpeta correcta.

Deje de adivinar por qué sus traducciones son invisibles. Comience con un archivo en el que pueda confiar.

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