Come rendere un plugin WordPress pronto per la traduzione?

1. Scrivi pensando alla localizzazione

Non usare echo o print() per produrre output di testo, invece utilizza le funzioni di WordPress __() e _e():

/** Non compatibile con la localizzazione */
echo "Benvenuto nel mio plugin";    
// OPPURE
print("Benvenuto nel mio plugin");

/** Compatibile con la localizzazione */
_e('Benvenuto nel mio plugin', 'my-plugin');
// OPPURE
$my_text = __('Benvenuto nel mio plugin', 'my-plugin');
echo $my_text;

_e() e __() forniranno la traduzione — nella lingua corrente — del testo fornito come primo parametro. _e() mostrerà il testo mentre __() lo restituirà.

Il secondo parametro è il text domain, lo userai per dire a WordPress che il testo fornito come primo parametro appartiene a questo plugin. Puoi usare qualsiasi nome tu voglia ma io preferisco usare lo stesso nome del file o della directory del plugin, lo trovo più intuitivo.

Come mostrare testo dinamico come: "Ciao <username>"?

Con __() e sprintf():

/** Ottieni il nome utente */
$username = 'Magictrick';

/** Non compatibile con la localizzazione */
echo "Ciao $username";     

/** Compatibile con la localizzazione */
printf(__('Ciao %s', 'my-plugin'), $username);
// OPPURE 
$my_text = sprintf(__('Ciao %s', 'my-plugin'), $username);
echo $my_text;

2. Prepara i file .pot/.po/.mo

Definizioni

• Il file .pot: è messo a disposizione dallo sviluppatore del plugin e viene usato come punto di partenza per creare nuove traduzioni, WordPress non lo utilizza.
• Un file .po: è un file di traduzione che tu o qualcun altro avete iniziato, e magari completato, WordPress non lo utilizza.
• Un file .mo: è creato automaticamente da Poedit ogni volta che salvi un file .po, tutto ciò che puoi fare con questi file è caricarli o ricaricarli ogni volta che crei o aggiorni un file .po. WordPress ottiene le traduzioni dai file .mo.

Apri Poedit e crea un nuovo catalogo (File › Nuovo catalogo...) con queste impostazioni:

• Info progetto: Usa le tue informazioni (o del tuo team), la lingua e il paese dovrebbero corrispondere alla lingua predefinita del tuo plugin
• Percorsi:
  • Percorso base: .
  • Percorsi: rimuovi tutto e aggiungi .. (memorizzeremo i file della lingua in una sottodirectory del plugin chiamata languages)
• Parole chiave: rimuovi tutto e aggiungi __ e _e

Salva il catalogo come /my_wordpress_blog/wp-content/plugins/my-plugin/languages/<strong>my-plugin.pot</strong> e scansiona i file del tuo plugin per il testo traducibile premendo il pulsante di aggiornamento. Quando l'aggiornamento è terminato chiudi quel catalogo, non avrai bisogno di aggiornare quel file a meno che non aggiungi nuove stringhe traducibili (cioè racchiuse in __() o _e()) al tuo plugin.

Ora creiamo la prima traduzione (userò fr_FR):

Usando Poedit, crea un catalogo da un file POT (File › Nuovo catalogo da file POT...):

• Info progetto: Usa le tue informazioni (o del tuo team), cambia la lingua e il paese, io userò Francese e Francia
• Percorsi: Non cambiare
• Parole chiave: Non cambiare

Salva il catalogo come /my_wordpress_blog/wp-content/plugins/my-plugin/languages/<strong>my-plugin-fr_FR.po</strong>. Traduci alcune o tutte le stringhe, salva nuovamente il file .po, carica sia il file .po che .mo.

Nota che ogni volta che salvi un file .po viene generato un file .mo con lo stesso nome, il nome del file .po è cruciale, è composto dalla concatenazione del text domain del plugin (my-plugin) e della localizzazione della lingua (fr_FR), nomina sempre i tuoi file .po per i plugin così: [textdomain]-[locale].po, ecco alcuni esempi:

• Italiano/Italia: wpcf7-it_IT.po
• Portoghese/Brasile: wpcf7-pt_BR.po
• Arabo: wpcf7-ar.po... Sì!

Ogni volta che il plugin viene aggiornato con nuovo testo, aggiorna il file po, traduci le nuove stringhe e ricarica i file .po e .mo

3. Istruisci il plugin a caricare il testo tradotto per la lingua corrente

Da qualche parte nel tuo plugin, devi dire a WordPress di usare il tuo file .mo, puoi farlo usando questo codice all'inizio del tuo file del plugin:

function my_plugin_init() {
  load_plugin_textdomain( 'my-plugin', false, 'my-plugin/languages' );
}
add_action('init', 'my_plugin_init');

Sostituisci my-plugin con il nome del tuo plugin nel 1° e 3° parametro della funzione load_plugin_textdomain.

4. Testa e risolvi i problemi

Alcuni motivi per cui potrebbe non funzionare:

• Le stringhe non sono importate nel file .pot o .po
  • → Impostazioni del catalogo sbagliate (percorso o parole chiave o entrambi)
• Il testo non è tradotto sul sito WordPress
  • → Manca il file .mo per quella lingua o ha un nome file errato
  • → Text domain non usato (sostituisci _e('my text') con _e('my text', 'my-plugin'))
  • → Text domain non caricato (usa l'esempio sopra con i parametri corretti, WP non ti avviserà degli errori)