Contents
Internacionalizar bloques de WordPress con @wordpress/i18n (JS) — tutorial completo
Este artículo detalla paso a paso cómo internacionalizar un bloque de Gutenberg usando la librería @wordpress/i18n (JavaScript). Se cubrirán las buenas prácticas, ejemplos de código (editor y PHP de registro), extracción y generación de ficheros de traducción, registro de traducciones para scripts y consejos de resolución de problemas.
Por qué y cómo funciona la internacionalización en bloques
WordPress permite traducir cadenas de texto tanto en PHP como en JavaScript. Para bloques modernos (escritos en ESNext/JSX) se recomienda usar @wordpress/i18n, que exporta funciones equivalentes a las de PHP (por ejemplo __(), _x(), _n(), _nx(), sprintf()). El flujo general es:
- Marcar cadenas en el código JS con las funciones de i18n.
- Extraer esas cadenas a un archivo .pot/.po usando herramientas (WP‑CLI u otras).
- Generar los ficheros de traducción en formato JSON destinados a JS (o .mo para PHP).
- Registrar/poner a disposición esas traducciones en WordPress con wp_set_script_translations o mediante la metadata del bloque y register_block_type.
Funciones clave en @wordpress/i18n
- __() — traducción simple: __(Hello, text-domain)
- _x() — traducción con contexto: _x(Post, noun, text-domain)
- _n() — pluralización: _n(One item, %d items, count, text-domain)
- _nx() — pluralización con contexto.
- sprintf() — formatea cadenas traducidas con placeholders.
Estructura recomendada de archivos
Ejemplo de estructura mínima de un plugin con bloque:
- my-plugin/
- block.json
- src/
- edit.js
- save.js
- build/
- index.js
- index.asset.php
- languages/
- my-plugin-es_ES.json (o PO/MO según flujo)
- my-plugin.php (archivo principal del plugin)
Paso 1 — Marcar cadenas en JavaScript
Importa las funciones desde @wordpress/i18n y úsalas en tu componente. Usa comentarios para traductores cuando sea necesario.
import { __, _n, _x, sprintf } from @wordpress/i18n
import { useBlockProps } from @wordpress/block-editor
export default function Edit( { attributes, setAttributes } ) {
const count = attributes.count 0
// Texto simple
const title = __( Saludo, my-plugin )
/ translators: Nombre del usuario que aparece en el saludo /
const greeting = sprintf( __( Hola %s, my-plugin ), attributes.name Invitado )
// Pluralización
const items = sprintf(
_n( %d elemento, %d elementos, count, my-plugin ),
count
)
return (
{ title }
{ greeting }
{ items }
)
}
Paso 2 — Añadir comentarios para traductores
Cuando una cadena necesita contexto o información adicional para el traductor, añade un comentario justo encima:
/ translators: Esto aparece cuando no hay elementos en la lista / const emptyText = __( No hay elementos, my-plugin )
Paso 3 — block.json y registro del bloque
Declara el bloque en block.json, incluyendo la referencia a editorScript y el textdomain (recomendado para claridad).
{
apiVersion: 2,
name: my-plugin/hello,
title: Bloque Hola,
category: widgets,
textdomain: my-plugin,
editorScript: file:./build/index.js
}
Paso 4 — Registro en PHP y carga de traducciones JS
Registra el script del editor (habitualmente generado por build) y usa wp_set_script_translations para indicar la ubicación de las traducciones JSON/PO. El handle que pases debe coincidir con el handle del script registrado.
Paso 5 — Generar POT / PO / JSON
Ejemplo con WP‑CLI para extraer cadenas y generar JSON para las traducciones JS:
- Generar POT (archivo base):
wp i18n make-pot . languages/my-plugin.pot --exclude=node_modules,build
- Crear archivos PO para cada idioma (puedes usar Poedit o herramientas CLI):
msginit --input=languages/my-plugin.pot --locale=es_ES --output-file=languages/my-plugin-es_ES.po
- Convertir PO a JSON para uso en JavaScript (WordPress dispone de comando make-json):
wp i18n make-json languages languages --domain=my-plugin
Esto generará archivos JSON en languages/ como my-plugin-es_ES.json que WordPress usará con wp_set_script_translations.
Notas sobre la generación de JSON
- El archivo JSON generado contiene las cadenas traducidas en un formato que wp.i18n puede usar en el navegador.
- Si usas herramientas de empaquetado (webpack/@wordpress/scripts), asegúrate de que las rutas de source maps y build no interfieran con la extracción.
Usar wp.i18n global como alternativa
Si tu script no está usando bundler o importaciones ES, puedes usar el global wp.i18n proporcionado por WordPress. Ejemplo:
const { __ } = wp.i18n
function render() {
return document.createElement(div).appendChild(
document.createTextNode( __(Hola mundo, my-plugin) )
)
}
Plurales, contexto y sprintf — ejemplos prácticos
import { __, _n, _x, sprintf } from @wordpress/i18n
// Contexto para la palabra Post (sustantivo o verbo)
const postNoun = _x( Post, noun, my-plugin )
const postVerb = _x( Post, verb, my-plugin )
// Pluralización
const count = 3
const items = sprintf(
_n( %d comentario, %d comentarios, count, my-plugin ),
count
)
Problemas comunes y cómo resolverlos
- No se traducen las cadenas JS: comprueba que el handle pasado a wp_set_script_translations coincide exactamente con el handle del script registrado y que el textdomain es el correcto.
- Ficheros JSON no encontrados: asegúrate de que los JSON están en la carpeta indicada (por ejemplo languages/) y que tienen el nombre correcto (my-plugin-es_ES.json).
- Cadenas extraídas incompletas: verifica que las cadenas en JS están marcadas con funciones de @wordpress/i18n y que la extracción excluye los ficheros build/ si no quieres duplicados.
- Caché de navegador: a veces hace falta limpiar cache o forzar recarga para ver cambios en JSON en el navegador.
- Contexto y comentarios a traductores: siempre añade / translators: … / justo encima de la llamada cuando el significado puede no ser obvio.
Buenas prácticas
- Usa el mismo textdomain en todo el plugin/tema mantenlo en block.json y en las llamadas a __().
- Registra las traducciones con wp_set_script_translations para los scripts que contienen cadenas JS.
- Incluye comentarios para traductores cuando sea necesario y usa _x() para casos de palabras polisémicas.
- Automatiza la extracción y generación de JSON en tu pipeline de CI o scripts NPM.
- Para bloques que muestran texto generado por PHP, también marca las cadenas en PHP con __() y genera PO/MO.
Ejemplo completo resumido
Resumen mínimo de los pasos: marcar cadenas en src/edit.js con __(), construir (wp-scripts build), extraer POT, crear PO, generar JSON, colocar JSON en languages/, usar wp_set_script_translations en PHP y registrar el bloque.
Ejemplo de comando de build y extracción (flujo típico)
# 1. Build JS (con @wordpress/scripts o tu bundler) npm run build # 2. Extraer POT wp i18n make-pot . languages/my-plugin.pot --exclude=node_modules,build # 3. Traducir/editar PO (ej. con Poedit) # 4. Generar JSON para JS wp i18n make-json languages languages --domain=my-plugin
Con todo esto en su sitio, los bloques mostrarán sus cadenas traducidas tanto en el editor como en el front-end (si los scripts están registrados y las traducciones cargadas).
Conclusión
Internacionalizar bloques con @wordpress/i18n es directo: marca las cadenas en JS, extrae y convierte las traducciones a JSON y registra esas traducciones con wp_set_script_translations. Mantén consistente el textdomain, usa comentarios para traductores cuando haga falta y automatiza la extracción/generación para evitar errores manuales. Siguiendo este flujo lograrás que tus bloques sean traducibles y accesibles en cualquier idioma soportado por WordPress.
|
|
Acepto donaciones de BAT's mediante el navegador Brave 🙂 |