Quando si sviluppa un tema per la distribuzione, è necessario tenere in considerazione la possibilità che questo venga utilizzato da un pubblico internazionale di utenti. Un aspetto importante da non dimenticare, è quindi la localizzazione del tema.
La prima operazione da eseguire è in questo caso la definizione del Text Domain, ossia l'assegnazione di un'etichetta comune a tutte le stringhe di testo che devono essere tradotte. Questa etichetta costituisce una sorta di indirizzo virtuale dove è disponibile la traduzione della stringa originaria nella lingua dell'utente corrente. Il Text Domain deve corrispondere allo slug del tema.
La definizione del Text Domain
Il Text Domain va definito nell'intestazione del foglio di stile principale del tema. Si modifichi quindi il blocco commentato in testa al file style.css di Seventyone come indicato nel seguente codice:
/*
Theme Name: Seventy One Theme
Theme URI: https://github.com/carlodaniele/seventyone
Description: A basic theme for HTML.it readers.
Author: Carlo Daniele
Author URI: http://carlodaniele.it
Version: 0.1
Text Domain: seventyone
*/Definito il Text Domain vanno caricate le traduzioni delle stringhe originarie. A questo scopo si ricorre alla funzione load_theme_textdomain. Si apra il file functions.php del tema e si verifichi che la funzione agganciata all'hook after_setup_theme contenga la seguente istruzione:
// Theme Setup
function seventyone_setup() {
load_theme_textdomain( 'seventyone', get_template_directory() . '/languages' );
// your code
}
add_action( 'after_setup_theme', 'seventyone_setup' );Il primo argomento della funzione load_theme_textdomain individua il Text Domain, mentre il secondo argomento individua la directory (senza la slash finale) dove sono archiviati i file locali con estensione .po. A questo punto potranno essere utilizzate tutte le funzioni disponibili per la traduzione delle stringhe.
Una delle funzioni base nella localizzazione delle stringhe è __(). Questa restituisce semplicemente la traduzione di una stringa di testo. All'interno del tema viene utilizzata più volte, come, ad esempio, nella registrazione delle aree widget:
register_sidebar( array(
'name' => __( 'Sidebar Widgets', 'seventyone' ),
'id' => 'sidebar-primary',
'before_widget' => '<div id="%1$s" class="widget %2$s">',
'after_widget' => '</div>',
'before_title' => '<h3 class="widget-title">',
'after_title' => '</h3>',
) );In questo esempio il valore dell'elemento name è dato dalla traduzione della stringa Sidebar Widgets. In un'istallazione in lingua italiana, questo blocco di codice genera l'area widget mostrata nell'immagine che segue.
La successiva tabella riporta le funzioni di localizzazione di uso più comune.
| Funzione | Descrizione |
|---|---|
__() |
Restituisce la traduzione di una stringa. |
_e() |
Stampa la traduzione di una stringa. |
_x() |
Restituisce una traduzione in base al contesto. |
_n() |
Restituisce una traduzione nella forma plurale o singolare in base ad un valore numerico. |
_ex() |
Stampa una traduzione in base al contesto. |
_nx() |
Restituisce una traduzione singolare o plurale in base al contesto. |
Oltre a quelle appena viste, esistono due set di funzioni che effettuano l'escaping delle stringhe prima dell'output o della stampa:
esc_attr__()esc_attr_e()esc_attr_x()esc_html__()esc_html_e()esc_html_x()
Il comportamento delle funzioni è identico alle precedenti, con l'unica differenza della messa in sicurezza dei dati prima della restituzione o della stampa dell'output.
La traduzione di stringhe con variabili
Quando è necessario introdurre delle variabili all'interno delle stringhe, è buona norma utilizzare le funzioni PHP printf() e sprintf(). La prima funzione stampa una stringa in base ad un determinato formato, mentre la seconda restituisce la stringa per la successiva manipolazione. Ecco un esempio:
$message = sprintf( __( 'Hi %s!', 'seventyone' ), $user->display_name );Il valore di $user->display_name andrà a sostituire %s sia nella versione originale della stringa, che in tutte le traduzioni disponibili. Le funzioni printf e sprintf supportano numerosi tipi di dati, che si riassumono la seguente tabella:
| Tipo | Specificatore |
|---|---|
| string | s |
| integer | d, u, c, o, x, X, b |
| double | g, G, e, E, f, F |
Dopo aver predisposto gli script alla localizzazione, il passo conclusivo è la creazione dei file locali.
La creazione dei file locali
Si è detto che la cartella /languages ospita i file .po contenenti le versioni localizzate delle stringhe di testo presenti negli script del tema. Queste stringhe sono presenti in tutti i file .php, quindi sia il file funcions.php, sia i vari template. Occorrerà creare un file .po per ognuna delle lingue del tema, assegnando al file un nome compatibile con la specifica ISO 639. Il nome, quindi, sarà costituito da due parti separate da underscore: la prima parte del nome individua la lingua, la seconda la nazionalità (ad esempio it_IT.po).
Per la generazione dei file e la traduzione delle stringhe, è consigliabile l'utilizzo di un software gratuito come Poedit. Si tratta di un catalogo gettext Open Source che permette di generare i file .po necessari alla localizzazione delle stringhe di testo.
Avviato Poedit, bisognerà creare un nuovo catalogo dal menu "File". In fase di salvataggio del catalogo, Poedit preleverà tutte le stringhe presenti nelle directory impostate nella scheda "Percorsi sorgente" e individuate dalle funzioni PHP impostate nella scheda "Chiavi ricerca sorgente".
Si prenda ad esempio la stringa riportata qui di seguito, inserita nel template content-none.php:
<p><?php printf( __( 'Publish your first post <a href="%1$s">here</a>.', 'seventyone' ), admin_url( 'post-new.php' ) ); ?></p>Una volta generato il file it_IT.po, Poedit avrà prelevato tutte le stringhe da tradurre e ne permetterà la gestione come mostrato nell'ultima immagine di questo capitolo.
