Internacionalización de WordPress: cómo traducir temas y plugins

Prepare su tema o plugin de WordPress para la traducción. Esta guía abarca los dominios de texto, las funciones gettext, la generación de POT y el mecanismo de carga que pone las traducciones frente a los usuarios. PTC (Private Translation Cloud) traduce después los archivos de recursos y revisa visualmente el tema o plugin renderizado en cada idioma.

Esta guía está dirigida a los desarrolladores que escriben el código. Si ya tiene un archivo POT o PO y solo necesita traducirlo, vaya a la página de archivos PO para conocer el flujo de trabajo de 3 pasos.

Al final de esta guía, su tema o plugin estará:

Internacionalizado correctamente según los estándares de codificación de WordPress.
Traducible por PTC a más de 40 idiomas.
Distribuible mediante los paquetes de idioma de WordPress.org.
Verificable en cada versión con la revisión visual de traducción de PTC.

¿Qué es la internacionalización de WordPress?

La internacionalización (i18n) es el trabajo de preparar su código para que pueda traducirse. La localización (l10n) es el siguiente paso. Produce las cadenas realmente traducidas para idiomas específicos.

Para los temas y plugins de WordPress, i18n significa tres cosas:

Envolver cada cadena visible para el usuario en funciones gettext para que WordPress pueda sustituirlas en tiempo de ejecución.
Definir un dominio de texto que vincule sus traducciones con su proyecto.
Generar un archivo POT con el que trabajan los traductores (o PTC).

Una vez hecho ese trabajo, tiene todo lo necesario para producir archivos traducidos PO, MO, JSON y .l10n.php para cualquier idioma.

PTC traduce archivos POT a MO, JSON y .l10n.php para WordPress

En cualquier flujo de trabajo de traducción de WordPress aparecen cinco extensiones de archivo. PTC traduce de .pot (su origen) a .po, .mo, .json y .l10n.php para cada idioma de destino. Cada formato cumple una función específica:

POT (Portable Object Template). El archivo de origen generado a partir de su código. Enumera cada cadena traducible sin traducciones adjuntas. Este es el que entrega a PTC.
PO (Portable Object). Una copia del POT con traducciones añadidas para un idioma específico. Texto sin formato, legible por humanos. PTC devuelve un PO por cada idioma de destino.
MO (Machine Object). La versión binaria compilada de un PO. WordPress lee archivos MO en tiempo de ejecución porque se cargan más rápido que el texto PO.
JSON. El equivalente en JavaScript de MO. WordPress no puede leer MO desde JavaScript, por lo que la canalización de compilación produce archivos JSON para las cadenas del lado del navegador.
.l10n.php. Una alternativa más reciente a MO, introducida en WordPress 6.5. Se carga más rápido y usa menos memoria. WordPress lo elige automáticamente cuando existe uno junto al archivo MO.

Active .l10n.php para los proyectos nuevos. En las versiones de WordPress compatibles es estrictamente mejor que MO.

Por qué la traducción comunitaria no es suficiente

WordPress.org ofrece traducción comunitaria a través de GlotPress. En la práctica, cubre una pequeña fracción de lo que la mayoría de los plugins y temas necesitan. Un análisis de más de 60.000 plugins y temas de WordPress reveló que la traducción comunitaria cubre menos del 5 % de las necesidades de traducción en 40 idiomas.

Dos problemas estructurales explican esta brecha:

Los voluntarios escasean en la mayoría de los idiomas. Un puñado de plugins con bases de usuarios enormes atrae a traductores. La mayoría no.
Las traducciones pueden tardar meses o años en aparecer, si es que aparecen. Si quiere que los usuarios vean su plugin o tema en su idioma desde el primer día, no puede depender de la comunidad.

Esta guía da por supuesto que usted desea una cobertura de traducción coherente y completa según un calendario de lanzamientos que usted controla. Eso es lo que ofrece PTC.

Cómo preparar su tema o plugin de WordPress para la traducción

Un dominio de texto que no coincide o una cadena sin envolver significa que ese texto nunca aparecerá en su salida traducida. Los detalles importan.

Paso 1: Defina su dominio de texto y la ruta del dominio

Cada tema o plugin necesita un dominio de texto. El dominio de texto es un identificador único que indica a WordPress qué archivos de traducción pertenecen a su proyecto. Debe coincidir exactamente con el slug de su plugin o tema.

Decláralo en la cabecera del archivo principal de su plugin:

<?php
/**
 * Plugin Name: My Plugin
 * Description: An example plugin.
 * Version: 1.0.0
 * Text Domain: my-plugin
 * Domain Path: /languages
 */

O en el style.css de su tema:

/*
Theme Name: My Theme
Text Domain: my-theme
Domain Path: /languages
*/

La ruta del dominio indica a WordPress dónde se encuentran sus archivos de traducción en relación con la raíz del plugin o del tema. /languages es el estándar.

Paso 2: Envuelva sus cadenas PHP en funciones gettext

Cualquier cadena que quiera hacer traducible debe envolverse en una de las funciones gettext de WordPress. En tiempo de ejecución, esas funciones buscan la traducción correcta. Si no se encuentra ninguna, recurren a la cadena original.

Cadenas básicas. Use __() cuando necesite devolver una cadena. Para la salida HTML, use las variantes con escape. Los estándares de codificación de WordPress recomiendan echo esc_html__() en lugar de _e(). La forma con escape hace explícito el escapado de la salida y previene XSS en el punto de salida:

// Return a translated string
$label = __( 'Settings', 'my-plugin' );

// Echo a translated string, escaped for HTML
echo esc_html__( 'Settings saved.', 'my-plugin' );

Cadenas con variables. No concatene variables dentro de las cadenas. Los traductores solo ven fragmentos y no pueden reordenar las palabras para idiomas con una sintaxis diferente. Use printf() o sprintf() con un marcador de posición. Añada un comentario para el traductor para que sepa qué representa %s:

printf(
    /* translators: %s: the user's display name */
    esc_html__( 'Welcome back, %s.', 'my-plugin' ),
    esc_html( $display_name )
);

Formas plurales. Los plurales en inglés son simples (one comment, two comments). Otros idiomas no lo son. Use _n() para gestionar todas las reglas de plural que WordPress conoce:

printf(
    esc_html( _n( '%s comment', '%s comments', $count, 'my-plugin' ) ),
    number_format_i18n( $count )
);

Cadenas que necesitan contexto. Algunas palabras significan cosas distintas según dónde aparezcan. Use _x() para dar a los traductores el contexto que necesitan:

// "Export" as a noun (the file) vs. a verb (the action)
echo esc_html_x( 'Export', 'button label', 'my-plugin' );

Paso 3: Internacionalice sus cadenas de JavaScript

WordPress proporciona el paquete wp-i18n para que pueda usar en JavaScript las mismas funciones gettext que usa en PHP. Al registrar su script, declare wp-i18n como dependencia:

wp_register_script(
    'my-plugin-script',
    plugins_url( 'js/app.js', __FILE__ ),
    array( 'wp-i18n' ),
    '1.0.0',
    true
);

Luego, en su archivo de JavaScript:

const { __, _n, sprintf } = wp.i18n;

const message = __( 'Settings saved.', 'my-plugin' );

Si usa un empaquetador como Webpack, instale @wordpress/babel-plugin-makepot. Extrae las cadenas traducibles de su paquete como parte de su compilación.

Paso 4: Genere su archivo POT

Una vez envueltas sus cadenas, genere un archivo POT. El POT es el archivo de origen con el que trabaja PTC (o cualquier traductor). Contiene cada cadena traducible pero ninguna traducción.

wp i18n make-pot . languages/my-plugin.pot

WP-CLI examina sus archivos PHP, JavaScript y block.json en busca de llamadas gettext. Las compila en un único POT. Si su equipo usa Composer, añada este comando como un script de Composer. Así se mantiene un uso coherente de WP-CLI en todo el equipo sin una instalación global.

