In questa lezione impariamo come funziona la traduzione (o altrimenti nota come i18n) in WordPress e come apportare le modifiche necessarie nei nostri modelli. Impareremo anche come impostare correttamente PoEdit per creare un file di traduzione per il nostro tema, pronto per essere tradotto in diverse lingue.
Perché preoccuparsi di aggiungere il supporto per la traduzione?
Tutti i temi, almeno quelli che diventano pubblici per l’uso da parte di persone diverse dallo sviluppatore, dovrebbero essere disponibili per la traduzione. Questa si chiama internazionalizzazione (i18n in breve) e consente alle persone di tradurre i testi che aggiungi nel tuo tema in un’altra lingua.
Il modo in cui funziona è che tu, come autore di temi o sviluppatore di plugin, avvolgi tutti i tuoi testi (come "Leggi di più", "Nessun post") in determinate funzioni. Queste funzioni fanno in modo che WordPress sia in grado di raccoglierli e iniettarli una traduzione se esiste. All’interno del tuo tema (o plugin) puoi aggiungere file di un certo tipo di file per ogni lingua tradotta, o assicurarti che altre persone siano in grado di creare la propria traduzione nella loro lingua.
Questo è molto utile per le persone che vogliono usare WordPress e il tuo tema (o plugin) in una lingua diversa dalla lingua di origine in cui è stato scritto (che di solito è l’inglese). Ma può anche essere utilizzato per cambiare alcuni testi in qualcosa di diverso all’interno della stessa lingua.
Se sei interessato all’argomento, WordPress Codex ha una lunga e buona guida alla documentazione su i18n per sviluppatori.
Implementazione di i18n nel nostro tema
Abbiamo già fatto la prima parte nel passaggio precedente di questa serie di tutorial sul tema, in cui abbiamo aggiunto load_theme_textdomainla funzione di configurazione del nostro tema. Nel caso ve lo foste dimenticato, questo è quello che abbiamo aggiunto:
load_theme_textdomain('wptutorial', get_stylesheet_directory(). '/lang');Il primo argomento è l’handle, questa è una stringa univoca che utilizzerai per raggruppare tutti i testi che appartengono al tuo tema. Ripeterai questa maniglia ogni volta che renderai un testo traducibile. Il secondo argomento dice a WordPress dove si trovano i file di traduzione. Li abbiamo definiti per risiedere in una sottocartella ‘ lang‘ nella nostra directory dei temi.
Non preoccuparti se questa cartella non esiste o non contiene alcun file: nulla andrà in crash. Se WordPress non trova la cartella né i file di traduzione corretti, tornerà per impostazione predefinita ai testi che abbiamo nel tema.
Il prossimo passo è esaminare tutto il nostro codice e trovare qualsiasi output di testo che dovrebbe essere traducibile. È buona norma assicurarsi di coprire assolutamente tutti i testi. Niente è più fastidioso dell’utilizzo di un tema o di un plug-in in cui l’autore ha codificato i testi rendendo impossibile la traduzione o la modifica in alcun modo.
Come rendere traducibili i testi
Quello che facciamo con tutti i testi è inserirli in una delle funzioni gettext di WordPress, che più comunemente sono _e()o __(). Il primo è un trattino basso con "e" che viene utilizzato quando si desidera fare eco al testo contemporaneamente. Il secondo è costituito da due caratteri di sottolineatura e viene utilizzato quando non si desidera eseguire l’eco ma memorizzarlo o utilizzarlo in una variabile.
WordPress ha più funzioni gettext che servono a scopi più specifici, ad esempio, esc_html__()e altro. Tuttavia non entreremo nei dettagli per quelli in questo tutorial._n()``_x()
Le funzioni gettext accettano due parametri; prima il testo stesso e, in secondo luogo, l’handle che hai definito in load_theme_textdomain. In questo caso è ‘ wptutorial‘.
Ad esempio, se hai qualcosa del genere:
echo 'Read more';Dovrai sostituirlo con:
_e('Read more', 'wptutorial');E allo stesso modo per la memorizzazione in una variabile;
$myvariable = 'Read more';Deve essere scritto così:
$myvariable = __('Read more', 'wptutorial');Ora dobbiamo trovare tutti i testi nei nostri modelli! Se hai seguito questo tutorial con una "T" non sono molti. Abbiamo alcune stringhe in index.phpe alcune in single.php.
Aggiunta del supporto per la traduzione nel nostro tema
Iniziamo con index.phpe individuare il messaggio "Nessun post, scusa" che abbiamo aggiunto se il ciclo non conteneva alcun post. Avvolgiamo questo testo all’interno _e()perché vogliamo ancora farne eco. Quindi questo è ciò che otteniamo:
Poiché hai usato _e(), non dovresti vedere alcun cambiamento quando premi Aggiorna in prima pagina o archivio. Ma sotto il cofano, questo testo è ora traducibile!
Abbiamo questo stesso testo nel nostro single.phpe page.php. Aggiornali come abbiamo fatto in index.php. Abbiamo aggiunto altri testi in single.php, quindi ecco come appare dopo aver reso tutti i testi traducibili:
D’ora in poi tutti i testi che aggiungiamo nel nostro tema ci assicuriamo di avvolgerli all’interno __()o _e().
File di traduzione
Ci sono due modi per fornire file di traduzione al tuo tema;
- Fornisci un
.pot-file - o fornire una coppia di
.poe.mofile.
Il .pot-file è consigliato per un tema che vendi o regali ad altri utenti, perché con questo file è molto facile generare un file di traduzione per una nuova lingua. Tuttavia non è facile (o gratuito) creare uno di quei file. Se hai familiarità con WP-CLI (riga di comando WordPress) o Grunt, puoi seguire le linee guida nella documentazione di WordPress qui. In caso contrario, l’altra alternativa potrebbe fare al caso tuo.
I file .poe .molavorare insieme. WordPress richiede una .motraduzione dei testi, ma questo file non è leggibile umanamente. Pertanto abbiamo il .pofile che è leggibile per noi. Con il software giusto genera il .mofile ogni volta che apporti modifiche.
Lo svantaggio di .poe .mofile è che è necessario generare una coppia per ogni lingua e, una volta tradotta in una lingua, non esiste un modo semplice per svuotare tutte le traduzioni per creare un’altra nuova lingua.
Hai bisogno di un programma per modificare .pote .pofile. Il più comune è PoEdit. PoEdit è gratuito e funziona sia per iOS che per Windows. Ma alcune funzionalità avanzate (come la generazione di un .potfile) richiedono purtroppo una versione a pagamento. Useremo la versione gratuita per creare un .pofile per il nostro tema.
Scarica e installa PoEdit per seguire il resto del tutorial.
Creazione di un file .po per il nostro tema con PoEdit
Creare un file di traduzione per l’inglese di solito non ha alcun senso quando tutti i testi nel nostro tema sono comunque in inglese, ma ai fini di questo tutorial creerò un file di traduzione in inglese.
1 Apri PoEdit e fai clic su File > Nuovo…
2 Ti verrà chiesto di scegliere una lingua. Scegli la lingua desiderata, ad esempio l’inglese.
3 Premi Salva (Ctrl+S). Individua la cartella del tema e accedi alla /lang/sottocartella. (Se non l’hai creato nell’ultimo passaggio, crealo ora). Il nome del tuo file è fondamentale. Per i temi dovrebbe essere chiamato solo il codice della tua lingua. Per l’inglese americano sarebbe en_US, per il norvegese lo è nb_NO. Cercalo su Google o fai riferimento a questa panoramica per trovare il codice della tua lingua. Lo chiameremo en_US.po.
4 Nel menu fare clic su Catalogo > Proprietà…
5 Nella prima scheda potresti inserire alcune informazioni come il nome del tuo progetto (tema) o cambiare la lingua, ma non è necessario. Ti consiglio di mantenere il set di caratteri in UTF-8 poiché questo è ciò che scriviamo per WordPress.
6 Fare clic sulla scheda Percorsi sorgenti. Qui dovrai definire in quali cartelle il file deve cercare i testi traducibili. I percorsi sono relativi e poiché l’abbiamo già salvato in una sottocartella del nostro tema, sappiamo che deve salire di una directory. Premi il pulsante + sotto la casella Percorsi e scegli Aggiungi cartelle. Scegli la directory del tuo tema. Questo dovrebbe aggiungere un elemento di percorso "." (salire di una cartella). Verifica che "Percorso di base" si riferisca alla directory del tema principale.
7 Fare clic sulla scheda successiva, "Sorgenti parole chiave". Qui devi indicare a PoEdit quali funzioni hai utilizzato per i testi traducibili (ad esempio __, _ee esc_html_ecosì via). Fare clic sul pulsante + per aggiungere ciascuna funzione e scriverle senza "()". Sta a te decidere se vuoi coprire tutte le tue basi e aggiungere tutte le funzioni gettext di WordPress, ma in questo tutorial sappiamo di averne usate solo due. Quindi aggiungiamo due elementi; __()e _e(). Aggiungi le funzioni senza alcuna parentesi.
8 Premi OK.
9 Non resta che dire a PoEdit di scansionare i percorsi forniti per le funzioni che utilizzano __()e _e()(o qualunque cosa tu abbia fornito). Puoi farlo premendo il pulsante "Aggiorna dal codice". (La versione Windows ha il testo sul pulsante ma la versione iOS no, quindi per iOS è necessario premere il pulsante che di solito è l’ultimo nella barra degli strumenti; un’icona di file con un’icona "ripeti" in alto. Fare clic il pulsante "Aggiorna da codice" e dovresti vedere tutti i testi elencati con un’interfaccia per la traduzione:
Simpatico!
File di traduzione generati
Ora puoi usare PoEdit per tradurre ogni stringa, ma non lo faremo qui poiché non ha senso tradurre dall’inglese all’inglese. Ricordati di premere Salva per aggiornare e generare un .mofile, e ogni volta che aggiungi un altro testo nel tuo tema, devi premere di nuovo il pulsante "Aggiorna dal codice". Quindi appariranno le nuove modifiche ai tuoi modelli.
Se controlli la /langsottocartella nella cartella della directory del tuo tema dovresti vedere due file; il .pofile che abbiamo appena creato, e un .mofile con lo stesso nome, generato da noi salvando in PoEdit.
Puoi fare una copia del en_US.pofile e rinominarlo in un codice di lingua diverso. Ma ricorda che PoEdit non offre un modo semplice per cancellare tutte le stringhe tradotte; dovresti cancellare uno per uno. Questo è il motivo per cui questo fa schifo per gli utenti che vogliono tradurre il tuo tema in una lingua diversa. Quindi, se hai la possibilità di creare un .potfile, dovresti farlo.
WordPress cercherà il file di traduzione in base alla lingua definita nel menu di amministrazione Impostazioni > Lingua del sito. Se hai aggiunto una lingua diversa dall’inglese, puoi provarla cambiando la lingua del sito e vedere se viene visualizzata la tua traduzione!