Cómo solucionar las traducciones 'fuzzy' en los archivos .po de WordPress

Tradujiste todas las cadenas. Guardaste el archivo, subiste el .mo y actualizaste tu sitio. Y, sin embargo, un puñado de etiquetas siguen obstinadamente en inglés. Abres el archivo .po, encuentras la cadena y ahí está, perfectamente traducida. Entonces, ¿por qué WordPress la ignora?

La respuesta es casi siempre un pequeño indicador escondido encima de la entrada: #, fuzzy. Una traducción 'fuzzy' es la forma en que gettext dice "esta traducción podría estar mal, así que no confíes en ella todavía". Y, fundamentalmente, WordPress se niega a mostrar cadenas 'fuzzy' en el sitio en vivo, recurriendo en su lugar al inglés original. Esta es una de las causas más incomprendidas del problema de "mi traducción no aparece".

Esta guía explica exactamente qué significa el indicador de traducción 'fuzzy', por qué sigue apareciendo en tus catálogos y cómo encontrar y limpiar cadenas 'fuzzy' en Poedit, en la línea de comandos y a escala en todo un 'backlog'. Una vez que entiendes el mecanismo, el misterio de las traducciones que faltan desaparece.

¿Qué significa realmente el indicador 'fuzzy'?

El indicador 'fuzzy' es un marcador que gettext añade a una entrada de traducción para indicar que la traducción es incierta y necesita revisión humana. En el archivo .po sin procesar, aparece como un comentario especial directamente encima de la cadena.

#: includes/cart.php:88
#, fuzzy
msgid "Add to cart"
msgstr "Im Warenkorb"

Esa línea #, fuzzy le dice a cada herramienta compatible con gettext, incluido WordPress, que el msgstr debajo es provisional. La traducción existe, pero gettext no la considera confirmada.

Por qué WordPress ignora las cadenas 'fuzzy'

Aquí está el comportamiento que toma a todos por sorpresa. Cuando WordPress compila o lee un archivo .mo, trata las entradas 'fuzzy' como no traducidas. La cadena está técnicamente presente en el archivo, pero WordPress la ignora deliberadamente y muestra el msgid original en su lugar.

Así que, desde tu perspectiva, la traducción está "hecha", está ahí mismo en el archivo. Pero desde la perspectiva de WordPress, esa cadena no tiene una traducción confiable, por lo que renderiza la fuente en inglés. Esta es precisamente la razón por la cual un catálogo de aspecto terminado aún puede mostrar texto sin traducir en el 'front end'.

Este diseño es intencional y, para ser justos, sensato. El objetivo principal del indicador 'fuzzy' es evitar que las traducciones no verificadas, potencialmente incorrectas, se publiquen silenciosamente. Imagina una cadena que originalmente decía "Delete account" (Eliminar cuenta) y que luego se cambió a "Deactivate account" (Desactivar cuenta). Si gettext mantuviera ciegamente la traducción antigua, tus usuarios podrían ver un botón etiquetado como "Delete account" que en realidad solo desactiva, un desajuste peligroso. Al ocultar las cadenas 'fuzzy', gettext obliga a un humano a confirmar que la traducción aún coincide con el nuevo significado antes de que llegue a nadie. El indicador es un mecanismo de seguridad, no un error.

¿Por qué siguen apareciendo los indicadores 'fuzzy'?

Los indicadores 'fuzzy' no son aleatorios. Son generados automáticamente por las herramientas de gettext en dos situaciones principales, y entender ambas te dice cómo prevenirlas.

La cadena fuente cambió

La causa más común es una actualización de la fuente. Imagina que el desarrollador cambia una cadena en la siguiente versión del plugin de "Add to cart" (Añadir al carrito) a "Add to basket" (Añadir a la cesta). Cuando fusionas la nueva plantilla con tu traducción existente, gettext ve que la fuente ya no coincide con lo que tradujiste originalmente. En lugar de descartar tu traducción antigua, la mantiene pero la marca como 'fuzzy', diciendo esencialmente: "el inglés cambió, así que por favor verifica si tu traducción sigue siendo adecuada".

Coincidencia automática por memoria de traducción y msgmerge

La segunda causa es la coincidencia 'fuzzy' durante una fusión. La herramienta msgmerge actualiza un archivo de traducción antiguo con una nueva plantilla, y cuando encuentra una cadena fuente que es similar pero no idéntica a una anterior, copia la traducción antigua y la marca como 'fuzzy'.

# Merge a new template into an existing translation.
# Similar-but-changed strings get marked #, fuzzy automatically.
msgmerge --update awesome-plugin-de_DE.po awesome-plugin.pot

La Memoria de Traducción en los editores de escritorio se comporta de la misma manera: cuando rellena automáticamente una sugerencia de una coincidencia cercana, marca el resultado como 'fuzzy' para que recuerdes verificarlo. En ambos casos, el indicador está haciendo su trabajo. El problema es que las entradas 'fuzzy' permanecen sin revisar y WordPress las oculta silenciosamente.

Hermosa tercera fuente, más sigilosa, que vale la pena conocer: las herramientas de copiar-pegar e importación masiva. Algunas plataformas de traducción y scripts de importación marcan cada entrada como 'fuzzy' por defecto como medida conservadora, esperando que un humano confirme cada una después. Si importas un catálogo de otro sistema y encuentras que cada cadena está repentinamente 'fuzzy', esta suele ser la razón. Las traducciones pueden estar perfectamente bien, pero hasta que se borren los indicadores, ninguna de ellas aparecerá en tu sitio. Conocer la fuente de los indicadores te dice si realmente necesitas revisar cada entrada o si una limpieza masiva con confianza es segura.

¿Cómo encontrar y corregir cadenas 'fuzzy'?

