Crear bloque de Gutenberg personalizado – Parte 8: Soporte de traducción

En esta parte nos centraremos en cómo traducir los textos y valores en nuestro bloque de Gutenberg personalizado. Usamos WP-CLI para generar los archivos necesarios para que Gutenberg pueda cargar nuestras traducciones al cambiar el idioma de WordPress.

Antes de continuar con esto, debe tener instalado WP CLI (interfaz de línea de comandos para WordPress). Si no lo tiene, simplemente siga la guía en el Manual de WordPress para CLI.

Para explicar brevemente cómo traducir scripts de Javascript (Gutenberg): WordPress requiere .moarchivos para la traducción de archivos PHP, pero para Javascript WordPress requiere un .jsonarchivo. Cada archivo Javascript necesita un archivo JSON para la traducción. El JSON debe tener un formato específico (WP CLI lo generará por nosotros) con nuestras cadenas traducidas. Necesitamos un archivo JSON por idioma al que deseamos traducir.

Entonces, lo que debemos hacer primero es agregar las funciones gettext (__(), _e()etc.) en nuestros archivos Javascript y generar un archivo PO como de costumbre para nuestro tema o complemento. Debido a que hemos envuelto los textos en nuestros archivos de script con, por ejemplo __(), el archivo PO debería poder incluirlos. Luego hacemos la traducción como de costumbre en nuestro archivo PO. Y finalmente usamos WP CLI para extraer las cadenas necesarias del archivo PO y generar archivos JSON para todos nuestros archivos Javascript.

Tenga en cuenta que los archivos / de su tema o complemento .ponunca .motendrán un efecto en sus archivos Javascript, aunque contengan cadenas traducidas de nuestros archivos Javascript.

Implementando la traducción en Javascript

El primer paso es envolver todos los textos en nuestro archivo Javascript dentro de las funciones de traducción. Si ha manejado la traducción de WordPress en PHP, probablemente esté muy familiarizado con las funciones __(), _e(), esc_html__()etc. WordPress tiene un paquete wp.i18nque contiene estas funciones, que funcionan exactamente como en PHP.

Al igual que con PHP, debe proporcionar un dominio de dominio de texto (nombre/identificador). Puede ser lo que quieras, pero sé breve, ya que es probable que tengas que escribirlo muy a menudo. Para mi tema, configuré mi dominio de texto con el dominio awhitepixel. Entonces, dentro de PHP, lo haré __('My string', 'awhitepixel')para traducir cadenas, y será exactamente lo mismo en los archivos Javascript.

Comencemos a editar nuestro archivo Javascript. Primero necesitamos desestructurar la función __y _edel wp.i18npaquete. Debido a la naturaleza de React, lo más probable es que use la __función principalmente o quizás solo.

const { __, _e } = wp.i18n;

Y luego es cuestión de encontrar todos nuestros textos codificados en el archivo Javascript y actualizarlos. Tenga en cuenta que las funciones __y _erequieren el contexto de Javascript. Eso significa que cuando escribimos cadenas como, por ejemplo, valores de propiedades de objetos, los usamos __()de inmediato, pero como valores para, por ejemplo, accesorios, necesitamos envolver todo dentro { }para indicar que se trata de código Javascript.

Por ejemplo, nuestro registerBlockTypesoporte para traducción se verá así:

