Crea un blocco Gutenberg personalizzato – Parte 8: Supporto alla traduzione

In questa parte ci concentreremo su come tradurre i testi e i valori nel nostro blocco Gutenberg personalizzato. Usiamo WP-CLI per generare i file necessari in modo che Gutenberg sia in grado di caricare le nostre traduzioni quando si cambia la lingua di WordPress.

Prima di procedere con questo, è necessario avere installato WP CLI (interfaccia della riga di comando per WordPress). Se non ce l’hai, segui la guida su WordPress Handbook for CLI.

Per spiegare in breve come tradurre per gli script Javascript (Gutenberg): WordPress richiede .modei file per la traduzione dei file PHP, ma per Javascript WordPress richiede un .jsonfile. Ogni file Javascript necessita di un file JSON per la traduzione. Il JSON dovrebbe essere di un formato specifico (WP CLI lo genererà per noi) con le nostre stringhe tradotte. Abbiamo bisogno di un file JSON per la lingua in cui desideriamo tradurre.

Quindi quello che dobbiamo fare è prima aggiungere le funzioni gettext (__(), _e()ecc.) nei nostri file Javascript e generare un file PO come al solito per il nostro tema o plugin. Poiché abbiamo racchiuso i testi nei nostri file di script con es __(), il file PO dovrebbe essere in grado di includerli. Quindi eseguiamo la traduzione come al solito nel nostro file PO. E infine utilizziamo WP CLI per estrarre le stringhe necessarie dal file PO e generare file JSON per tutti i nostri file Javascript.

Tieni presente che i file / del tuo tema o plugin .ponon .moavranno mai effetto sui tuoi file Javascript, anche se contengono stringhe tradotte dai nostri file Javascript.

Implementazione della traduzione in Javascript

Il primo passo è racchiudere tutti i testi nel nostro file Javascript all’interno delle funzioni di traduzione. Se hai gestito la traduzione per WordPress in PHP probabilmente hai molta familiarità con le funzioni __(), _e(), esc_html__()e così via. WordPress ha un pacchetto wp.i18nche contiene queste funzioni, che funzionano esattamente come in PHP.

Come con PHP, devi fornire un dominio textdomain (nome/handle). Può essere quello che vuoi, ma mantienilo breve poiché probabilmente dovrai scriverlo molto spesso. Per il mio tema ho impostato il mio dominio di testo con il dominio awhitepixel. Quindi all’interno di PHP farò __('My string', 'awhitepixel')per tradurre le stringhe e sarà esattamente lo stesso nei file Javascript.

Iniziamo a modificare il nostro file Javascript. Per prima cosa dobbiamo destrutturare la funzione __e _edal wp.i18npacchetto. A causa della natura di React, molto probabilmente utilizzerai principalmente o forse solo la __funzione.

const { __, _e } = wp.i18n;

E poi si tratta di trovare tutti i nostri testi hardcoded nel file Javascript e aggiornarli. Tieni presente che le funzioni __e _erichiedono il contesto Javascript. Ciò significa che quando scriviamo stringhe come ad esempio i valori delle proprietà degli oggetti, le usiamo __()immediatamente, ma come valori per es. props dobbiamo racchiudere tutto all’interno { }per significare che si tratta di codice Javascript.

Ad esempio, il nostro registerBlockTypecon supporto per la traduzione sarà simile a:

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

E per quanto riguarda gli oggetti di scena, cioè in InspectorControls:

Avvolgi tutti i testi per i quali desideri supportare la traduzione in __()e _e(). Se hai seguito questo tutorial passo dopo passo, non dovresti avere casi in cui devi usare _e(). Quando hai finito, ricompila Javascript e ci allontaneremo da Javascript.

Configurazione di file po e/o pot

Questo passaggio varia leggermente a seconda di ciò che hai già fatto e configurato per il tuo tema o plug-in. Potresti scrivere i tuoi script Gutenberg in un nuovo plug-in vuoto che non è stato impostato per la traduzione PHP o all’interno di un tema che ha già registrato un dominio di testo. Potresti avere file PO (e MO) pronti o potresti avere solo un file POT. Farò del mio meglio per coprire tutte le basi.

Il mio tema o plugin ha già un file po(t).

Se hai già un file PO o POT nel tuo progetto, molto probabilmente hai anche la funzione PHP load_theme_textdomain()o load_child_theme_textdomain()da load_plugin_textdomain()qualche parte nel tuo codice. Assicurati che il dominio registrato sia lo stesso che hai utilizzato nei tuoi file Javascript.

Tutto quello che devi fare è caricare il file PO per la lingua che vuoi tradurre (o generarne uno dal file POT) ad esempio PoEdit. Fai clic su "Aggiorna da codice" (o simile in altri programmi) in modo che il programma possa scansionare tutti i file di progetto (inclusi i nostri file Javascript aggiornati di recente) e aggiornare il pool di stringhe per la traduzione. Le stringhe nel nostro file Javascript dovrebbero apparire. Quindi devi solo tradurli normalmente e salvare.

PS: se non sei in grado di fare clic su "Aggiorna da codice" o scansionare nuovamente i file, è probabile che il file PO non sia stato impostato correttamente. Cerca suggerimenti nella prossima sezione.

Non ho nessun file di traduzione

Se il tuo tema o progetto non è stato impostato con la traduzione, devi generare un file POT utilizzando WP-CLI o creare manualmente un file PO.

Ho una guida completa su come creare un file PO nel mio Tutorial tema per principianti – parte 8. Il post descrive come creare il file e configurarlo correttamente per cercare i file del tema e le parole chiave da cercare (__, _e, ecc.).

Se si desidera creare un file POT, è possibile utilizzare il comando wp i18n make-pot in WP-CLI, quindi creare un file PO utilizzando ad esempio PoEdit. Tieni presente che dovrai rigenerare il file POT (e quindi il file PO) ogni volta che aggiorni le stringhe nel tuo codice.

Risultato finale

Ciò di cui hai bisogno alla fine è un file PO che abbia trovato le tue stringhe Javascript dove queste sono state tradotte. Ti consiglio di posizionare i tuoi file di traduzione in una cartella separata nel tuo tema o plugin. Quando inizieremo a generare file JSON, ci ritroveremo con un bel po’ di file da tradurre e sarà bello tenerli tutti insieme nella loro cartella.

Come punto di riferimento sto inserendo tutti i file di traduzione nel mio file theme/assets/lang/. Ho aggiunto una traduzione norvegese per il mio tema, denominata nb_NO.po, che contiene le stringhe tradotte dal nostro file Javascript di blocco personalizzato.

Generazione di file JSON dal file po

Il passaggio successivo consiste nell’utilizzare WP-CLI per generare file JSON dal nostro file po. Per fare ciò utilizziamo il comando wp i18n make-json.

Tieni presente che come impostazione predefinita questo comando eliminerà le stringhe tradotte dal tuo file PO per utilizzarle nella generazione di file JSON. Questo può essere ingombrante durante lo sviluppo del tuo tema o plugin. Perché quando aggiungi nuove stringhe o modifichi le stringhe dovrai scansionare nuovamente i file e tradurre tutte le stringhe ancora (e ancora, e ancora). Fortunatamente c’è un flag al comando per evitarlo.

Iniziamo! Nel tuo terminale, vai alla directory della tua lingua per il tuo progetto. Esegui il comando seguente e fai riferimento al tuo file po (come accennato, ho un nb_NO.pofile pronto).

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

Se non hai problemi con la rimozione delle stringhe tradotte dal tuo file PO (ad esempio se stai creando la tua build finale), puoi saltare il --no-purgeflag.

Il terminale dovrebbe richiedere "Success" e indicare quanti file JSON sono stati creati. Se vedi che ha generato due file JSON, è perché ha letto sia il nostro file Javascript del codice sorgente che il file build e ne ha generato uno per ciascuno. Se hai più file Javascript nel tuo progetto, ti ritroverai con ancora più file JSON.

Al momento della stesura di questo (WordPress v 5.3.2 e WP-CLI versione 2.4.0) i file JSON vengono generati con il codice della lingua e un hash, una stringa criptica come nomi di file. Dobbiamo trovare quello giusto e rinominarlo.

Rinominare il file JSON e caricarlo in PHP

La tua cartella della lingua probabilmente assomiglia a questa:

Ricorda che il comando ha generato un file JSON per file Javascript e poiché in realtà abbiamo due file per il nostro blocco personalizzato (il sorgente e la build) ha generato due file. Se il tuo codice Javascript è suddiviso in più file, ognuno otterrà due dei propri file JSON.

Se sei seduto con solo due file JSON (perché non sono stati trovati altri file Javascript), puoi eliminarne uno ora. Se ne hai più di due, devi aprire i file JSON e vedere a quale file si riferiscono. I file JSON contengono una proprietà " source" che indica a quale file Javascript è destinato questo file JSON. Usalo per capire quale file JSON conservare. Consiglio di trovare il file di build finale (al contrario dei file dev) poiché dovrebbe contenere tutte le stringhe di tutti i file.

Quando hai trovato quello corretto, dobbiamo rinominarlo. Dobbiamo rinominarlo per seguire questo schema:

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

Usa il dominio di testo che hai usato ovunque (es __('My string', 'awhitepixel')), aggiungi un trattino e il codice della lingua. Quindi fornisci un trattino e l’handle di script che hai usato per registrare il tuo file Javascript Gutenberg (wp_register_script()). Come riferimento, il mio dominio di testo è awhitepixel, il codice della mia lingua è nb_NOe il mio handle di script per lo script Gutenberg è awp-myfirstblock-js. Quindi rinomino il file JSON in:

awhitepixel-nb_NO-awp-myfirstblock-js.json

Dì a WordPress di caricare il nostro JSON

Tutto ciò che rimane ora è il passaggio finale: dire a WordPress di caricare il nostro file JSON. Dobbiamo usare la funzione [wp_set_script_translations](https://developer.wordpress.org/reference/functions/wp_set_script_translations/)(). Questa è una nuova funzione di WordPress, quindi consiglio di avvolgerla all’interno di un file function_exists(). Accetta tre parametri; l’handle di script per il nostro blocco, il dominio di testo e il percorso della nostra cartella di traduzione (nota: il percorso, non l’URL).

All’interno della nostra funzione hooked to init, dove abbiamo registrato il nostro script di blocco e call register_block_type, possiamo anche chiamare questa nuova funzione per caricare il nostro file di traduzione JSON. PS: Tieni presente che l’hook enqueue_block_assetsnon funzionerà per la registrazione delle traduzioni.

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');
    }
});

E questo è tutto! Il tuo blocco ora dovrebbe essere tradotto. Cambia la lingua di WordPress nella lingua in cui hai tradotto e verifica tu stesso. Quando cambio la mia lingua WordPress in norvegese e aggiungo il mio blocco, il nome e tutto ciò che contiene vengono tradotti: