Localizzazione in WordPress

Configurare WordPress per la localizzazione

Modificare le impostazioni locali

Per modificare le impostazioni locali di un sito WordPress:

• accedere alla console dell’amministratore,
• selezionare le voci di menu Impostazioni > Generali,
• modificare il valore dei campi:
  • Lingua del sito
  • Fuso orario
  • Formato della data
  • Formato ora
  • La settimana comincia di
• cliccare sul bottone Salva le modifiche

Aggiornare le traduzioni

Dopo la modifica della lingua predefinita del sito è necessario scaricare le traduzioni nella nuova lingua:

• accedere alla console dell’amministratore,
• selezionare le voci di menu Bacheca > Aggiornamenti,
• scorrere la pagina “Aggiornamenti di WordPress” fino alla sezione “Traduzioni”. Se è presente la scritta “Sono disponibili nuove traduzioni”, cliccare sul bottone Aggiorna le traduzioni e attendere il completamento del processo di aggiornamento.

Modificare la lingua per l’amministratore

E’ anche possibile modificare la lingua dell’amministratore:

• seleziona la voce di menu Utenti > Profilo,
• impostare il campo Lingua,
• cliccare sul bottone Aggiorna profilo

Modificare la lingua per un utente

Infine, è possibile modificare la lingua di un utente del sito:

• selezionare la voce di menu Utenti > Tutti gli utenti
• posizionare il mouse sopra il nome dell’utente
• nel menu che compare sotto al nome utente cliccare su Modifica
• impostare il campo Lingua
• cliccare sul bottone Aggiorna utente

Gestione delle traduzioni: i file PO/MO

WordPress e, se correttamente scritti, anche i suoi temi e i plugin utilizzano i file PO/MO per la localizzazione nelle diverse lingue.

Per informazioni dettagliate sui file PO/MO vedere l’articolo Cosa sono i file .PO e .MO su questo sito.

L’elenco delle lingue in cui è tradotto WordPress è pubblicato sulla pagina Translating WordPress.

La codifica dei nomi delle lingue (es: “it_IT” per la lingua italiana) rispetta i criteri dell’attributo globale lang del linguaggio HTML, con la sostituzione del trattino con un underscore (“it_IT” invece che “it-IT”).

I file PO/.MO usati dal core di WordPress sono collocati nella cartella /wp-content/languages (l’asterisco al termine del nome indica sia il file .PO che il file .MO):

• it_IT.*: traduzioni dei testi presenti nel codice sorgente della cartella /wp-includes
• admin-it_IT.*: traduzioni dei testi presenti nel codice sorgente della cartella /wp-admin
• admin-network-it_IT.*: come sopra, per le installazioni multi-site di WordPress
• continents-cities-it_IT.* traduzioni dei testi presenti nel file /wp-admin/includes/continents-cities.php

La cartella /wp-content/languages contiene anche le sottocartelle plugins e themes, con i file PO/MO di tutti i plugin e temi installati.

Download delle versioni aggiornate delle traduzioni

Le traduzioni di WordPress possono essere scaricate dalla pagina dei translation teams, cliccando sul link “View Team Page” della lingua desiderata.

Per la lingua italiana, il “language pack” (ovvero l’insieme dei file .PO e .MO sopra citati, più eventuali file .json utilizzati per la localizzazione degli script JavaScript) può essere scaricato direttamente dalla pagina del Translation Team Italiano, cliccando sul bottone Download language pack.

Voglio sovrascrivere una traduzione, posso modificare i file PO/MO?

Anche i language pack sono soggetti a manutenzione, perciò i file PO/MO non devono essere modificati, pena la sovrascrittura delle modifiche al successivo rilascio.

Per temi e plugin è però possibile creare dei file PO/MO all’interno del tema child ed utilizzarli per correggere eventuali errori di traduzione presenti nei file PO/MO distribuiti.

Per le eventuali correzioni di traduzioni del Core di WordPress questa modalità non è applicabile e si dovrà ricorrere agli hook di filtro.

Di seguito i procedimenti per temi/plugin e per il Core di WOrdPRess.

Sovrascrivere le traduzioni dei temi di WordPress

Per sovrascrivere le traduzioni di un tema si può ricorrere al tema child. Ecco come procedere:

• creare una directory nel tema child che contenga i file PO/MO con le traduzioni personalizzate;
• indicare tale directory a WordPress (affinché cerchi al suo interno i file di traduzione);
• creare un file .PO con le traduzioni personalizzate;
• generare il file .MO;
• portare il file .MO (e il corrispondente file .PO) in produzione, nella directory creata nel primo punto.

Pe un esempio dettagliato di tali attività, vedere l’articolo Come personalizzare le traduzioni del tema Divi in questo sito.

Sovrascrivere le traduzioni dei plugin di WordPress

Per sovrascrivere le traduzioni di un plugin, non esistendo il concetto di “plugin child”, si dovrà procedere in modo differente:

• eliminare eventuali traduzioni del plugin già presenti;
• caricare il file delle traduzioni personalizzate
• caricare il file delle traduzioni originali

Queste operazioni devono essere inserite in un hook di tipo action, dopo il caricamento del plugin.

Per un esempio dettagliato di tali attività, vedere l’articolo xxxxx

Sovrascrivere le traduzioni del Core di WordPress

Ciascuna funzione WordPress per la localizzazione utilizza in sequenza due hook di filtro che offrono la possibilità di sovrascrivere la traduzione originale di WordPress, uno generico ed uno specifico per il dominio, ad esempio gettext e gettext_default (“default” è il dominio dei nomi del Core di WorPress).

L’hook specifico di dominio, richiamato per ultimo, può sovrascrivere non solo la traduzione originale ma anche quella personalizzata estratta dall’hook generico.

Ecco ad esempio come si può sovrascrivere il saluto di benvenuto che compare nella bacheca dell’amministratore, aggiungendo il nome dell’utente:

function sovrascrivo_traduzioni_core( $translated_text, $untranslated_text, $domain ) {
    if ( $untranslated_text === "Welcome to WordPress!" ) {
        $current_user = wp_get_current_user();
        return "Ciao " . $current_user->first_name . ", ti diamo il benvenuto in WordPress!";
    } else {
        return $translated_text;
    }
}
add_filter( 'gettext_default', 'sovrascrivo_traduzioni_core', 10, 3 );

Va gestita una complicazione: gli hook utilizzati da una funzione di localizzazione dipendono dalla categoria di quest’ultima, perciò:

• o si procede in modo empirico, provando ad utilizzare tutti quattro gli hook specifici di dominio, partendo da gettext_default, che è in assoluto l’hook maggiormente utilizzato,
• o si procede in modo analitico, individuando quale funzione di localizzazione emette il messaggio che si vuole sovrascrivere e andando ad utilizzare il corrispondente hook, in base alla tabella del paragrafo “Riepilogo degli hook di filtro per sovrascrivere le traduzioni del Core di WordPress“.
  Di seguito si descrive questo metodo, utilizzando un esempio.

Individuare la funzione di localizzazione che produce il messaggio da sovrascrivere.

Immaginiamo di voler modificare il testo che compare nella parte alta della pagina degli Articoli di WordPress, modificando il termine “Pubblicati” con “Usciti”:

Inserendo in functions.php il seguente codice, che utilizza l’hook gettext_default, si vedrà che non si ottiene l’effetto desiderato:

function sovrascrivo_traduzioni_core( $translated_text, $untranslated_text, $domain ) {
    switch ( $translated_text ) {
        Case "Pubblicato <span class=\"count\">(%s)</span>":
            return "Uscito <span class=\"count\">(%s)</span>";
            break;
        Case "Pubblicati <span class=\"count\">(%s)</span>":
            return "Usciti <span class=\"count\">(%s)</span>";
            break;        
    default:
        return $translated_text;
    }
}
add_filter( 'gettext_default', 'sovrascrivo_traduzioni_core', 10, 3 );

Ciò perché la funzione di localizzazione che emette il messaggio è _n_noop().

Ecco come procedere per trovare il corretto hook da utilizzare:

• Nel file /wp-content/languages/it_IT.po sono presenti i testi da tradurre del Core di WordPress, completi del riferimento alla riga di codice che utilizza ciascun testo. Dopo aver aperto il file con un editor (non con POEdit, che nasconde i riferimenti al codice), se si cerca “pubblicati”, dopo qualche tentativo si arriva alla seguente scrittura:

#. translators: %s: Number of published posts.
#: wp-includes/post.php:375
msgid "Published <span class=\"count\">(%s)</span>"
msgid_plural "Published <span class=\"count\">(%s)</span>"
msgstr[0] "Pubblicato <span class=\"count\">(%s)</span>"
msgstr[1] "Pubblicati <span class=\"count\">(%s)</span>"

• La riga di codice che utilizza il testo in questione è quindi /wp-includes/post.php:375.
  Aprendo il file post.php, sempre con un text editor, alla riga 375 si troverà:

• la funzione di localizzazione è perciò _n_noop(); se si ricercano i corrispondenti hook nella tabella del paragrafo successivo, si otterranno i valori: ngettext / ngettext.{$domain}
• basterà dunque usare l’hook ngettext_default invece che gettext_default:

add_filter( 'ngettext_default', 'sovrascrivo_traduzioni_core', 10, 3 );

Riepilogo degli hook di filtro per sovrascrivere le traduzioni del Core di WordPress

Rigenerare un file .POT

Se non si ha a disposizione il file .PO, oppure quest’ultimo non risulta aggiornato (e quindi, restando nell’esempio, alla riga 375 non si trova nulla che richiami l testo ricercato), è possibile rigenerare il file .POT (dal quale ottenere i corretti riferimenti al codice sorgente) utilizzando WP CLI:

• verificare se WP CLI è installato sul computer dove risiede il sito, ed eventualmente installarlo (qui le istruzioni su come installare WP CLI);
• aprire una finestra DOS (o una shell negli ambienti unix-like), posizionarsi nella cartella dov’è installato WordPress ed eseguire il seguente comando di WP CLI “wp i18n make-pot” (qui la documentazione del comando). Nell’esempio che segue, si vuole creare il file .admin.pot con i testi da tradurre presenti nel code della directory wp-admin. Il file .pot viene inserito all’interno di una struttura di cartelle del tema child:

wp i18n make-pot ./wp-admin ./wp-content/themes/divi-child/languages/core/admin.pot

Risorse online

• I18n for WordPress Developers (https://codex.wordpress.org/I18n_for_WordPress_Developers)
• Se si usa DIVI: How to translate the Divi Theme dal sito (https://intercom.help/elegantthemes)
• A proposito di siti multilingua: Guida di wp-sos.it sui siti WordPress multilingua (usando WPML)