Come Tradurre un Plugin WordPress (Passo dopo Passo)

Hai trovato il plugin WordPress perfetto per il tuo progetto. Fa esattamente ciò di cui hai bisogno, le recensioni sono entusiastiche, e poi lo attivi e ti rendi conto che ogni pulsante, etichetta e messaggio di errore è in inglese. I tuoi visitatori tedeschi, francesi o giapponesi stanno per imbattersi in un muro di testo che non possono leggere.

La buona notizia è che la maggior parte dei plugin ben costruiti sono pronti per la traduzione, il che significa che lo sviluppatore ha incapsulato le proprie stringhe in funzioni Gettext proprio perché persone come te possano tradurle. La sfida è sapere dove si trovano i file, come nominare la tua traduzione e dove posizionarla in modo che il prossimo aggiornamento del plugin non cancelli il tuo lavoro.

Questa guida ti mostra come tradurre un plugin WordPress dall'inizio alla fine: trovare il text domain e la cartella delle lingue, ottenere o generare il template .pot, costruire file .po e .mo con il nome corretto e posizionarli dove WordPress li caricherà in modo affidabile. Tratteremo anche l'unico tipo di plugin che questo approccio non può tradurre completamente, in modo che tu non sprechi ore a combattere una causa impossibile.

Come si Trovano i File di Traduzione di un Plugin?

Prima di tradurre qualsiasi cosa, hai bisogno di due informazioni dal plugin: il suo text domain e la sua cartella delle lingue. Il text domain è la stringa unica che il plugin usa per identificare le proprie traduzioni, e la cartella delle lingue è dove risiede il template sorgente.

Localizzare la Cartella delle Lingue e il Text Domain

Apri la directory del plugin in wp-content/plugins/your-plugin/ e cerca una sottocartella /languages. Al suo interno, di solito troverai un file .pot, il template vuoto che contiene ogni stringa traducibile.

Per confermare il text domain, apri il file PHP principale del plugin e guarda il suo blocco di intestazione:

/**
 * Plugin Name: Awesome Plugin
 * Text Domain: awesome-plugin
 * Domain Path: /languages
 */

Qui il text domain è awesome-plugin. Questo valore è fondamentale, perché i tuoi file di traduzione devono includerlo nei loro nomi o WordPress non li abbinerà mai al plugin. Lo vedrai anche in ogni chiamata di stringa in tutto il codice:

echo __( 'Settings saved successfully.', 'awesome-plugin' );

Quel secondo argomento, awesome-plugin, è di nuovo il text domain. Ogni stringa che lo usa può essere tradotta dal tuo catalogo. Se una stringa nell'interfaccia del plugin manca di questo "wrapper", ad esempio uno sviluppatore che ha codificato echo 'Save' senza __(), allora quella stringa non è traducibile affatto, e nessun file .po può raggiungerla. La maggior parte dei plugin affidabili incapsula tutto correttamente, ma se noti una o due stringhe ostinate che si rifiutano di tradurre, un "wrapper" Gettext mancante nel codice sorgente è un probabile colpevole.

Un modo rapido per valutare se un plugin è veramente pronto per la traduzione è controllare la sua scheda sulla directory WordPress.org, che mostra una percentuale di traduzione e link a un template /languages. Un plugin con un progetto di traduzione attivo ha molte più probabilità di avere stringhe pulite e completamente incapsulate rispetto a uno abbandonato.

Cosa Succede se il Plugin Non Ha un File POT?

Alcuni plugin vengono distribuiti senza un template .pot. Se la cartella /languages è vuota o mancante, devi generare il template tu stesso scansionando il codice sorgente per le stringhe traducibili.

Lo strumento standard per questo è WP-CLI, che estrae ogni chiamata Gettext in un nuovo .pot.

wp i18n make-pot wp-content/plugins/awesome-plugin \
  wp-content/plugins/awesome-plugin/languages/awesome-plugin.pot

Questo comando analizza i file PHP e JavaScript del plugin, trova ogni __(), _e(), _n() e le chiamate correlate, e scrive un template completo. Se preferisci una via grafica, Poedit Pro può scansionare il codice sorgente nello stesso modo. In ogni caso, il risultato è un .pot contenente tutte le stringhe sorgente con traduzioni vuote, pronto per essere trasformato in un vero file di lingua.

Generare il tuo template ha un beneficio nascosto: cattura le stringhe che lo sviluppatore originale potrebbe aver dimenticato di includere in un .pot distribuito. I plugin si evolvono rapidamente, e un template fornito con la versione 2.1 potrebbe mancare di stringhe aggiunte nella 2.4. Rigenerare dalla sorgente attuale garantisce che il tuo catalogo rifletta ciò che il plugin visualizza effettivamente oggi, non ciò che visualizzava due versioni fa. Se mantieni le traduzioni per un plugin nel tempo, eseguire di nuovo make-pot dopo ogni aggiornamento importante è un'abitudine affidabile.

Creazione dei File PO e MO con il Nome Corretto

L'errore più comune nella traduzione di un plugin è il nome del file. WordPress trova le traduzioni dei plugin abbinando un pattern molto specifico, e un carattere sbagliato significa che la tua traduzione viene completamente ignorata.

La Formula del Nome del File

Per le traduzioni dei plugin, il pattern è text-domain-locale. Quindi per il text domain awesome-plugin tradotto in tedesco, i file devono essere nominati:

awesome-plugin-de_DE.po
awesome-plugin-de_DE.mo

Il codice locale è il codice della lingua del sito WordPress: de_DE per il tedesco, fr_FR per il francese, es_ES per lo spagnolo, pt_BR per il portoghese brasiliano. Se sbagli il locale, WordPress salterà silenziosamente il tuo file. Puoi crearli dal template .pot in un editor come Poedit, che compila automaticamente il .mo binario quando salvi. Se sei nuovo a quell'editor, la guida completa a Poedit ti guida passo dopo passo nella creazione di una traduzione da un template.

