Rendere traducibile un tema di WordPress

Rendere traducibile un tema di WordPress era una delle operazioni che ancora mancava al mio scarno bagaglio di conoscenze su questo meraviglioso e semplice CMS. Per questo motivo non ho mai inviato alla directory dei temi di WordPress nessuno dei lavori che ho realizzato. Eppure, una volta appresi i principi base che regolano l’internazionalizzazione di un tema, si rivela facile e richiede tutto sommato poco tempo, localizzazione compresa. In questo articolo vedremo, passo passo, come consentire la localizzazione in ogni lingua, partendo ovviamente dal fatto che il tema abbia come lingua base l’inglese, cioè lo standard sul web.

Un articolo sull’argomento è stato pubblicato su Cats Who Code, anche se necessita di qualche approfondimento, specie dal lato della creazione del modello per le traduzioni (il file .pot).

Rendere localizzabile il tema

Prima di cominciare, chiariamo cosa siano i tre diversi tipi di file con cui avremo a che fare, vale a dire il .pot, il .po e il .mo:

  1. il file .pot è il modello con cui si comincia una nuova traduzione e viene fornito dallo sviluppatore sia la prima volta in cui viene rilasciato sia quando le stringhe da tradurre saranno state aggiornate in una versione successiva;
  2. il file .po viene ottenuto dal precedente ed è quello su cui materialmente lavora il traduttore; questo file, poi, viene aggiornato prelevando le stringhe nuove dalla nuova versione del file .pot;
  3. il file .mo è la versione binaria del prcedente ed è quello che la macchina utilizza per visualizzare le stringhe tradotte; software come Poedit consentono di generare automaticamente questi file; questo è l’unico file indispensabile per visualizzare il software (in questo caso un tema di WordPress) nella lingua prescelta.

Per un approfondimento sulle operazioni di traduzione, si può leggere il testo Gestione pratica delle traduzioni, di Luca Ferretti.

Chiarito ciò, la prima cosa da fare per internazionalizzare il tema è inserire nel proprio functions.php le seguenti righe:

// Make theme ready for localization
// Translations must be archived in the `languages/' subdirectory
load_theme_textdomain( 'mydomain', get_template_directory() . '/languages' );
$locale = get_locale();
$locale_file = get_template_directory() . "/languages/$locale.php";
if ( is_readable( $locale_file ) )
	require_once( $locale_file );

Queste righe innanzitutto specificano il dominio della traduzione, in questo caso “mydomain” (voi personalizzatelo usando il nome del vostro tema; si posso usare anche gli spazi, ad esempio “My Domain”) e cercano il file, relativo alla lingua impostata nel proprio wp-config.php, nella sotto directory languages/ e, se esiste, lo usa. Cercate di essere brevi nel nome del dominio perché questo nome lo userete in ogni stringa da tradurre. Ovviamente non è obbligatorio inserire tutti i file di lingua in una sotto directory, ma per ragioni di pulizia è consigliabile farlo.

Rendere localizzabili le stringhe

Si passa ora alla parte che ci interessa più da vicino. Si tratta di passare in rassegna tutte le righe di tutti i file alla ricerca delle stringhe da rendere traducibili. Per farlo useremo le funzioni di gettext _e (underscore+e) e __ (doppio underscore). Ad esempio, la riga contenente questo:

<h2>Post not found!</h2>

diventerà

<h2><?php _e('Post not found!', 'mydomain'); ?></h2>

La funzione _e è una abbreviazione di echo con l’aggiunta della traducibilità.

Questo è il caso più semplice; ma se ci troviamo già all’interno di una funzione PHP come in questo caso:

<?php next_posts_link('&laquo; Older Entries'); ?>

ecco come renderla:

<?php next_posts_link(__('&laquo; Older Entries', 'mydomain')); ?>

racchiudendo quindi all’interno di questa struttura __('stringa', 'dominio') il testo da rendere traducibile.

Vediamo altri esempi.

Concatenazione

add_theme_page($themename." Options", "".$themename." Options", 'edit_themes', basename(__FILE__), 'mytheme_admin');

può diventare:

add_theme_page($themename.__(' Options', 'mydomain'), ''.$themename.__(' Options', 'mydomain'), 'edit_themes', basename(__FILE__), 'mytheme_admin');

Oppure ancora:

echo "<li><strong>Aperture:</strong> f/" . $imgmeta['image_meta']['aperture']. "</li>";

può diventare:

echo "<li><strong>".__('Aperture:', 'mydomain')."</strong> f/" . $imgmeta['image_meta']['aperture']. "</li>";

Printf

by <a href="<?php bloginfo('url') ?>"><?php bloginfo('name') ?></a>

può diventare:

<?php printf(__('by <a href="%1$s">%2$s</a>', 'CMS Pro Clean'), get_bloginfo('url'), get_bloginfo('name') ); ?>

In questo caso ciò che è racchiuso tra __( ) verrà reso traducibile mentre printf sostituirà a %1$s il risultato di get_bloginfo('url') e a %2$s il risultato di get_bloginfo('name'). In questo modo il traduttore non vedrà gli indirizzi web e la stringa da tradurre sarà più pulita.

Creare il modello .pot

Una volta che avremo finito col racchiudere le stringhe da tradurre nelle funzioni di gettext, dobbiamo creare il modello che i traduttori nelle varie lingue useranno per creare ciascuno il proprio file .po e successivamente il proprio .mo1. Avendo gettext installato sul proprio sistema, si potrà agire da terminale, ma ho visto2 che Poedit può estrarre tutte le stringhe da tradurre e aggiornare tutti i file (.pot, .po e .mo) quando i sorgenti (cioè i file del tema) vengono aggiornati. Ciò significa che sia lo sviluppatore che il traduttore possono utilizzare Poedit per eseguire tutte le operazioni necessarie.

Per creare il modello, si possono seguire queste linee:

  1. da Poedit aprite un nuovo catalogo (“File > Nuovo”) e inserite le informazioni nel form (per qualche chiarimento sul punto si può leggere qui);
  2. passate alla scheda “Percorsi” e aggiungete il percorso relativo alla directory da scansionare alla ricerca delle stringhe; se avete optato per lasciare il file del modello nella root del tema, basterà inserire un punto (.) e premere Invio; se invece avete optato per mettere tutti i file di traduzione nella directory languages/ compreso il modello, inserite ../. e premete Invio;
  3. passate alla scheda “Parole chiavi” e inserite le due funzioni che avete usato per marcare tutte le stringhe, vale a dire __ e _e, una riga per ciascuna funzione.
  4. fate clic su “Ok” e salvate il file .pot col nome che avete dato al dominio di traduzione del vostro tema (ad esempio my-theme.pot).

A questo punto avete completato il lavoro. La palla passa ai traduttori, i quali potranno creare un nuovo catalogo partendo dal modello .pot che avete consegnato. Quando il traduttore salverà il suo file .po, dovrà salvarlo nella forma con cui ha inserito la sua lingua nel file wp-config.php: per l’italiano it_IT.po, per l’inglese americano en_US.po e così via. La directory in cui salvare il file della localizzazione è, in questo caso, languages/, come definito nel file functions.php del tema.

Si noti che, a differenza dei plugin, il nome del file della traduzione del tema .mo deve seguire questo schema: lingua_LINGUA.mo, ad esempio it_IT.mo per l’italiano.

Aggiornare il modello .pot

Quando modificherete il tema e avrete aggiunto nuove caratteristiche, il tema presenterà probabilmente nuove stringhe di testo. In questo caso bisognerà aggiornare anche il modello da far avere insieme con la nuova versione del tema.

Occorrerà marcare, quindi, tutte le nuove stringhe e far rieseguire la scansione a Poedit aprendo il file del modello e facendo clic sul menu “Catalogo > Aggiorna da sorgenti”: alla fine della (breve) scansione Poedit vi darà il resoconto delle stringhe nuove e di quelle obsolete. Stesso discorso vale per le stringhe che erano già inserite e che sono state modificate: Poedit riconoscerà la modifica.

Il traduttore, a sua volta, ricevuta la nuova versione del tema con il nuovo modello, dovrà semplicemente scegliere la voce di menu “Aggiorna da file POT” e puntare al nuovo modello: anche qui sarà avvisato delle modifiche effettuate dallo sviluppatore.

Per approfondire

Non tutti gli aspetti della lavorazione sono coperti da questo articolo: per questo motivo vi rimando alla relativa pagina del Codex che tratta della localizzazione di plugin e temi:

Photo courtesy: Lance and Erin, Five Flags, CC by-nc-nd.


  1. Il file .po è quello su cui il traduttore materialmente lavora (sia traducendolo che aggiornandolo quando lo sviluppatore rilascia un modello .pot aggiornato, mentre il file .mo è quello che utilizza materialmente l’applicazione (WordPress in questo caso) per visualizzare la traduzione. Poedit può, se glielo si chiede nelle preferenze, costruire il file .mo al momento del salvataggio del file .po↩︎

  2. Non sapevo che Poedit può eseguire questo lavoro. Ho trovato queste preziose informazioni qui: Codex User Skippy↩︎