Cómo Traducir un Plugin de WordPress (Paso a Paso)

Encontraste el plugin de WordPress perfecto para tu proyecto. Hace exactamente lo que necesitas, las reseñas son excelentes, y luego lo activas y te das cuenta de que cada botón, etiqueta y mensaje de error está en inglés. Tus visitantes alemanes, franceses o japoneses están a punto de encontrarse con una pared de texto que no pueden leer.

La buena noticia es que la mayoría de los plugins bien construidos están listos para la traducción, lo que significa que el desarrollador envolvió sus cadenas en funciones Gettext específicamente para que personas como tú puedan traducirlas. El desafío es saber dónde residen los archivos, cómo nombrar tu traducción y dónde colocarla para que la próxima actualización del plugin no borre tu trabajo.

Esta guía te muestra cómo traducir un plugin de WordPress de principio a fin: encontrando el dominio de texto y la carpeta de idiomas, obteniendo o generando la plantilla .pot, construyendo archivos .po y .mo nombrados correctamente, y colocándolos donde WordPress los cargará de manera confiable. También cubriremos el único tipo de plugin que este enfoque no puede traducir completamente, para que no pierdas horas luchando contra un caso imposible.

¿Cómo Encontrar los Archivos de Traducción de un Plugin?

Antes de traducir cualquier cosa, necesitas dos piezas de información del plugin: su dominio de texto y su carpeta de idiomas. El dominio de texto es la cadena única que el plugin utiliza para identificar sus propias traducciones, y la carpeta de idiomas es donde reside la plantilla fuente.

Localizando la Carpeta de Idiomas y el Dominio de Texto

Abre el directorio del plugin en wp-content/plugins/your-plugin/ y busca una subcarpeta /languages. Dentro, normalmente encontrarás un archivo .pot, la plantilla vacía que contiene cada cadena traducible.

Para confirmar el dominio de texto, abre el archivo PHP principal del plugin y mira su bloque de cabecera:

/**
 * Plugin Name: Awesome Plugin
 * Text Domain: awesome-plugin
 * Domain Path: /languages
 */

Aquí el dominio de texto es awesome-plugin. Este valor es crítico, porque tus archivos de traducción deben incluirlo en sus nombres o WordPress nunca los asociará con el plugin. También lo verás en cada llamada de cadena a lo largo del código:

echo __( 'Settings saved successfully.', 'awesome-plugin' );

Ese segundo argumento, awesome-plugin, es de nuevo el dominio de texto. Cada cadena que lo utiliza puede ser traducida por tu catálogo. Si a una cadena en la interfaz del plugin le falta este envoltorio, por ejemplo, un desarrollador que codificó echo 'Save' sin __(), entonces esa cadena no es traducible en absoluto, y ningún archivo .po puede alcanzarla. La mayoría de los plugins de buena reputación envuelven todo correctamente, pero si notas una o dos cadenas persistentes que se niegan a traducirse, la ausencia de un envoltorio Gettext en el código fuente es un culpable probable.

Una forma rápida de evaluar si un plugin está realmente listo para la traducción es revisar su listado en el directorio de WordPress.org, que muestra un porcentaje de traducción y enlaces a una plantilla /languages. Un plugin con un proyecto de traducción activo es mucho más probable que tenga cadenas limpias y completamente envueltas que uno abandonado.

¿Qué Pasa si el Plugin No Tiene Archivo POT?

Algunos plugins se envían sin una plantilla .pot. Si la carpeta /languages está vacía o falta, necesitas generar la plantilla tú mismo escaneando el código fuente en busca de cadenas traducibles.

La herramienta estándar para esto es WP-CLI, que extrae cada llamada Gettext en un nuevo .pot.

wp i18n make-pot wp-content/plugins/awesome-plugin \
  wp-content/plugins/awesome-plugin/languages/awesome-plugin.pot

Este comando recorre los archivos PHP y JavaScript del plugin, encuentra cada __(), _e(), _n() y llamadas relacionadas, y escribe una plantilla completa. Si prefieres una ruta gráfica, Poedit Pro puede escanear el código fuente de la misma manera. De cualquier manera, el resultado es un .pot que contiene todas las cadenas fuente con traducciones vacías, listo para convertirse en un archivo de idioma real.

Generar tu propia plantilla tiene un beneficio oculto: captura cadenas que el desarrollador original pudo haber olvidado incluir en un .pot enviado. Los plugins evolucionan rápidamente, y una plantilla que venía con la versión 2.1 podría carecer de cadenas añadidas en la 2.4. Regenerar desde la fuente actual garantiza que tu catálogo refleje lo que el plugin realmente muestra hoy, no lo que mostraba hace dos versiones. Si mantienes traducciones para un plugin a lo largo del tiempo, volver a ejecutar make-pot después de cada actualización importante es un hábito confiable.

Creando los Archivos PO y MO con el Nombre Correcto

El error más común al traducir un plugin es el nombre del archivo. WordPress encuentra las traducciones de los plugins haciendo coincidir un patrón muy específico, y un solo carácter incorrecto significa que tu traducción es ignorada por completo.

La Fórmula del Nombre de Archivo

Para las traducciones de plugins, el patrón es text-domain-locale. Así que para el dominio de texto awesome-plugin traducido al alemán, los archivos deben llamarse:

awesome-plugin-de_DE.po
awesome-plugin-de_DE.mo

El código de configuración regional es el código de idioma del sitio de WordPress: de_DE para alemán, fr_FR para francés, es_ES para español, pt_BR para portugués de Brasil. Si el código de configuración regional es incorrecto, WordPress omitirá silenciosamente tu archivo. Creas estos a partir de la plantilla .pot en un editor como Poedit, que compila automáticamente el .mo binario cuando guardas. Si eres nuevo en ese editor, la guía completa de Poedit te guía paso a paso a través de la creación de una traducción a partir de una plantilla.

