Caricare correttamente i file di lingua di WordPress

Le funzionalità di localizzazione di WordPress ti permettono di rendere plugin e temi facilmente traducibili tramite i file di lingua di WordPress (file po/mo).

Questo è vero soprattutto da WordPress 3.7 ed è diventato molto più semplice da WordPress 4.6.

Sono stati apportati molti miglioramenti all'intero sistema di traduzione di WordPress, e ho sentito il bisogno di pubblicare un articolo aggiornato sull'argomento.

I file di lingua di WordPress – La confusione ( Edizione sviluppatori )

Per gli sviluppatori, il nodo centrale è come comunicare a WordPress nel modo corretto che si dispone di file di traduzione.

Come sviluppatori, ci è stato indicato di usare "load_plugin_textdomain()" e di puntare questa funzione al file di lingua nella cartella del plugin.

In passato, però, questo era l'unico posto in cui WordPress avrebbe cercato e se un utente aggiungeva un proprio file di lingua lì, al successivo aggiornamento sarebbe andato perduto!

Tempo fa circolava un articolo che promuoveva l'uso di una seconda chiamata, questa volta con la funzione "load_textdomain()", per puntare a un file nella cartella delle lingue di WP, e molti hanno adottato questo approccio (noi compresi).

Questo consentiva agli utenti di inserire i propri file di lingua in una posizione predefinita nella cartella delle lingue di WP, senza perdere la traduzione ad ogni aggiornamento del plugin.

I file di lingua di WordPress – La confusione ( Edizione utenti )

Gli utenti devono sapere dove inserire una traduzione personalizzata per un plugin/tema; il problema è che in passato i posti possibili erano diversi.

La documentazione di WP indica agli sviluppatori di fare riferimento a una cartella chiamata "languages" all'interno della cartella del plugin, ma lo sviluppatore potrebbe usare la cartella "lang" e in ogni caso, questa andrà persa quando il plugin/tema viene aggiornato.

Alcuni sviluppatori aggiungevano un secondo controllo in un percorso a loro scelta, spesso in una cartella con nome personalizzato all'interno della cartella delle lingue di WP.

Questo significava che non esisteva un modo uniforme per l'utente di sapere dove inserire in modo sicuro i propri file di traduzione personalizzati.

Caricare i file di lingua nel modo corretto (2017)

Da WP 4.6 tutto è diventato molto più semplice sia per gli utenti che per gli sviluppatori!

Come sviluppatore, ora devi solo assicurarti di caricare i file di lingua correttamente, seguendo la documentazione di WP come indicato di seguito:

<br />
// for plugins<br />
add_action( 'init', 'myplugin_load_textdomain' );<br />
function myplugin_load_textdomain() {<br />
  load_plugin_textdomain( 'my-plugin', false, basename( dirname( __FILE__ ) ) . '/languages' );<br />
}<br />

<br />
// for themes<br />
add_action( 'after_setup_theme', 'my_theme_setup' );<br />
function my_theme_setup(){<br />
    load_theme_textdomain( 'my-theme', get_template_directory() . '/languages' );<br />
}<br />

Nota che questi vengono attivati sugli hook 'init' e 'after_setup_theme': questo dovrebbe garantire che tutto si carichi senza problemi.

Se li attivi direttamente o prima dei rispettivi hook, potresti riscontrare problemi con alcune stringhe che non vengono tradotte, e plugin per la gestione delle traduzioni o per la creazione di siti multilingua come WPML potrebbero non funzionare affatto.

Come utenti, ora abbiamo a disposizione un percorso comodo e denominato in modo uniforme dove inserire i nostri file di lingua.

• Per i plugin: /wp-content/languages/plugins/my-plugin-en_US.mo
• Per i temi: /wp-content/languages/themes/my-theme-en_US.mo

'my-plugin' e 'my-theme' corrispondono al textdomain del plugin/tema (solitamente indicato nel file readme.txt del plugin o nel file style.css del tema, in cima al file).

Si tratta di un grande miglioramento rispetto al metodo precedente e nella maggior parte dei casi eviterà la perdita delle traduzioni durante gli aggiornamenti.

In alcuni casi il plugin/tema potrebbe già disporre di una nuova traduzione nella tua lingua memorizzata su wp.org; in tal caso potrebbe sovrascrivere il tuo file .mo, ma nella maggior parte dei casi questo è il comportamento desiderato.

Puoi contribuire alle traduzioni su wp.org se il plugin è ospitato lì; se si tratta di un plugin premium, è molto improbabile che la tua traduzione venga sovrascritta.

Informazioni aggiuntive

WordPress tenterà di trovare i file di lingua di WordPress in diversi percorsi; per un plugin con textdomain 'my-plugin' cercherà prima qui:

/wp-content/languages/plugins/my-plugin-en_US.mo

Se non trova una traduzione lì e il plugin specifica dove trovarne una in locale, cercherà lì:

/wp-content/plugins/my-plugin/languages/my-plugin-en_US.mo

Se il plugin non specifica un percorso, WordPress cercherà invece qui:

/wp-content/languages/my-plugin-en_US.mo

È bene seguire la documentazione di WordPress, ma in realtà da WP 4.6 non è nemmeno necessario specificare un file locale se non ne stai includendo alcuno (se sono archiviati nel repository di wp.org); puoi quindi semplicemente aggiungere questo:

<br />
// for plugins<br />
add_action( 'init', 'myplugin_load_textdomain' );<br />
function myplugin_load_textdomain() {<br />
  load_plugin_textdomain( 'my-plugin');<br />
}<br />

<br />
// for themes<br />
add_action( 'after_setup_theme', 'my_theme_setup' );<br />
function my_theme_setup(){<br />
    load_theme_textdomain( 'my-theme');<br />
}<br />

Spero che questo chiarisca un po' le idee sulle traduzioni; se hai domande o vuoi aggiungere qualcosa, lascia pure un commento qui sotto.