La directory dei plugin di WordPress serve utenti in oltre 200 paesi. Se il tuo plugin è disponibile solo in inglese, escludi una parte significativa del tuo potenziale mercato. L'internazionalizzazione (i18n) — preparare il plugin alla traduzione — è uno degli investimenti con il ROI più alto che tu possa fare come sviluppatore di plugin.
WordPress ha un sistema di internazionalizzazione maturo che rende semplice preparare il tuo plugin alla traduzione in qualsiasi lingua. Il sistema usa gettext, un framework di traduzione ampiamente adottato, e funziona con strumenti come Poedit e GlotPress.
Le Funzioni Principali: __(), _e() e le Altre
WordPress fornisce diverse funzioni per l'internazionalizzazione. La più basilare è __(), che restituisce una stringa tradotta. La sua controparte _e() stampa direttamente la stringa tradotta. Usa __() quando devi catturare la stringa tradotta in una variabile e _e() quando la emetti direttamente nell'HTML.
Per le stringhe che includono segnaposto, usa sprintf() con la stringa tradotta come argomento di formato. WordPress fornisce anche _n() per la gestione singolare/plurale, _x() per le stringhe che richiedono contesto (come «post» come verbo rispetto al nome) e _nx() per forme plurali sensibili al contesto.
Text Domain: Come WordPress Identifica le Stringhe del Tuo Plugin
Ogni plugin che usa l'internazionalizzazione ha bisogno di un text domain unico. È una stringa che identifica le traduzioni del tuo plugin nel sistema WordPress. Il text domain deve corrispondere esattamente allo slug del tuo plugin ed è definito nel commento di intestazione del plugin.
Carica il text domain nell'inizializzazione del plugin usando load_plugin_textdomain(). Questa funzione dice a WordPress dove trovare i file di traduzione. La posizione standard è la directory /languages/ del plugin.
Creare i File di Traduzione
I file di traduzione usano i formati .po (Portable Object) e .mo (Machine Object). Il file .po è leggibile dall'uomo e contiene le stringhe originali con le loro traduzioni. Il file .mo è un binario compilato che WordPress legge per le prestazioni.
Genera il file .pot (Portable Object Template) iniziale usando uno strumento come il comando i18n di WP-CLI o Poedit. Il file .pot contiene tutte le stringhe traducibili del tuo plugin. I traduttori usano il file .pot come modello per creare i file .po per ogni lingua.
Dai un nome ai tuoi file usando il formato standard: {text-domain}-{locale}.po. Per l'italiano, è my-plugin-it_IT.po. Una volta tradotto il file .po, compilalo in formato .mo usando msgfmt o la funzione di salvataggio di Poedit.
Buone Pratiche per Stringhe Traducibili
Scrivere stringhe che si traducono bene richiede una certa disciplina. Ecco le pratiche più importanti:
- Usa frasi complete invece di frammenti concatenati. I traduttori hanno bisogno del contesto completo per produrre traduzioni accurate.
- Evita l'HTML all'interno delle stringhe traducibili. Se ti serve HTML in una stringa tradotta, usa sprintf() per inserire l'HTML come variabile.
- Non spezzare le frasi in più chiamate __(). Ogni chiamata viene tradotta indipendentemente e la struttura delle frasi varia tra le lingue.
- Includi commenti per i traduttori sulle stringhe ambigue. Usa un commento PHP che inizia con «translators:» sopra la chiamata __() per fornire contesto.
- Usa segnaposto per numeri, nomi e valori dinamici. I traduttori devono vedere la struttura completa della frase per produrre traduzioni naturali.
- Codifica il text domain in ogni chiamata di internazionalizzazione. Non usare una variabile per il text domain: rompe la capacità degli strumenti di traduzione di estrarre le tue stringhe.
Internazionalizzazione JavaScript
Se il tuo plugin usa JavaScript (per i blocchi Gutenberg, le interfacce di amministrazione o l'interattività frontend), devi internazionalizzare anche quelle stringhe. WordPress fornisce il pacchetto wp-i18n per JavaScript, che rispecchia le funzioni di internazionalizzazione PHP.
Usa le funzioni __() e _n() di @wordpress/i18n nel tuo codice JavaScript. Configura le traduzioni dello script usando wp_set_script_translations() in PHP, che dice a WordPress di caricare i file di traduzione per il tuo script.
Usare la Piattaforma di Traduzione di WordPress.org
Se il tuo plugin è nella directory dei plugin di WordPress.org, puoi sfruttare la piattaforma di traduzione della community. Traduttori da tutto il mondo possono contribuire con traduzioni per il tuo plugin tramite translate.wordpress.org.
Per abilitare le traduzioni della community, assicurati che il plugin abbia un file .pot e che il text domain sia configurato correttamente. Il sistema di WordPress.org rileva automaticamente il plugin e lo rende disponibile per la traduzione. Le traduzioni della community vengono incluse automaticamente negli aggiornamenti del plugin.
Il punto fondamentale
L'internazionalizzazione non è difficile, ma richiede disciplina costante. Usa le funzioni di internazionalizzazione di WordPress per ogni stringa che potrebbe comparire nell'interfaccia utente. Genera regolarmente il file .pot. Testa il plugin con una lingua di traduzione per individuare stringhe hardcoded che potresti aver dimenticato.
Lo sforzo ripaga quando il tuo plugin raggiunge utenti che non parlano inglese. Molti dei plugin WordPress di maggior successo hanno traduzioni in oltre 20 lingue, e spesso quelle traduzioni sono contribuite dalla community piuttosto che dallo sviluppatore. Rendi facile contribuire ai traduttori, e lo faranno.