Dónde Colocar los Archivos Para que las Actualizaciones No los Borren

Hay dos ubicaciones posibles, y elegir la correcta importa.

# RISKY: inside the plugin — wiped on every plugin update
wp-content/plugins/awesome-plugin/languages/awesome-plugin-de_DE.mo

# SAFE: the global languages override folder — survives updates
wp-content/languages/plugins/awesome-plugin-de_DE.mo

Usa siempre wp-content/languages/plugins/. WordPress verifica este directorio de anulación primero, y como se encuentra fuera de la carpeta del plugin, la actualización del plugin nunca afectará tus traducciones. Los archivos colocados dentro de la propia carpeta del plugin se sobrescriben en el momento en que se instala una nueva versión.

Este comportamiento de anulación es una de las características más útiles y menos conocidas de la localización de WordPress. Significa que puedes entregar traducciones personalizadas o corregidas para cualquier plugin de terceros sin tener que bifurcarlo, y tus cambios están completamente protegidos ante actualizaciones. Si administras varios sitios de clientes que usan el mismo plugin, incluso puedes mantener un único conjunto de archivos .mo de anulación e implementarlos en todos ellos, sabiendo que cada sitio los tomará automáticamente siempre que la configuración regional coincida.

Cómo Carga WordPress Tu Traducción

Un plugin listo para la traducción le indica a WordPress que cargue su catálogo llamando a load_plugin_textdomain() durante la inicialización:

add_action( 'init', function() {
    load_plugin_textdomain(
        'awesome-plugin',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages'
    );
} );

Para la mayoría de los plugins modernos en WordPress 4.6 y posteriores, no necesitas tocar esto. WordPress carga automáticamente las traducciones desde wp-content/languages/plugins/ siempre que el nombre de tu archivo y la configuración regional del sitio coincidan. Si tu traducción terminada aún no aparece, la causa casi siempre es un nombre de archivo incorrecto, un .mo obsoleto o un idioma del sitio configurado en la configuración regional incorrecta. Nuestra guía de solución de problemas para traducciones que no aparecen recorre cada uno de estos puntos de falla.

Plugins que Almacenan Cadenas en la Base de Datos

Aquí está la limitación importante. El enfoque de Gettext solo traduce cadenas que residen en el código del plugin. Algunos plugins, especialmente constructores de formularios, constructores de páginas y extensiones de comercio electrónico, te permiten crear contenido (etiquetas de formulario, atributos de producto, mensajes personalizados) que se guarda en la base de datos de WordPress. Esas cadenas son datos generados por el usuario, no forman parte del .pot, por lo que un archivo .po no puede alcanzarlas. Para el contenido de la base de datos, necesitas un plugin multilingüe como WPML o Polylang, o la propia función de traducción de cadenas del plugin. Siempre prueba si una cadena dada reside en el código o en la base de datos antes de asumir que un archivo .po puede solucionarlo.

Una prueba sencilla te indica con qué tipo de cadena estás tratando. Si el texto es algo que escribiste en un campo de configuración, una etiqueta de formulario que creaste, un mensaje de agradecimiento personalizado, un nombre de producto, es contenido de la base de datos y un .po no puede tocarlo. Si el texto forma parte de la interfaz integrada del plugin, etiquetas de botones, errores de validación, avisos de administración que vienen con el plugin mismo, reside en el código y un archivo .po es la herramienta correcta. Trazar esta línea temprano ahorra horas de frustración, porque por mucha edición perfecta de .po que hagas, nunca traducirás una cadena que el plugin extrae de la base de datos en tiempo de ejecución.

Traducción a Escala sin el Trabajo Manual Exhaustivo

Traducir un plugin a un idioma a mano es manejable. Traducirlo a diez idiomas, o traducir un conjunto completo de plugins para el sitio de un cliente, se convierte en días de trabajo repetitivo, y cada edición manual corre el riesgo de alterar un marcador de posición como %s o %1$s y romper la salida.

Aquí es donde un flujo de trabajo en la nube cambia las reglas. Sube el archivo .po o .pot del plugin a SimplePoTranslate, elige tus idiomas de destino, y la IA consciente del contexto traduce todo el catálogo mientras el Bloqueo de Sintaxis congela cada marcador de posición, etiqueta HTML y token de código para que nada se rompa. El Procesamiento por Lotes Inteligente maneja grandes catálogos en una sola pasada, y descargas un ZIP que contiene .po, .mo, .json, .php y .xliff juntos, formateados correctamente y listos para ser colocados en wp-content/languages/plugins/. Funciona completamente en la nube, por lo que no hay instalación de escritorio ni bloat en tu sitio.

Ten en cuenta que traducir un plugin difiere de traducir un tema, que utiliza una convención de carpetas y una función de carga ligeramente diferentes. Si tu objetivo es un tema, sigue nuestra guía dedicada sobre cómo localizar cualquier tema de WordPress incluso si no eres desarrollador en su lugar.

Usa la ruta manual cuando tengas un plugin y un idioma. Usa la nube cuando necesites muchos idiomas, rápidamente, sin sacrificar la seguridad de los marcadores de posición.

¿Listo para traducir tu plugin de WordPress a todos los idiomas que habla tu audiencia sin romper una sola variable? Prueba SimplePoTranslate gratis — no se requiere tarjeta de crédito. El nivel gratuito te permite traducir tu primer archivo .po de plugin en minutos, con Bloqueo de Sintaxis en cada cadena.