Traducciones de JavaScript en Gutenberg

Desde 2007, WordPress ha admitido la traducción de cadenas de texto en PHP. A partir de 2018, ahora tenemos un proceso similar para traducir cadenas en JavaScript. Tradicionalmente, los desarrolladores de WordPress han utilizado la wp_localize_script() función para pasar cadenas traducidas de PHP a JavaScript. Desafortunadamente, este enfoque no se escala bien y hace que el código sea desordenado. Afortunadamente, con los albores de Gutenberg, ahora tenemos la nueva biblioteca npm i18n de WordPress . En el momento de escribir este artículo, es un poco difícil encontrar ejemplos de cómo traducir correctamente las cadenas de JavaScript en WordPress de principio a fin. La mayoría de los ejemplos te darán una pieza del rompecabezas, pero no la imagen completa. Nuestro objetivo hoy es documentar todo el proceso de principio a fin.

Descripción general de la internacionalización y la localización

El proceso de traducción consta de dos etapas: la internacionalización y la localización. Es habitual ver las abreviaturas i18n y l10n cuando se hace referencia a internacionalización y localización. La lógica detrás de esto es que tomas la primera y la última letra de la palabra, cuentas las letras restantes y pones ese número en el medio. En el nivel más básico, la internacionalización es el proceso de preparar un tema o plugin para su traducción. La localización es el proceso de aprovechar esa preparación y realizar la traducción. La internacionalización comienza utilizando las funciones de traducción que proporciona WordPress. Esencialmente, todas estas funciones le permiten proporcionar una cadena de texto para traducir y lo que se denomina un dominio de texto.

Dominio de texto : un espacio de nombres, o identificador único, bajo el cual se administran todas las cadenas traducidas. WordPress utiliza el dominio de texto para diferenciar entre la traducción de tu tema o plugin y la de otro.

Por último, se utiliza una herramienta automatizada para localizar y compilar todas las cadenas de texto con su dominio de texto en un .pot archivo (plantilla de objeto portátil). La localización, el siguiente paso del proceso, comienza cuando se proporciona el archivo a un traductor para que lo .pot traduzca al idioma o idiomas elegidos. El traductor tomará el archivo, traducirá las cadenas y guardará las cadenas traducidas en un .poarchivo (objeto portátil). Sin embargo, WordPress requiere un .mo archivo (objeto de máquina) para traducir dinámicamente el texto a través de código. El último paso es convertir el archivo .po en un .mo archivo. Hay varias formas de hacer esto, pero si usa una herramienta como Poedit , ambos archivos se pueden generar simultáneamente. En este punto, nos hemos preparado para la traducción y tenemos un archivo que permitirá a WordPress traducir las cadenas a través del código. Sin embargo, nada se va a traducir a menos que WordPress sepa qué idioma está en uso y dónde se encuentra el archivo de idioma:

1. Establezca el idioma : puede decirle a WordPress qué idioma desea usar yendo a Configuración > General en el administrador de WordPress y seleccionando el idioma deseado en el menú desplegable Idioma del sitio . Si bien sus usuarios normalmente serían los que harían esto, debe hacer esto para probar a fondo que su traducción está funcionando.
2. Registre su archivo de idioma – WordPress tiene algunas funciones que puede utilizar para registrar su archivo de idioma para que pueda ser encontrado. Si está traduciendo un tema, querrá usar load_theme_textdomain(). Si está traduciendo un complemento, querrá usar load_plugin_textdomain().

Traducción de cadenas de JavaScript

Ahora que tenemos una comprensión clara de cómo funcionan las traducciones en WordPress, echemos un vistazo exactamente a cómo podemos traducir cadenas en JavaScript.

Uso del paquete i18n de WordPress

Comencemos echando un vistazo a una función de traducción en JS:

__( 'Hello World!', 'text-domain' );

Parece familiar, ¿verdad? La API i18n de JavaScript refleja las funciones de traducción que normalmente se utilizan en PHP. La única excepción es que primero debes cargar la biblioteca NPM i18n de WordPress en tu proyecto e importar las funciones necesarias para que estén disponibles. Para hacer esto, comience instalando el módulo npm:

npm install --save @wordpress/i18n

A continuación, importe las funciones que utilizará desde el módulo:

import { __, _n, sprintf } from '@wordpress/i18n';

Nota: Este enfoque utiliza JavaScript ES6. Será necesario ejecutar un proceso de compilación automatizado para convertir el código en JavaScript seguro para el navegador. Recomendamos usar Babel y Webpack para lograr esto.

Generación de un archivo .pot

Tradicionalmente, la generación de un archivo .pot para cadenas en un archivo PHP se ha realizado normalmente utilizando el ejecutor de tareas Grunt y el paquete grunt-wp-i18n. Sin embargo, esta herramienta no analiza los archivos JavaScript. WordPress ha lanzado un paquete NPM llamado babel-plugin-makepot con el propósito específico de generar (o actualizar) automáticamente un archivo .pot a medida que realiza cambios en sus archivos JavaScript. Este plugin de Babel requiere el uso de Babel. Normalmente, Babel está configurado para ejecutarse a través de Webpack. Para hacer esto, comience instalando el módulo npm:

npm install --save-dev @wordpress/babel-plugin-makepot

A continuación, actualiza la configuración de tu cargador de Babel para incluir el plugin makepot:

[ "@wordpress/babel-plugin-makepot", {
	"output": "languages/myplugin.pot"
} ]

