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

Prepare su tema o plugin de WordPress para su traducción. Esta guía cubre los dominios de texto, las funciones gettext, la generación de archivos POT y el mecanismo de carga que muestra las traducciones a los usuarios. A continuación, PTC (Private Translation Cloud) traduce los archivos de recursos y realiza una revisión visual de la traducción del 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, diríjase 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.
Listo para que PTC lo traduzca a 40+ idiomas.
Listo para su distribución a través de los paquetes de idiomas de WordPress.org.
Verificable en cada lanzamiento con la revisión visual de la 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 ser traducido. La localización (l10n) es el siguiente paso. Esta produce las cadenas traducidas reales para idiomas específicos.

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

Envolver cada cadena orientada al usuario en funciones gettext para que WordPress pueda intercambiarlas en tiempo de ejecución.
Definir un dominio de texto que vincule sus traducciones a su proyecto.
Generar un archivo POT a partir del cual trabajen los traductores (o PTC).

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

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

Cinco extensiones de archivo aparecen en cualquier flujo de trabajo de traducción de WordPress. PTC traduce desde .pot (su origen) a .po, .mo, .json y .l10n.php para cada idioma de destino. Cada formato tiene 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. Usted se lo entrega a PTC.
PO (Portable Object). Una copia del POT con las 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 los archivos MO en tiempo de ejecución porque se cargan más rápido que el texto de un PO.
JSON. El equivalente de MO en JavaScript. WordPress no puede leer archivos MO desde JavaScript, por lo que el pipeline 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.

Habilite .l10n.php para los proyectos nuevos. Es estrictamente mejor que MO en las versiones de WordPress compatibles.

Por qué la traducción de la comunidad no es suficiente

WordPress.org ofrece traducción de la comunidad a través de GlotPress. En la práctica, cubre una pequeña fracción de lo que necesitan la mayoría de los plugins y temas. Un análisis de más de 60.000 plugins y temas de WordPress reveló que la traducción de la comunidad 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 locales. Un puñado de plugins con bases de usuarios masivas atraen a los traductores. La mayoría no lo hace.
Las traducciones pueden tardar meses o años en aparecer, si es que lo hacen. Si desea 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 asume que usted desea una cobertura de traducción completa y coherente en un calendario de lanzamientos que usted controla. Eso es lo que ofrece PTC.

Preparación de su tema o plugin de WordPress para la traducción

Un dominio de texto que no coincida o una cadena sin envolver significa que ese texto nunca aparecerá en su resultado traducido. 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árelo en el encabezado 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 tema. /languages es el estándar.

Paso 2: Envuelva sus cadenas PHP en funciones gettext

Cualquier cadena que desee que sea traducible debe estar envuelta 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 escapadas. Los estándares de codificación de WordPress recomiendan echo esc_html__() en lugar de _e(). La forma escapada hace explícito el escapado de la salida y previene el 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 en las cadenas. Los traductores solo ven fragmentos y no pueden reordenar las palabras para idiomas con sintaxis diferente. Use printf() o sprintf() con un marcador de posición. Añada un comentario para el traductor de modo que los traductores sepan 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 sencillos (one comment, two comments). En otros idiomas no lo son. Use _n() para procesar cada regla 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 diferentes dependiendo de 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 JavaScript:

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

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

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

Paso 4: Genere su archivo POT

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

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

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

La suite completa de comandos wp i18n cubre el resto del pipeline:

Comando	Qué hace
`wp i18n make-pot`	Genera un archivo POT a partir del origen.
`wp i18n update-po`	Sincroniza los archivos PO existentes cuando su POT cambia.
`wp i18n make-mo`	Compila los archivos PO en archivos MO binarios.
`wp i18n make-json`	Extrae las cadenas JS del PO en archivos JSON.
`wp i18n make-php`	Genera 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 se encarga de la generación del POT y la compilación de MO/JSON. PTC se encarga de 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.

Traducción de archivos POT con PTC

PTC está creado pensando en los desarrolladores de WordPress. Comience con un archivo POT y obtenga archivos de traducción listos para producción. La prueba de 30 días cubre hasta 20.000 palabras en dos idiomas.

Configure su primer proyecto de traducción

Suba su archivo POT. Elija qué formatos de salida necesita. PTC devuelve cualquier combinación de:

Archivos .po para cada idioma de destino.
Archivos .mo, compilados y listos para publicar.
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 contexto adecuados. Añada términos específicos de la marca al glosario en esta etapa. El glosario mantiene los nombres, las etiquetas de las 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 encabezado 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 que sus primeros archivos estén traducidos, actualice al pago al consumo. Conecte PTC a su repositorio de GitHub, GitLab o Bitbucket. A partir de ese momento, no subirá archivos manualmente:

# .github/workflows/translate.yml
name: Regenerate POT for PTC
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: Translate with PTC
        run: |
          cat > .ptc-config.yml <<'EOF'
          source_locale: en
          files:
            - file: languages/my-plugin.pot
              output: languages/my-plugin-{{lang}}.po
              additional_translation_files:
                - type: mo
                  path: languages/my-plugin-{{lang}}.mo
          EOF
          curl -fsSL https://raw.githubusercontent.com/OnTheGoSystems/ptc-cli/main/ptc-cli.sh -o ptc-cli.sh
          chmod +x ptc-cli.sh
          ./ptc-cli.sh --config-file .ptc-config.yml --api-token="${{ secrets.PTC_API_TOKEN }}"