Dove Posizionare i File in Modo Che gli Aggiornamenti Non Li Cancellino

Ci sono due possibili posizioni, e scegliere quella giusta è importante.

# RISKY: inside the plugin — wiped on every plugin update
wp-content/plugins/awesome-plugin/languages/awesome-plugin-de_DE.mo

# SAFE: the global languages override folder — survives updates
wp-content/languages/plugins/awesome-plugin-de_DE.mo

Usa sempre wp-content/languages/plugins/. WordPress controlla prima questa directory di override, e poiché si trova fuori dalla cartella del plugin, l'aggiornamento del plugin non tocca mai le tue traduzioni. I file posti all'interno della cartella del plugin vengono sovrascritti nel momento in cui viene installata una nuova versione.

Questo comportamento di override è una delle funzionalità più utili e meno conosciute della localizzazione di WordPress. Significa che puoi distribuire traduzioni personalizzate o corrette per qualsiasi plugin di terze parti senza mai doverlo "forkare", e le tue modifiche sono completamente sicure dagli aggiornamenti. Se gestisci diversi siti client che eseguono lo stesso plugin, puoi persino mantenere un unico set di file .mo di override e distribuirli su tutti, sapendo che ogni sito li acquisirà automaticamente purché il locale corrisponda.

Come WordPress Carica la Tua Traduzione

Un plugin pronto per la traduzione indica a WordPress di caricare il suo catalogo chiamando load_plugin_textdomain() durante l'inizializzazione:

add_action( 'init', function() {
    load_plugin_textdomain(
        'awesome-plugin',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages'
    );
} );

Per la maggior parte dei plugin moderni su WordPress 4.6 e successivi, non è necessario toccare questo. WordPress carica automaticamente le traduzioni da wp-content/languages/plugins/ purché il nome del file e il locale del sito corrispondano. Se la tua traduzione finita non appare ancora, la causa è quasi sempre una mancata corrispondenza del nome del file, un .mo obsoleto o una lingua del sito impostata su un locale errato. La nostra guida alla risoluzione dei problemi per le traduzioni non visualizzate analizza ciascuno di questi punti di fallimento.

Plugin Che Memorizzano le Stringhe nel Database

Ecco la limitazione importante. L'approccio Gettext traduce solo le stringhe che si trovano nel codice del plugin. Alcuni plugin, in particolare i costruttori di moduli, i page builder e le estensioni e-commerce, ti permettono di creare contenuti (etichette di moduli, attributi di prodotto, messaggi personalizzati) che vengono salvati nel database di WordPress. Tali stringhe sono dati generati dall'utente, non fanno parte del .pot, quindi un file .po non può raggiungerle. Per il contenuto del database hai bisogno di un plugin multilingue come WPML o Polylang, o della funzione di traduzione delle stringhe del plugin stesso. Testa sempre se una data stringa si trova nel codice o nel database prima di presumere che un file .po possa risolverla.

Un semplice test ti dice con che tipo di stringa hai a che fare. Se il testo è qualcosa che hai digitato in un campo delle impostazioni, un'etichetta di modulo che hai creato, un messaggio di ringraziamento personalizzato, un nome di prodotto, è contenuto del database e un .po non può toccarlo. Se il testo fa parte dell'interfaccia integrata del plugin, etichette di pulsanti, errori di validazione, avvisi di amministrazione forniti con il plugin stesso, si trova nel codice e un file .po è esattamente lo strumento giusto. Tracciare questa linea in anticipo ti risparmia ore di frustrazione, perché nessuna quantità di perfetta modifica .po tradurrà mai una stringa che il plugin estrae dal database in fase di esecuzione.

Tradurre su Larga Scala Senza la Fatica Manuale

Tradurre un plugin in una lingua a mano è gestibile. Tradurlo in dieci lingue, o tradurre un intero stack di plugin per un sito client, si trasforma in giorni di lavoro ripetitivo, e ogni modifica manuale rischia di confondere un placeholder come %s o %1$s e rompere l'output.

È qui che un flusso di lavoro cloud cambia le carte in tavola. Carica il .po o il .pot del plugin su SimplePoTranslate, scegli le tue lingue target, e l'IA consapevole del contesto traduce l'intero catalogo mentre il Syntax Locking blocca ogni placeholder, tag HTML e token di codice in modo che nulla possa rompersi. Lo Smart Batching gestisce grandi cataloghi in un unico passaggio, e scarichi un ZIP contenente .po, .mo, .json, .php e .xliff insieme, formattati correttamente e pronti per essere inseriti in wp-content/languages/plugins/. Funziona interamente nel cloud, quindi non c'è installazione desktop e nessun ingombro sul tuo sito.

Nota che la traduzione di un plugin differisce dalla traduzione di un tema, che utilizza una convenzione di cartelle e una funzione di caricamento leggermente diverse. Se il tuo obiettivo è un tema, segui invece la nostra guida dedicata su come localizzare qualsiasi tema WordPress anche se non sei uno sviluppatore.

Usa il percorso manuale quando hai un plugin e una lingua. Usa il cloud quando hai bisogno di molte lingue, velocemente, senza compromettere la sicurezza dei placeholder.

Pronto a tradurre il tuo plugin WordPress in ogni lingua parlata dal tuo pubblico senza rompere una singola variabile? Prova SimplePoTranslate gratuitamente — nessuna carta di credito richiesta. Il livello gratuito ti permette di tradurre il tuo primo file .po del plugin in pochi minuti, con Syntax Locking su ogni stringa.