El conjunto completo de comandos wp i18n cubre el resto de la canalización:

Comando	Qué hace
`wp i18n make-pot`	Generar un archivo POT a partir del origen.
`wp i18n update-po`	Sincronizar los archivos PO existentes cuando cambia su POT.
`wp i18n make-mo`	Compilar archivos PO en archivos MO binarios.
`wp i18n make-json`	Extraer las cadenas JS de PO en archivos JSON.
`wp i18n make-php`	Generar archivos `.l10n.php` (WordPress 6.5+).

No necesita Poedit. Todo en este flujo de trabajo se ejecuta a través de WP-CLI y PTC. WP-CLI gestiona la generación de POT y la compilación de MO/JSON. PTC gestiona la traducción y devuelve todos los formatos de archivo que WordPress necesita. Poedit es un editor de escritorio útil para la traducción manual, pero no forma parte de este flujo de trabajo.

Traducir archivos POT con PTC

PTC se ha creado pensando en los desarrolladores de WordPress. Empiece con un archivo POT y reciba a cambio archivos de traducción listos para producción. La prueba gratuita de 30 días cubre hasta 20.000 palabras en dos idiomas.

Configure su primer proyecto de traducción

Suba su archivo POT. Elija los formatos de salida que necesite. PTC devuelve cualquier combinación de:

Archivos .po para cada idioma de destino.
Archivos .mo, compilados y listos para distribuir.
Archivos .json para sus cadenas de JavaScript.
Archivos .l10n.php para una carga más rápida en WordPress 6.5+.

El asistente de configuración le pide que describa su tema o plugin. PTC usa la descripción para generar traducciones con el tono y el contexto adecuados. Añada los términos específicos de su marca al glosario en esta etapa. El glosario mantiene los nombres, las etiquetas de funciones y cualquier otra terminología coherentes en todos los idiomas.

PTC analiza la estructura gettext al subir el archivo. Reconoce los marcadores de posición (%s, %1$s, %d), las formas plurales (entradas extraídas con _n() con su cabecera Plural-Forms) y los contextos (entradas _x() con msgctxt). A continuación genera las categorías de plural correctas por idioma. El polaco obtiene one / few / many / other. El japonés obtiene solo other. El árabe obtiene seis formas.

Pase a la localización continua

Una vez traducidos sus primeros archivos, cambie a Pay-As-You-Go. Conecte PTC con su repositorio de GitHub, GitLab o Bitbucket. A partir de ese momento, no sube archivos manualmente:

# .github/workflows/translate.yml
name: PTC translate
on:
  push:
    branches: [main]
    paths:
      - 'languages/my-plugin.pot'
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate POT
        run: |
          wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin
      - name: Trigger PTC translation
        run: |
          curl -X POST https://api.ptc.wpml.org/v1/projects/${{ secrets.PTC_PROJECT_ID }}/sync \
            -H "Authorization: Bearer ${{ secrets.PTC_API_KEY }}"

PTC sincroniza las nuevas cadenas, traduce solo lo que ha cambiado y abre un pull request con los archivos .po, .mo, .json y .l10n.php actualizados. Consulte la referencia de la API de PTC para conocer la API REST y de webhooks completa.

Si confirma los archivos .mo en su repositorio depende de la política de su equipo. Muchos plugins los generan en el momento del lanzamiento. La integración de CI de PTC los produce en cada ejecución de traducción. Confírmelos solo si quiere archivos traducidos en el historial de versiones.

Cargar traducciones en WordPress

Con los archivos traducidos en la mano, colóquelos correctamente e indique a WordPress dónde encontrarlos. El nombre del archivo es lo primero. WordPress busca los archivos de traducción usando un patrón de nomenclatura específico. Un nombre de archivo que no coincida significa que el archivo no se cargará.

Acertar con los nombres de archivo

Los códigos de configuración regional siguen el formato language_COUNTRY. de_DE es alemán (Alemania). fr_FR es francés (Francia). pt_BR es portugués (Brasil). zh_CN es chino simplificado. El portal de traducción de WordPress enumera todas las configuraciones regionales compatibles.