Limpiar cadenas 'fuzzy' significa revisar cada una y, una vez que confirmas que la traducción es correcta, eliminar el indicador. Hay tres formas prácticas de hacer esto dependiendo del tamaño de la tarea.

Corrección de cadenas 'fuzzy' en Poedit

Poedit lo hace más fácil. Abre el archivo .po y usa los controles de búsqueda y filtro para mostrar solo las entradas 'fuzzy'; están codificadas por colores (normalmente naranja) para que destaquen inmediatamente. Haz clic en cada una, confirma o corrige la traducción, luego desactiva el estado 'fuzzy' con el atajo de teclado (Editar y luego "La traducción es 'Fuzzy'", o el atajo que se muestra en el menú). Cuando guardes, Poedit recompilará un .mo limpio y las cadenas ahora confirmadas se mostrarán en tu sitio. Si eres nuevo en ese editor, la guía completa de Poedit cubre el flujo de trabajo de filtro y revisión en detalle.

Corrección de cadenas 'fuzzy' en la línea de comandos

Para la automatización o catálogos grandes, la línea de comandos es más rápida. Puedes contar las entradas 'fuzzy' y, una vez que las hayas verificado en bloque, eliminar los indicadores para que WordPress las cargue.

# Count how many fuzzy strings remain
msgattrib --only-fuzzy --no-obsolete awesome-plugin-de_DE.po | grep -c "msgid"

# Clear all fuzzy flags (only after you trust the translations)
msgattrib --clear-fuzzy --empty awesome-plugin-de_DE.po \
  --output-file=awesome-plugin-de_DE.po

Ten cuidado con la limpieza masiva. Eliminar los indicadores 'fuzzy' sin revisar las traducciones anula el propósito del indicador y puede enviar texto realmente incorrecto a tus usuarios. Usa el enfoque de línea de comandos cuando confías en la fuente de las traducciones, y la ruta manual de Poedit cuando no.

Un término medio seguro es exportar las cadenas 'fuzzy' a un archivo separado, revisar solo esas y luego fusionarlas de nuevo. Esto mantiene tus traducciones confirmadas intactas mientras te concentras solo en las entradas que realmente necesitan atención.

# Extract only the fuzzy entries for focused review
msgattrib --only-fuzzy --no-obsolete awesome-plugin-de_DE.po \
  --output-file=fuzzy-only.po

Revisar cincuenta cadenas aisladas es mucho menos propenso a errores que desplazarse por un catálogo de mil líneas buscando filas naranjas, y te proporciona un registro limpio de exactamente lo que cambió en la última actualización.

Después de borrar los indicadores, siempre vuelve a guardar o recompila el archivo .mo. El estado 'fuzzy' reside en el .po, pero WordPress lee el binario .mo, así que hasta que lo regeneres, tu 'front end' seguirá mostrando inglés aunque el .po parezca limpio. Poedit recompila automáticamente al guardar; en la línea de comandos ejecutas msgfmt awesome-plugin-de_DE.po -o awesome-plugin-de_DE.mo. Olvidar este paso de compilación final es una de las razones más comunes por las que un catálogo recién 'des-fuzzificado' todavía no aparece: la traducción está confirmada en el archivo fuente, pero el binario que el sitio realmente carga está obsoleto.

Ten en cuenta que las entradas 'fuzzy' a menudo aparecen junto con cadenas plurales, donde un msgid_plural cambiado puede marcar todo el bloque plural como 'fuzzy'. Si tu 'backlog' de 'fuzzy' tiene muchas entradas de recuentos y cantidades, nuestra guía sobre Plurales de Gettext y pluralización compleja explica por qué esas entradas son especialmente frágiles durante las fusiones.

Eliminación masiva del 'backlog' de 'fuzzy'

Una sola cadena 'fuzzy' se corrige en treinta segundos. Un catálogo con cuatrocientas cadenas 'fuzzy' después de una actualización importante de un plugin es un problema diferente, y en una docena de idiomas se convierte en un verdadero cuello de botella. La tentación de eliminar masivamente los indicadores sin revisión es precisamente cómo las traducciones defectuosas llegan a producción.

Una solución más limpia es volver a traducir las entradas 'fuzzy' desde cero en lugar de simplemente aprobar coincidencias obsoletas. Cuando procesas un catálogo a través de SimplePoTranslate, la IA sensible al contexto produce una traducción actual y confirmada para cada cadena modificada, por lo que no solo estás eliminando un indicador de advertencia, sino que estás reemplazando coincidencias inciertas con traducciones reales. El Bloqueo de Sintaxis mantiene intactos todos los %s, %1$s, {count} y las etiquetas HTML durante el proceso, y el Procesamiento por Lotes Inteligente gestiona grandes catálogos post-actualización de una sola vez. Obtienes un ZIP limpio con .po, .mo, .json, .php y .xliff, sin 'backlog' de 'fuzzy' persistente, listo para implementar desde la nube.

Vale la pena distinguir esto de la pregunta más amplia de por qué las traducciones no aparecen en absoluto. Los indicadores 'fuzzy' son una causa específica, pero la falta de archivos .mo, nombres de archivo incorrectos y desajustes de idioma local (locale) causan el mismo síntoma. Para la lista de verificación de diagnóstico completa, consulta nuestra guía de solución de problemas para traducciones que no aparecen en WordPress, que trata las cadenas 'fuzzy' como un elemento de una lista más grande.

¿Listo para limpiar todo un 'backlog' de 'fuzzy' y hacer que cada cadena aparezca en tu sitio? Prueba SimplePoTranslate gratis — no se requiere tarjeta de crédito. El nivel gratuito vuelve a traducir tu archivo .po desde cero, reemplazando las coincidencias 'fuzzy' inciertas con traducciones limpias y confirmadas.