Tiene dos formas de automatizar esto. Con la integración con Git, PTC vigila su repositorio y abre un merge request con las traducciones actualizadas cada vez que cambia el archivo de origen. Para ejecutar la traducción dentro de su propio trabajo de CI, use la CLI de PTC: esta sube el archivo modificado, espera a que termine la traducción y descarga los archivos traducidos. Las plantillas de flujo de trabajo listas para usar para GitHub Actions, GitLab CI y Bitbucket Pipelines se encuentran en la guía de configuración del pipeline de CI/CD.

Cualquiera de los dos flujos entrega un merge request o una descarga con los archivos .po, .mo, .json y .l10n.php actualizados. Consulte la referencia de la API de PTC para ver los webhooks y la API REST completos.

Si hace un commit de los archivos .mo en su repositorio depende de la política del 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. Añádalos al repositorio solo si desea tener los archivos traducidos en el historial de versiones.

Carga de traducciones en WordPress

Con los archivos traducidos en 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á.

Cómo nombrar correctamente sus archivos

Los códigos de idioma 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 todos los locales 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 se incluyen dentro del tema. En el directorio global de idiomas, tanto los plugins como los temas usan el patrón {text-domain}-{locale}.

Carga de traducciones para plugins (PHP)

Registre las traducciones en WordPress en el hook init. No use plugins_loaded. Esto 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/'
    );
} );

Carga de traducciones para temas (PHP)

Use load_theme_textdomain() asociado al hook after_setup_theme:

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

Carga de traducciones de JavaScript

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

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

Verifique la carga

Establezca el idioma de su sitio de WordPress en un idioma de destino. El ajuste se encuentra en Ajustes > Generales > Idioma del sitio.
Vuelva a cargar el front end 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? Solucione 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 el mismo pipeline de POT/PO/MO.

El paso adicional es asegurarse de que su tema sea compatible con los 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 para RTL.

Localización de 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 el idioma del usuario. Use las funciones de formato integradas de WordPress en lugar de las nativas de PHP:

date_i18n() formatea las fechas según el idioma activo.
number_format_i18n() formatea los números con separadores de miles y decimales adaptados al idioma.

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

Internacionalización de los bloques del editor de bloques (Gutenberg)

Los bloques añaden dos pasos adicionales al pipeline estándar:

Las traducciones de JavaScript necesitan un archivo .json por idioma. 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 front end usa las mismas llamadas __() que el resto de su PHP. No hay trabajo adicional ahí.

Traducción de su README y de la ficha de WordPress.org

Su readme.txt no es un archivo de recursos. WP-CLI no lo incluirá 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 orientados al cliente enviados desde el plugin y la descripción de la página del plugin en WordPress.org se traducen de la misma manera, todo en el mismo proyecto para que la terminología se mantenga coherente.

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

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

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

Revisión visual de la traducción de su tema o plugin renderizado: publique sin control de calidad manual por idioma

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

Una etiqueta traducida puede desbordar un botón de la página de configuración en alemán.
“Submit” puede traducirse como un sustantivo en francés cuando la acción de administración necesitaba un verbo.
Una cadena hardcoded en inglés fuera de __() se renderizará sin traducir sin importar cuántos idiomas publique.

La revisión visual de la traducción de PTC reemplaza la pasada de control de calidad manual (QA). Los temas y plugins de WordPress se renderizan en el navegador (tanto wp-admin como el front end). 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 configuración, las acciones de administración y la salida del front end. PTC vuelve a ejecutar la grabación en cada idioma de destino después de cada actualización de la traducción. Captura cada pantalla y reporta dos tipos de correcciones:

Correcciones en los archivos .po cuando PTC los controla. PTC vuelve a traducir una acepción incorrecta, elige un sinónimo más corto que encaje en un botón o regenera una forma plural.
Prompts de Cursor o Claude Code cuando el problema se encuentra en su código PHP o JavaScript. Los ejemplos incluyen un wrapper __() que falta, una cadena hardcoded en inglés o una oración construida por concatenación que debería usar sprintf( __( ... ) ).

Usted publica un plugin multilingüe y verificado en cada lanzamiento. El trabajo residual de control de calidad manual desaparece.

Precios: prueba de 30 días, luego pago al consumo

La prueba cubre 20.000 palabras en 2 idiomas sin tarjeta de crédito. Cuando termina la prueba, PTC ofrece el pago al consumo. 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 ampliada para empresas.

¿Listo para publicar un plugin o tema verificado?

PTC genera las traducciones y revisa el plugin renderizado. Usted confirma el resultado y lo publica. El ciclo completo se ejecuta sin control de calidad manual (QA):

Genere su archivo .pot con wp i18n make-pot.
Súbalo a PTC y reciba de vuelta 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 de 30 días: 20.000 palabras por nuestra cuenta, sin necesidad de tarjeta de crédito.

Relacionado:

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