Cómo añadir traducciones JS para el editor de Gutenberg

Al generar textos para el editor de Gutenberg, necesitamos seguir una serie de pasos para poder crear traducciones adecuadas. Lo que antes era un clásico metabox ahora se ha convertido en un panel de Gutenberg, que también requiere textos traducidos. A continuación, detallo los pasos para incluir las traducciones en el área de administración de WordPress, específicamente para las secciones en JavaScript.

El proceso de generación de traducciones sigue siendo el mismo: primero, necesitamos crear un archivo .pot. Luego, traducimos este archivo en archivos .po (utilizando herramientas como PoEdit o poeditor.com). Estos archivos .po se guardarán como archivos .mo, y finalmente generaremos un archivo .json que almacenará las traducciones para la parte del editor de Gutenberg.

Voy a suponer que todas tus cadenas de texto están preparadas para ser traducidas con las funciones pertinentes de WordPress, como por ejemplo __('mi texto a traducir', 'mi-plugin-textdomain'), usando el «text domain» de tu plugin.

Generación del archivo .pot

En primer lugar, vamos a generar un archivo .pot utilizando WP CLI en la línea de comando con wp i18n make-pot

Dentro del plugin, crea un directorio /languages si aún no lo tienes, y dentro de este, otro directorio /js para almacenar los archivos .json más adelante y mantener todo organizado.

Abre tu terminal, asegúrate de que los comandos se ejecuten desde la raíz de tu plugin, y ejecuta el siguiente comando:

wp i18n make-pot . languages/mi-plugin.pot --slug=mi-plugin --domain=mi-plugin-textdomain --exclude=node_modules,dist,vendor

Te recomiendo que añadas esta línea de comando a tu package.json en caso de tener uno, y así solo tener que hacer algo como npm run make-pot

1
2
3
4
5
"scripts": {
    .....
    "make-pot": "wp i18n make-pot ./ ./languages/mi-plugin.pot --domain=mi-plugin-textdomain --exclude=node_modules,vendor,dist"
    .....
}

Generación del los archivos .po y .mo

Ya tenemos nuestro archivo .pot que subiremos a poeditor.com para generar los .po. Utilizaré poeditor.com porque nos permite aprovechar servicios de traducción automática como como Google Translate o DeepL.

En poeditor, importaremos el archivo .pot que hemos generado en el paso anterior, seleccionaremos las opciones necesarias para la traducción automática y, finalmente, exportaremos ambos archivos, .po y .mo.
Después de descargarlos, los renombraremos siguiendo las convenciones de WordPress: el slug del plugin más el locale (slug-plugin-locale.po). Por ejemplo, si hemos traducido de inglés a español, los archivos serían:
mi-plugin-es_ES.mo y mi-plugin-es_ES.po

Luego, moveremos estos archivos a /wp-content/languages/plugins.

En este punto, ya puedes incluir las traducciones en tu plugin utilizando load_plugin_textdomain. Sin embargo, para traducir los textos en JavaScript y bloques de Gutenberg, queda un paso más por realizar.

1
2
3
4
5
6
add_action( 'init', 'i18n' );

function i18n() {
    // Load text domain and plugin text domain.
    load_plugin_textdomain( 'mi-plugin-textdomain' );
}

Generación del los archivos .json

Esta es la última parte para poder añadir traducciones al JavaScript y bloques de Gutenberg. Para ello, añadiremos la librería po2json en nuestro archivo package.json bajo devDependencies.

{
  "devDependencies": {
    "po2json": "^1.0.0"
  }
}

Luego, en la línea de comando, ejecutaremos un bucle para generar un archivo .json por cada archivo .po existente en languages/plugins que comience con el nombre de nuestro plugin. Estos archivos se almacenarán en el directorio que creamos al principio: /languages/js. La convención para nombrar estos archivos es:
{text-domain}-{locale}-{script-handle}.json

for file in ../../languages/plugins/mi-plugin*.po; do po2json \"$file\" \"languages/js/$(basename \"$file\" .po)-mi_plugin_admin.json\" -f jed1.x; done

Añadiremos también el script a package.json

1
2
3
4
5
6
"scripts": {
  ....
    "make-json": "wp i18n make-pot ./ ./languages/mi-plugin.pot --domain=mi-plugin-textdomain --exclude=node_modules,vendor,dist",
    "make-json": "for file in ../../languages/plugins/mi-plugin*.po; do po2json \"$file\" \"languages/js/$(basename \"$file\" .po)-mi_plugin_admin.json\" -f jed1.x; done"
  ....
}

Por último, en el plugin añadiremos la llamada a wp_set_script_translations para establecer las traducciones para el JS en el admin y bloques Gutenberg.
Recuerda que el handle debe de ser el mismo que el utilizado para enqueue los scripts del admin con wp_enqueue_script

1
2
3
4
5
6
7
8
9
add_action( 'admin_enqueue_scripts', 'script_translations' );

function script_translations() { 
     wp_set_script_translations(
           'mi_plugin_admin',
           'mi-plugin-textdomain',
            plugin_dir_path( __FILE__ ) . 'languages/js' 
     );
}

¡Y eso es todo! Siguiendo estos sencillos pasos al pie de la letra, no deberías tener problemas para añadir traducciones a tu plugin para el JavaScript.