registerBlockType('awp/firstblock', {
    title: __('My first block', 'awhitepixel'), 
    category: 'common',
    icon: 'smiley',
    description: __('Learning in progress', 'awhitepixel'),
    keywords: [__('example', 'awhitepixel'), __('test', 'awhitepixel')],
    attributes: {
        ...

Y en cuanto a accesorios, es decir, en InspectorControls:

Envuelva todos los textos para los que desee admitir la traducción en __()y _e(). Si ha seguido este tutorial paso a paso, no debería tener ningún caso en el que necesite usar _e(). Cuando haya terminado, vuelva a compilar el Javascript y nos alejaremos de Javascript.

Configuración de archivos po y/o pot

Este paso varía un poco según lo que ya haya hecho y configurado para su tema o complemento. Es posible que esté escribiendo sus scripts de Gutenberg en un complemento nuevo y vacío que no se ha configurado para la traducción de PHP, o dentro de un tema que ya tiene un dominio de texto registrado. Es posible que tenga archivos PO (y MO) listos, o que solo tenga un archivo POT. Haré todo lo posible para cubrir todas las bases.

Mi tema o complemento ya tiene un archivo po(t)

Si ya tiene un archivo PO o POT en su proyecto, lo más probable es que también tenga la función PHP load_theme_textdomain(), load_child_theme_textdomain()o load_plugin_textdomain()en algún lugar de su código. Asegúrese de que el dominio registrado sea el mismo que ha utilizado en sus archivos Javascript.

Todo lo que necesita hacer es cargar el archivo PO para el idioma que desea traducir (o generar uno desde el archivo POT) en, por ejemplo , PoEdit. Haga clic en "Actualizar desde el código" (o similar en otros programas) para que el programa pueda escanear todos los archivos del proyecto (incluidos nuestros archivos Javascript actualizados recientemente) y actualizar el grupo de cadenas para la traducción. Deberían aparecer las cadenas en nuestro archivo Javascript. Luego solo necesita traducirlos como normales y guardar.

PD: si no puede hacer clic en "Actualizar desde el código" o volver a escanear los archivos, es probable que el archivo PO no se haya configurado correctamente. Busque consejos en la siguiente sección.

No tengo ningún archivo de traducción.

Si su tema o proyecto no ha sido configurado con traducción, necesita generar un archivo POT usando WP-CLI o crear manualmente un archivo PO.

Tengo una guía detallada sobre cómo crear un archivo PO en mi Tutorial de temas para principiantes, parte 8. La publicación describe cómo puede crear el archivo y configurarlo correctamente para buscar sus archivos de tema y las palabras clave para buscar (__, _e, etc.).

Si prefiere crear un archivo POT, puede usar el comando wp i18n make-pot en WP-CLI y luego crear un archivo PO a partir de eso usando, por ejemplo, PoEdit. Tenga en cuenta que deberá volver a generar el archivo POT (y luego el archivo PO) cada vez que actualice cualquier cadena en su código.

Resultado final

Lo que finalmente necesita es un archivo PO que haya encontrado sus cadenas de Javascript donde se han traducido. Recomiendo colocar sus archivos de traducción en una carpeta separada en su tema o complemento. Cuando comencemos a generar archivos JSON, terminaremos con bastantes archivos para traducir y será bueno mantenerlos todos juntos en su propia carpeta.

Como punto de referencia, estoy colocando todos los archivos de traducción en mi archivo theme/assets/lang/. Agregué una traducción al noruego para mi tema, llamada nb_NO.po, que contiene las cadenas traducidas de nuestro archivo Javascript de bloque personalizado.

Generación de archivos JSON desde el archivo po

El siguiente paso es usar WP-CLI para generar archivos JSON desde nuestro archivo po. Para ello usamos el comando wp i18n make-json.

Tenga en cuenta que, de manera predeterminada, este comando eliminará las cadenas traducidas de su archivo PO para usarlas en la generación de archivos JSON. Esto puede ser engorroso mientras se encuentra en medio del desarrollo de su tema o complemento. Porque cuando agrega cadenas nuevas o las ajusta, tendrá que volver a escanear los archivos y traducir todas las cadenas nuevamente (y otra y otra vez). Afortunadamente, hay una bandera en el comando para evitar esto.

¡Empecemos! En su terminal, navegue hasta el directorio de su idioma para su proyecto. Ejecute el siguiente comando y consulte su archivo po (como se mencionó, tengo un nb_NO.poarchivo listo).

wp i18n make-json nb_NO.po --no-purge

Si no tiene problemas para eliminar las cadenas traducidas de su archivo PO (por ejemplo, si está haciendo su compilación final), puede omitir la --no-purgebandera.

El terminal debería indicar "Éxito" e indicar cuántos archivos JSON se crearon. Si ve que generó dos archivos JSON, es porque leyó nuestro archivo Javascript de código fuente y el archivo de compilación, y generó uno para cada uno. Si tiene más archivos Javascript en su proyecto, terminará con aún más archivos JSON.

Al momento de escribir esto (WordPress v 5.3.2 y WP-CLI versión 2.4.0), los archivos JSON se generan con el código de idioma y un hash, una cadena críptica como nombres de archivo. Necesitamos encontrar el correcto y cambiarle el nombre.

Cambiar el nombre del archivo JSON y cargarlo en PHP

Su carpeta de idioma probablemente se parece a esto:

Recuerde que el comando ha generado un archivo JSON por archivo Javascript, y como en realidad tenemos dos archivos para nuestro bloque personalizado (la fuente y la compilación), generó dos archivos. Si su código Javascript se divide en varios archivos, cada uno obtendrá dos de sus propios archivos JSON.

Si solo tiene dos archivos JSON (porque no se encontraron otros archivos Javascript), puede eliminar uno de ellos ahora. Si tiene más de dos, debe abrir los archivos JSON y ver para qué archivo son. Los archivos JSON contienen una propiedad " source" que le indica para qué archivo Javascript es este archivo JSON. Úselo para averiguar qué archivo JSON conservar. Recomiendo encontrar el archivo de compilación final (a diferencia de los archivos de desarrollo), ya que debe contener todas las cadenas de todos los archivos.

Cuando haya encontrado el correcto, debemos cambiarle el nombre. Necesitamos cambiarle el nombre para que siga este patrón:

[textdomain]-[language code]-[script handle].json

Use el dominio de texto que ha usado en todas partes (por ejemplo __('My string', 'awhitepixel')), agregue un guión y el código de idioma. Luego proporcione un guión y el identificador de secuencia de comandos que utilizó para registrar su archivo Gutenberg Javascript (wp_register_script()). Como referencia, mi dominio de texto es awhitepixel, mi código de idioma es nb_NOy mi identificador de script para el script de Gutenberg es awp-myfirstblock-js. Así que cambio el nombre del archivo JSON a:

awhitepixel-nb_NO-awp-myfirstblock-js.json

Dile a WordPress que cargue nuestro JSON

Todo lo que queda ahora es el paso final: decirle a WordPress que cargue nuestro archivo JSON. Necesitamos usar la función [wp_set_script_translations](https://developer.wordpress.org/reference/functions/wp_set_script_translations/)(). Esta es una función bastante nueva de WordPress, por lo que recomiendo envolverla dentro de un archivo function_exists(). Acepta tres parámetros; el identificador del script para nuestro bloque, el dominio de texto y la ruta a nuestra carpeta de traducción (nota: la ruta, no la URL).

Dentro de nuestra función conectada a init, donde registramos nuestro script de bloque y llamamos register_block_type, también podemos llamar a esta nueva función para cargar nuestro archivo de traducción JSON. PD: Tenga en cuenta que el gancho enqueue_block_assetsno funcionará para registrar traducciones.

add_action('init', function() {
    wp_register_script('awp-myfirstblock-js', ....);
    register_block_type('awp/firstblock', ....
 
    if (function_exists('wp_set_script_translations')) {
        wp_set_script_translations('awp-myfirstblock-js', 'awhitepixel', get_template_directory(). '/assets/lang');
    }
});

¡Y eso es todo! Su bloque ahora debería estar traducido. Cambie el idioma de WordPress al idioma al que tradujo y compruébelo usted mismo. Cuando cambio mi idioma de WordPress a noruego y agrego mi bloque, el nombre y todo lo que contiene se traduce: