Rendere un plugin o un tema WordPress multilingua è oggi fondamentale, sia per una commercializzazione all’estero sia per motivi di professionalità. Il plugin più utilizzato per rendere un sito multilingua è The WordPress Multilingual Plugin, noto più comunemente come WPML.

In questa guida completa spiegheremo come tradurre un tema o un plugin WordPress in conformità alle linee guida di WordPress ed interoperabile con WPML.

A chi è rivolta questa guida

Questa guida è rivolta a tutti gli sviluppatori di temi e plugin per WordPress che non sono ancora riusciti ad eseguire una trasformazione multilingua dei propri software o che hanno la necessità di imparare a farlo.

Alla fine di questa guida, i plugin ed i temi saranno non solo compatibili secondo le direttive multilingua WordPress ma funzioneranno perfettamente anche con WPML, per cui lo stesso shortcode o porzione di codice posta in diverse pagine WPML si adatterà alla lingua prescelta dall’utente.

Funzionamento traduzione su WordPress

WordPress utilizza le librerie gettext, ormai da molti anni impiegate in numerosi progetti open source. Di seguito illustriamo brevemente come funziona la traduzione su WordPress:

  • Gli sviluppatori dei plugin e dei temi racchiudono le stringhe da tradurre in speciali funzioni gettext.
  • Con l’utilizzo di tools come Poedit, le stringhe da tradurre vengono estratte dal codice sorgente del tema o del plugin e catalogate all’interno di un file POT (estensione .po o .pot).
  • I traduttori eseguono la traduzione dei file POT.
  • I file POT vengono successivamente compilati in formato binario (estensione .mo) in modo da garantire un’accesso rapido e performante alla stringa tradotta.

Le funzioni WordPress gettext più utilizzate sono due:

  • __(), la quale ritorna come valore la corrispettiva traduzione della stringa passata come parametro;
  • _e(), equivalente alla precedente ma anziché ritornare il valore lo stampa a video (echo).

Esistono anche altre funzioni WordPress da adottare in base al contesto di traduzione.

1. Rendere temi e plugin conformi alla traduzione WordPress

Il primo passo da compiere per rendere un tema o un plugin compatibile con il sistema multilingua di WordPress è definire il Text Domain. Non si tratta altro che di una particolare stringa che aiuterà l’algoritmo a capire quale traduzione corrisponde al tema o al plugin di riferimento. 

1a. Text Domain per Plugin WordPress

Per impostare il text domain in un plugin basta aprire il file principale del plugin ed inserire la voce Text Domain: {nome-text-domain} nell’intestazione:

/*
Plugin Name: Mio Plugin
Plugin URI: http://www.squeezemind.it
Description: Il mio primo plugin Wordpress
Author: SqueezeMind SRL
Version: 0.1
Author URI: http://www.squeezemind.it/
Text Domain: mio-plugin
*/

Per una questione di prassi, solitamente il nome del Text Domain corrisponde alla slug del plugin, ma non è una regola imperativa. Nell’esempio precedente come nome è stato adottato mio-plugin ma avremmo potuto scrivere anche mio-text-domain-personalizzato.

1b. Text Domain per Temi WordPress

Analogamente per il tema, il Text Domain viene inserito all’interno del principale style.css, come da esempio:

/*
 * Theme Name: Mio Tema
 * Author: SqueezeMind SRL
 * Text Domain: mio-tema
 */

1c. Racchiudere le stringhe da tradurre con le funzioni gettext

Una volta impostato il Text Domain, occorre racchiudere le stringhe da tradurre con le funzioni gettext di WordPress, avendo l’accortezza di passare come secondo argomento il Text Domain appena creato. Spieghiamlo con un esempio:

Codice non compatibile alla traduzione

$variabile_1 = "Ciao mondo 1";
echo "Prima stringa tradotta: $variabile_1";

Codice compatibile alla traduzione

$variabile_1 = __("Ciao mondo 1", "text-domain-qui");
_e("Prima stringa tradotta: ", "text-domain-qui");
echo $variabile_1;

Codice compatibile alla traduzione con parametro, usando la famiglia printf

$variabile_1 = __("Ciao mondo 1", "text-domain-qui");
printf( __( 'Prima stringa tradotta: %s', 'text-domain-qui'), $variabile_1 );

Naturalmente text-domain-qui va sostituito con il Text Domain reale, che consigliamo di memorizzare in una costante PHP per non doverlo riscrivere ogni volta, diminuendo il rischio di commettere errori di trascrizione. Potrete inoltre sbizzarrirvi in base alla situazione utilizzando anche le altre funzioni che WordPress mette a disposizione come ad esempio _n(), che permette di stabilire quale frase utilizzare in un contesto singolare e quale per il plurale.

1d. Impostare la traduzione di eventuali file Javascript (UPDATE)

La traduzione dei file Javascript avviene in modo del tutto analogo. Vi invitiamo a leggere questa guida.

2. Creare i file di traduzione .PO e .MO per WordPress

Una volta reso compatibile tutto il codice del sorgente del plugin o del tema WordPress, occorre creare i file di traduzione. Per farlo utilizzeremo lo già citato software gratuito Poedit. Di seguito i passi da seguire per la creazione di un file traduzione:

  1. Aprire PoEdit
  2. Cliccare su File > New Catalog
  3. Nel tab Translation properties inserire il nome del progetto, ad esempio Mio Plugin, e la lingua, ad esempio English

    Proprietà Catalogo Poedit WordPress

  4. Salvare il nome del template di traduzione come MioPlugin.pot (oppure MioPlugin.po)
  5. Ignorare possibili messaggi di errore e cliccare sul menu Catalog > Properties
  6. Cliccare su Sources keywords ed inserire tutte le funzioni gettext di WordPress utilizzate nel codice sorgente (sicuramente le già citate _e e __) cliccando sull’icona New items

    Source Keywords Poedit WordPress

  7. Cliccare su Sources paths ed inserire il percorso assoluto al plugin in modo che Poedit possa caricare le stringhe da tradurre, ovvero tutte quelle racchiuse dalle funzioni elencate in Sources keywords

    Source path Poedit WordPress

  8. Cliccare su Ok
  9. Cliccare su Catalog e successivamente su Update from Sources

Se tutto è stato eseguito a regola d’arte, Poedit caricherà la lista di parole da tradurre. Importante: può essere tradotto solo testo in formato ASCII. Per caratteri speciali utilizzare la notazione HTML (è à ecc…).

File PO WordPress

Non rimane che salvare il template (o catalogo) di traduzione appena creato.

2a. Impostare il nome corretto del file di traduzione per i temi WordPress

Al momento di dover fare la traduzione, basta creare una nuova copia del file del catalogo avendo l’accortezza di rinominare il nuovo file secondo la forma {Locale}.po. Impostare il Locale corretto è essenziale per la traduzione, non basta specificare solo il Language Code della lingua di destinazione ma anche il Territorio. Esempio:

  • Locale italiano: it_IT
  • Locale inglese americano: en_US
  • Locale inglese britannico: en_GB
  • Locale tedesco: de_DE
  • Locale tedesco svizzero: de_CH

Visualizzate la lista completa dei Locale da adottare su WordPress. Per visualizzare il Locale attualmente in uso sulla pagina WordPress in corso, inserire il seguente filtro nel file functions.php del tema e scorrere all’altezza del footer:

add_action('wp_footer', function() { printf("
Il locale utilizzato &amp;egrave;: <b>%s</b>", get_locale()); });

Quindi se volessimo effettuare una traduzione per l’inglese americano del nostro tema, chiameremo il nuovo file POT en_US.po

Non resta che aprire il nuovo file con Poedit, effettuare le traduzioni e salvare. Verrà automaticamente creata la copia corrispondente in binario con estensione .mo, quella che andremo ad utilizzare su WordPress.

2b. Impostare il nome corretto del file di traduzione per i plugin WordPress

A differenza che per i temi, per i plugin occorre che il nome del file .mo venga preceduto anche dal Text Domain. La forma diventa quindi: {text domain}-{locale}.mo.

Ciò significa che se ad esempio il Text Domain impostato è mio-plugin, il nome del file binario della traduzione dovrà essere mio-plugin-en_US.mo.

3. Caricare i file di traduzione su WordPress

Prima di tutto occorre eliminare il falso mito che su WordPress anche i file .po hanno una loro valenza. WordPress prenderà in considerazione solo i file .mo, di conseguenza non serve inserire in produzione i file POT.

Adesso che tutto è pronto, occorre dire a WordPress dove andare a pescare i file per le traduzioni. Utilizzeremo due funzioni analoghe:

Entrambe le funzioni hanno un funzionamento molto simile, vediamo come utilizzarle.

3a. Caricamento dei file di traduzione su plugin WordPress

Siamo arrivati in fondo al problema. Non resta che inserire un action nel plugin per informare Wordpress circa il path da dove andare a pescare il file di traduzione compilato. Per farlo basta utilizzare il seguente codice:

function mio_plugin_carica_file_traduzioni() {
    load_plugin_textdomain("text-domain-qui", false, dirname( plugin_basename( __FILE__ )).'/languages'); 
}
 
add_action('init', 'mio_plugin_carica_file_traduzioni');

In questo caso stiamo dicendo a WordPress che i file traduzione si trovano nella directory languages all’interno della directory del plugin. Fate molta attenzione a dove collocate questo codice poiché il path alla directory languages sarà calcolato partendo dal path del file in cui il codice risiede. Esempio:

Se inserite il codice in /var/www/miosito/wp-content/plugins/my-plugin/my-plugin.php, il path sarà /var/www/miosito/wp-content/plugins/my-plugin/languages

Se inserite il codice in /var/www/miosito/wp-content/plugins/my-plugin/include/actions.php, il path sarà /var/www/miosito/wp-content/plugins/my-plugin/include/languages

3b. Caricamento dei file di traduzione su tema WordPress

Analogamente per quanto fatto con il plugin, aprire il file functions.php del tema ed inserire il seguente codice:

function mio_tema_carica_file_traduzioni(){
    load_theme_textdomain('text-domain-qui', get_template_directory().'/languages' );
}
 
add_action( 'after_setup_theme', 'mio_tema_carica_file_traduzioni' );

Anche in questo caso stiamo dicendo a WordPress che i file di traduzione si trovano all’interno della directory languages del tema ma, a differenza dei plugin, non si avranno i problemi relativi al percorso in quanto la funzione get_template_directory() restituirà sempre il path assoluto alla root del template.

4. Risoluzione dei problemi

Di seguito riportiamo una lista degli errori più comuni che si compiono durante questo delicato lavoro.

4a. Path errato dei file .mo

Uno degli errori comuni è il path errato, ovvero WordPress cercherà di caricare un file .mo in un percorso dove questo non esiste. Inserendo il seguente codice nel file functions.php potremo visualizzare la lista di file .mo con percorso assoluto per dato Text Domain che WordPress sta cercando di caricare. correggendo di fatto eventuali percorsi errati:

function debug_file_mo_caricati($false, $domain, $mofile ) {
  printf("Text Domain: <b>%s</b> - Path file .mo: <b>%s</b>", $domain, $mofile);
  return $false;
}
 
add_filter('override_load_textdomain', debug_file_mo_caricati, 10, 3);

4b. Nome del file .mo errato

Ricordiamo di utilizzare la seguente nomenclatura dei file .mo:

  • Per i plugin: {text domain}-{locale}.mo
  • Per i temi: {locale}.mo

Quindi se il Text Domain è mio-text-domain e il Locale per la traduzione è de_DE, la nomenclatura corretta è:

  • Per i plugin: mio-text-domain-de_DE.mo
  • Per i temi: de_DE.mo