El nombre de archivo esperado depende de dónde coloque el archivo:

Ubicación	Patrón	Ejemplo
Carpeta `/languages/` del plugin	`{text-domain}-{locale}.mo`	`my-plugin-de_DE.mo`
Carpeta `/languages/` del tema	`{locale}.mo`	`de_DE.mo`
Directorio global de idiomas de WordPress (`/wp-content/languages/`)	`{text-domain}-{locale}.mo`	`my-plugin-de_DE.mo`

Los temas usan una convención de nomenclatura más corta cuando los archivos están incluidos dentro del tema. En el directorio global de idiomas, tanto los plugins como los temas usan el patrón {text-domain}-{locale}.

Cargar traducciones para plugins (PHP)

Registre las traducciones en WordPress en el hook init. No use plugins_loaded. Desencadena una advertencia de obsolescencia en las versiones actuales de WordPress:

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

Cargar traducciones para temas (PHP)

Use load_theme_textdomain() enganchado a after_setup_theme:

add_action( 'after_setup_theme', function () {
    load_theme_textdomain( 'my-theme', get_template_directory() . '/languages' );
} );

Cargar traducciones de JavaScript

Después de registrar su script (paso 3 anterior), llame a wp_set_script_translations(). WordPress carga entonces las traducciones JSON para ese identificador de script:

add_action( 'init', function () {
    wp_set_script_translations(
        'my-plugin-script',
        'my-plugin',
        plugin_dir_path( __FILE__ ) . 'languages'
    );
} );

Verificar la carga

Establezca el idioma de su sitio de WordPress en una configuración regional de destino. El ajuste está en Ajustes > Generales > Idioma del sitio.
Vuelva a cargar el frontend y las páginas de administración que renderiza su plugin o tema.
Las cadenas envueltas en __() o esc_html__() deberían aparecer en el nuevo idioma.

Si falta algo, consulte ¿No se muestran las traducciones del plugin de WordPress? Cómo corregir las traducciones que faltan para conocer las causas más comunes.

Idiomas de derecha a izquierda y diseños bidireccionales

El flujo de trabajo de traducción es el mismo para los idiomas de derecha a izquierda (RTL). El árabe, el hebreo, el persa y el urdu usan la misma canalización POT/PO/MO.

El paso adicional consiste en asegurarse de que su tema admite estilos RTL. WordPress carga automáticamente un archivo rtl.css si existe uno en el directorio de su tema. Use la función is_rtl() para aplicar de forma condicional estilos o scripts específicos de RTL.

Localizar fechas, números y monedas

Una cadena traducida no es toda la historia. Las fechas, los números y las monedas también deben seguir la configuración regional del usuario. Use las funciones de formato integradas de WordPress en lugar de las nativas de PHP:

date_i18n() formatea las fechas según la configuración regional activa.
number_format_i18n() formatea los números con separadores de decimales y de miles según la configuración regional.

Estas funciones no forman parte del flujo de trabajo de archivos de traducción. Importan para una experiencia completamente localizada.

Internacionalizar bloques del editor de bloques (Gutenberg)

Los bloques añaden dos pasos adicionales a la canalización estándar:

Las traducciones de JavaScript necesitan un archivo .json por configuración regional. Genérelo a partir del .po con wp i18n make-json.
El script del editor del bloque necesita wp_set_script_translations() en PHP. Eso indica a WordPress que sirva el JSON al bloque.

La salida renderizada por el bloque en el frontend usa las mismas llamadas __() que el resto de su PHP. Ahí no hay trabajo adicional.

Traducir su README y su ficha de WordPress.org

Su readme.txt no es un archivo de recursos. WP-CLI no lo tiene en cuenta al generar un POT. Para traducirlo, use la función Paste to Translate de PTC. Pegue el contenido, elija sus idiomas de destino y descargue el resultado. Los correos electrónicos dirigidos a los clientes que se envían desde el plugin y la descripción de la página del plugin en WordPress.org se traducen del mismo modo, todo en el mismo proyecto para que la terminología se mantenga coherente.

Si su plugin o tema aparece en WordPress.org, la descripción traducida aparece en la pestaña Detalles del plugin en el idioma del usuario. Para publicar las traducciones allí, siga el proceso de importación de WordPress.org.

Traducir el contenido de usuario del plugin con la API de PTC

Los plugins que almacenan datos generados por los usuarios (plugins de foros, plugins de reseñas, plugins de comentarios) pueden traducir ese contenido a medida que llega. La API REST de PTC traduce las publicaciones, los comentarios y las reseñas de los usuarios bajo demanda con autenticación mediante token Bearer, usando el mismo glosario y la misma voz de marca que sus archivos .po.

Revisión visual de traducción de su tema o plugin renderizado - publique sin QA manual por idioma

Un archivo .po traducido es necesario, pero no suficiente. El tema o plugin traducido todavía necesita verificación:

Una etiqueta traducida puede desbordar un botón de una página de ajustes en alemán.
«Submit» puede traducirse como sustantivo en francés cuando la acción de administración necesitaba un verbo.
Una cadena en inglés codificada de forma fija fuera de __() se renderizará sin traducir, sin importar cuántos idiomas distribuya.

La revisión visual de traducción de PTC sustituye la pasada de QA manual. Los temas y plugins de WordPress se renderizan en el navegador (tanto wp-admin como el frontend). La variante adecuada es la extensión de navegador.

Instálela una vez. Grabe un recorrido de su tema o plugin en un sitio de prueba. Cubra las páginas de ajustes, las acciones de administración y la salida del frontend. PTC reproduce la grabación en cada idioma de destino después de cada actualización de traducción. Captura cada pantalla e informa de dos tipos de correcciones:

Correcciones en los archivos .po cuando PTC los controla. PTC vuelve a traducir un sentido erróneo, elige un sinónimo más corto que cabe en un botón o regenera una forma plural.
Prompts de Cursor o Claude Code cuando el problema está en su código PHP o JavaScript. Algunos ejemplos son un envoltorio __() que falta, una cadena en inglés codificada de forma fija o una frase construida por concatenación que debería usar sprintf( __( ... ) ).

Distribuye un plugin multilingüe verificado en cada versión. La cola de QA manual desaparece.

Precios: prueba gratuita de 30 días, después Pay-As-You-Go

La prueba gratuita cubre 20.000 palabras a 2 idiomas sin tarjeta de crédito. Cuando termina la prueba, PTC ofrece Pay-As-You-Go. Sin suscripción. Sin compromiso mínimo. Las primeras 500 palabras de cada mes son gratuitas. Solo paga por el resto. La página de precios tiene una calculadora de costes. Regístrese con un correo electrónico de empresa para obtener una prueba de negocio ampliada.

¿Listo para distribuir un plugin o tema verificado?

PTC genera las traducciones y revisa el plugin renderizado. Usted confirma el resultado y lo lanza. El ciclo completo se ejecuta sin QA manual:

Genere su archivo .pot con wp i18n make-pot.
Súbalo a PTC y reciba a cambio archivos .po, .mo, .l10n.php y .json en minutos.
Instale la extensión de navegador para verificar el plugin en ejecución en cada idioma de destino.

Comience su prueba gratuita de 30 días - 20.000 palabras de regalo, sin tarjeta de crédito.

Relacionado:

Traducir archivos PO en línea con IA - la página canónica de traducción de PO/POT.
GlotPress frente a PTC para la traducción de plugins/temas de WordPress - cuándo elegir la traducción comunitaria frente a PTC.
¿No se muestran las traducciones del plugin de WordPress? Cómo corregir las traducciones que faltan - guía de resolución de problemas.
Cómo importar traducciones de temas y plugins a WordPress.org - proceso CLPTE y una alternativa más rápida.
Referencia de la API de PTC - endpoints REST para la integración de CI.