Se stai costruendo un plugin WordPress per il repository pubblico, l'internazionalizzazione — comunemente chiamata i18n — non è opzionale. WordPress è usato in oltre 200 paesi e oltre il 50% delle installazioni usa lingue diverse dall'inglese. Un plugin che non è pronto per la traduzione esclude più della metà del suo potenziale pubblico.
Fortunatamente, WordPress fornisce un sistema i18n completo che rende semplice preparare il tuo plugin alla traduzione. Questa guida copre tutto ciò che devi sapere, dalle funzioni PHP di base all'i18n JavaScript fino al flusso di traduzione GlotPress.
Le Basi: __() e _e()
Al centro dell'i18n di WordPress ci sono due funzioni che marcano le stringhe per la traduzione. La funzione __() restituisce la stringa tradotta, mentre _e() la stampa direttamente. Entrambe accettano due parametri: la stringa da tradurre e il text domain — un identificatore univoco per le traduzioni del tuo plugin.
Ogni stringa che appare nell'interfaccia utente del tuo plugin dovrebbe essere avvolta in una di queste funzioni. Questo include i testi dei pulsanti, le etichette, i messaggi di errore, i titoli delle pagine di amministrazione e le descrizioni delle impostazioni. Se un utente può vederla, dovrebbe essere traducibile.
Il Text Domain: La Chiave di Traduzione del Tuo Plugin
Il text domain è uno slug univoco che identifica il tuo plugin nel sistema di traduzione. Deve corrispondere allo slug del tuo plugin nella directory WordPress.org. Lo dichiari nell'intestazione del plugin e lo carichi con la funzione load_plugin_textdomain(), tipicamente in un hook collegato a plugins_loaded.
Se cambi il text domain dopo che i plugin sono stati tradotti, tutte le traduzioni esistenti si rompono. Scegli il text domain con attenzione e non cambiarlo mai.
Plurali e Contesto
L'inglese ha regole di plurale semplici, ma molte lingue hanno forme plurali complesse. Usa _n() per le stringhe che richiedono la gestione singolare/plurale. Accetta quattro parametri: la forma singolare, la forma plurale, il numero per determinare quale forma usare e il text domain.
Per le stringhe che richiedono contesto aggiuntivo — come «post» nel senso editoriale rispetto a «post» come posta — usa _x() e _ex(). Queste funzioni aggiungono un parametro di contesto che aiuta i traduttori a comprendere il significato corretto.
Variabili nelle Stringhe Tradotte
Non concatenare mai stringhe tradotte con variabili. L'ordine delle parole cambia tra le lingue e le variabili hardcoded rompono le traduzioni. Usa sprintf() con la sintassi dei segnaposto per inserire variabili nelle stringhe tradotte.
Usa %s per le stringhe, %d per gli interi e %f per i numeri in virgola mobile. Aggiungi segnaposto numerati come %1$s quando devi riferirti alla stessa variabile più volte o cambiare l'ordine delle variabili in una traduzione.
i18n JavaScript con wp.i18n
Per il codice JavaScript nel tuo plugin — in particolare i blocchi Gutenberg personalizzati e le interfacce di amministrazione — usa il pacchetto wp.i18n fornito da WordPress. Fornisce equivalenti di __(), _n(), _x() e sprintf() che funzionano lato client.
Per usare wp.i18n, metti in coda lo script wp-i18n come dipendenza del tuo file JavaScript. Poi usa le funzioni direttamente nel tuo codice. Il processo di build di WordPress estrae le stringhe dai tuoi file JavaScript e genera automaticamente i file di traduzione.
Generare i File POT
Il file POT (Portable Object Template) è il modello principale che i traduttori usano per creare traduzioni in lingue specifiche. Contiene tutte le stringhe traducibili del tuo plugin. Generalo usando uno strumento come il comando i18n di WP-CLI o un plugin come Loco Translate.
Esegui wp i18n make-pot . languages/my-plugin.pot dalla directory del tuo plugin. Questo scansiona i tuoi file PHP e JavaScript, estrae tutte le stringhe traducibili e genera il file POT. Includi questo file nella directory languages del plugin.
La Piattaforma di Traduzione di WordPress.org
Quando il tuo plugin è su WordPress.org, i traduttori possono contribuire con traduzioni tramite translate.wordpress.org. La piattaforma rileva automaticamente il file POT del tuo plugin e lo rende disponibile per la traduzione. I traduttori della community possono inviare traduzioni per la loro lingua e gli utenti ricevono automaticamente le traduzioni per il loro locale.
Per ottenere il massimo da questa piattaforma, mantieni aggiornato il file POT a ogni release. Aggiungi commenti chiari alle tue funzioni i18n per aiutare i traduttori a comprendere il contesto. Rivedi le traduzioni inviate prima che vengano pubblicate.
Il punto fondamentale
L'internazionalizzazione non è difficile, ma richiede disciplina. Avvolgi ogni stringa rivolta all'utente in __() o _e(). Usa sprintf() per le variabili. Genera il file POT a ogni release. Mantieni coerente il text domain. Queste pratiche aprono il tuo plugin a un pubblico globale e sono richieste per la directory WordPress.org.