Si no está familiarizado con Babel o Webpack, todo esto puede ser confuso. Cuando se aprende algo por primera vez, a menudo es más fácil mirar un ejemplo de trabajo. Tal vez revisar este archivo de webpack.config.js ayude. Una vez que haya configurado este paquete, ejecutará Webpack, que luego observará sus archivos JavaScript en busca de cambios, detectará automáticamente cuándo está utilizando funciones de traducción y generará o mantendrá automáticamente su archivo .pot actualizado en su directorio languages/.

Carga del archivo de traducción

Esencialmente, una vez que hayas pasado por el proceso de convertir tu archivo .pot en un archivo .mo, estarás listo para registrar el archivo de traducción con WordPress de la manera tradicional. En un plugin:

<?php
add_action( 'plugins_loaded', function () {
	load_plugin_textdomain( 'text-domain', plugin_basename( __DIR__ ) . '/languages' );
} );

o en un tema:

<?php
add_action( 'after_setup_theme', function () {
	load_theme_textdomain( 'text-domain', get_template_directory() . '/languages' );
} );

Pasar traducciones a JavaScript

WordPress cargará nuestros archivos .mo a través de PHP, lo cual es suficiente para garantizar que se traduzcan todas las cadenas en PHP. Sin embargo, dado que estamos tratando de traducir cadenas en JavaScript, todavía tenemos un obstáculo más. Necesitamos tomar las traducciones que PHP conoce y pasarlas a nuestro JavaScript en el front-end. Al igual que el antiguo método de usar wp_localize_script() para pasar cadenas traducidas a nuestro JavaScript, debemos asegurarnos de cerrar la brecha entre el back-end y el front-end. Nota: En el momento de escribir este artículo, el código que sigue depende actualmente de que el plugin Gutenberg de WordPress esté instalado y activo en un sitio. Una vez que la nueva experiencia de edición de WordPress de Gutenberg se integre en el núcleo, no habrá una dependencia del complemento, pero algunas de estas funciones pueden tener nombres ligeramente diferentes. Sin embargo, la mayoría de los casos de uso actuales de la traducción de JavaScript se encuentran en el contexto de la creación de bloques de Gutenberg. La biblioteca JavaScript WordPress i18n está actualmente cargada bajo la variable global wp en JavaScript. Esto significa que para acceder a la biblioteca i18n en WordPress, lo harías así: wp.i18n. Lo que queremos hacer es aprovechar la llamada a la API setLocaleData() de la biblioteca i18n de WordPress para registrar nuestra(s) traducción(es):

<?php
add_action( 'wp_enqueue_scripts', function () {
	$suffix = defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ? '' : '.min';
	wp_enqueue_script(
		'my-script-js',
		plugins_url( "/assets/js/script{$suffix}.js", __FILE__ ),
		[ 'wp-i18n' ],
		filemtime( __DIR__ . "/assets/js/script{$suffix}.js" )
	);
	if ( function_exists( 'gutenberg_get_jed_locale_data' ) ) {
		$locale  = gutenberg_get_jed_locale_data( 'text-domain' );
		$content = 'wp.i18n.setLocaleData( ' . json_encode( $locale ) . ', "text-domain" );';
		wp_script_add_data( 'my-script-js', 'data', $content );
	}
} );

En este ejemplo, estamos cargando nuestro script en el wp_enqueue_scripts gancho. Si está creando un bloque de Gutenberg, es posible que desee usar el enqueue_block_assets gancho o enqueue_block_editor_assets . Para seguir las mejores prácticas, nos aseguramos de cargar el código JavaScript minificado o no minificado en función del estado de la SCRIPT_DEBUG constante. Registramos nuestro script personalizado y le damos un identificador (my-script-js en este caso). Solo después de que hayamos registrado o puesto en cola nuestro script podemos llamar a wp_script_add_data(), lo que nos permite registrar datos personalizados con nuestro archivo JavaScript. Esencialmente, generará y ejecutará cualquier código JavaScript que proporcionemos, pero solo cuando se cargue nuestro archivo. El código JavaScript que queremos ejecutar es wp.i18n.setLocaleData(), al que se le pasarán los datos de configuración regional y nuestro dominio de texto personalizado. Estamos configurando el código JavaScript en PHP para que podamos pasar fácilmente nuestras traducciones del back-end al front-end. Como puede ver, estamos usando la gutenberg_get_jed_locale_data() función que acepta un dominio de texto y devuelve los datos de traducción en una estructura que el setLocaleData() método JavaScript espera. Usamos json_encode() para asegurarnos de convertir las matrices PHP en JSON y ¡listo! Nota: Solo por si acaso, estamos envolviendo nuestra llamada a gutenberg_get_jed_locale_data() en una function_exists() verificación en caso de que el complemento Gutenberg no esté activo o WordPress cambie el nombre de la función una vez que Gutenberg se incorpore al núcleo. En cualquiera de esos casos, deshabilitaría las traducciones de JavaScript. ¿Tienes alguna pregunta? Deja un comentario a continuación.

---

Micah Wood es un desarrollador de WordPress en Bluehost. Desarrollador profesional de WordPress durante más de una década, Micah ha trabajado en sitios para empresas de Fortune 100, ha lanzado más de una docena de complementos de WordPress, es un orador frecuente en WordCamps, coorganiza la reunión de WordPress Gwinnett , es coanfitrión en el podcast WP Square One y comparte sus conocimientos blogueando sobre temas de desarrollo de WordPress . Correo electrónico: [email protected]