.po vs .mo vs .pot: i file di traduzione di WordPress spiegati

Apri la cartella languages di un tema WordPress e trovi tre file che sembrano quasi identici: twentytwentyfour.pot, twentytwentyfour-de_DE.po e twentytwentyfour-de_DE.mo. Stesso tema, stessa lingua, tre estensioni diverse. Quale modifichi? Quale carica effettivamente WordPress? E perché la modifica del file sbagliato fa sparire silenziosamente le tue traduzioni?

Se ti sei mai chiesto quale file sia importante nel dibattito file .po vs .mo, non sei solo. Queste tre estensioni sono la spina dorsale di ogni sito WordPress tradotto, eppure la differenza tra loro confonde sia i principianti che gli sviluppatori esperti. Modifica il file sbagliato e i tuoi visitatori tedeschi vedranno comunque l'inglese. Modifica quello giusto ma salta un passaggio e non cambierà nulla.

Questa guida spiega esattamente cosa sono i file .pot, .po e .mo, come si relazionano all'interno del flusso di lavoro GNU Gettext, dove risiedono in WordPress e perché non dovresti mai aprire un file .mo in un editor di testo. Alla fine saprai quale file toccare e quale lasciare in pace.

Cosa sono i file .pot, .po e .mo?

In breve: un file .pot è il modello vuoto, un file .po è la tua traduzione modificabile e un file .mo è il binario compilato che WordPress legge in fase di esecuzione. Formano una catena, e ogni anello ha esattamente un compito.

Questi tre formati provengono tutti da GNU Gettext, il sistema di localizzazione su cui si basano WordPress, Drupal e migliaia di progetti PHP e C. Gettext separa le stringhe sorgente scritte da uno sviluppatore dalle traduzioni fornite da un traduttore, in modo che lo stesso codice possa parlare decine di lingue senza toccare una singola riga di PHP.

Pensala come una scheda di ricetta. Il .pot è la scheda vuota con gli spazi per gli ingredienti ma senza quantità. Il .po è la scheda compilata per un piatto specifico. Il .mo è la copia laminata, scansionabile dalla macchina, che la cucina usa effettivamente durante il servizio. Tu scrivi sulla scheda di carta; non scarabocchi mai su quella laminata.

Il file .pot: il modello principale

Un file .pot (Portable Object Template) contiene ogni stringa traducibile in un tema o plugin con le traduzioni lasciate vuote. È l'elenco principale che gli sviluppatori distribuiscono in modo che i traduttori sappiano esattamente cosa deve essere tradotto. Le righe msgstr sono vuote perché non è stata ancora scelta alcuna lingua.

#: includes/checkout.php:42
msgid "Add to Cart"
msgstr ""

#: includes/account.php:108
msgid "Your order has been shipped to %s"
msgstr ""

Nota la riga msgstr "" vuota. Un .pot è un modello, non una traduzione. Lo copi una volta per lingua e riempi gli spazi vuoti. Raramente modifichi un .pot a mano; viene rigenerato dal codice sorgente ogni volta che le stringhe cambiano.

Il file .po: la tua traduzione modificabile manualmente

Un file .po (Portable Object) è una copia del .pot con le righe msgstr compilate per una lingua. Questo è il file che traduttori e sviluppatori modificano effettivamente. È un testo semplice, leggibile dall'uomo e compatibile con il controllo di versione.

#: includes/checkout.php:42
msgid "Add to Cart"
msgstr "In den Warenkorb"

#: includes/account.php:108
msgid "Your order has been shipped to %s"
msgstr "Ihre Bestellung wurde an %s versandt"

Il msgid è la stringa sorgente originale in inglese e non deve mai cambiare. Il msgstr è la tua traduzione. Il %s è un segnaposto che deve sopravvivere intatto nella traduzione — eliminarlo o riordinarlo è la causa più comune di layout rotti, che trattiamo in dettaglio in come tradurre file PO senza rompere le variabili del codice.

Il file .mo: il binario compilato

Un file .mo (Machine Object) è la versione compilata e binaria del tuo .po. WordPress non può leggere i file .po in modo efficiente in fase di esecuzione, quindi carica invece il .mo pre-compilato. L'apertura di un .mo in un editor di testo mostra byte illeggibili — è destinato alle macchine, non alle persone.

Quando WordPress chiama load_textdomain() o load_theme_textdomain(), cerca un file .mo, analizza la sua tabella hash binaria e sostituisce ogni msgid con il msgstr corrispondente al volo. Questo formato binario rende le ricerche veloci anche su siti con migliaia di stringhe.

Come si relazionano i tre file nel flusso di lavoro Gettext?

Formano una pipeline unidirezionale: il codice sorgente diventa un .pot, il .pot diventa un .po per lingua e ogni .po compila in un .mo. Le traduzioni scorrono sempre a valle.

Ecco il ciclo di vita completo in ordine:

1. Uno sviluppatore racchiude le stringhe rivolte all'utente in funzioni Gettext come __() e _e() all'interno del sorgente PHP.
2. Uno strumento di scansione legge il sorgente e genera il modello .pot contenente ogni stringa racchiusa.
3. Un traduttore copia il .pot in un .po specifico per lingua (ad esempio de_DE.po) e compila ogni msgstr.
4. Il .po completato viene compilato in un binario .mo.
5. WordPress carica il .mo in fase di esecuzione e visualizza il sito tradotto.

Quando lo sviluppatore aggiunge nuove stringhe in seguito, il .pot viene rigenerato, le nuove voci vengono unite in ogni .po esistente (mantenendo le vecchie traduzioni), il traduttore colma le lacune e il .po viene ricompilato in .mo. Il ciclo si ripete per tutta la durata del progetto.

Il punto cruciale: modifica il .po, quindi compila in .mo. Non modificare mai direttamente il .mo e non tradurre mai all'interno del .pot. Se desideri una panoramica più approfondita, la guida definitiva alla localizzazione di WordPress illustra l'intera pipeline con esempi.

Convenzioni di denominazione e dove si trovano i file

WordPress è rigoroso sui nomi dei file. Se sbagli la denominazione, il tuo .mo perfettamente tradotto verrà semplicemente ignorato, perché WordPress cerca una corrispondenza esatta basata sul dominio del testo e sulla locale.

Il modello di denominazione per le traduzioni di temi e plugin è:

# Pattern: textdomain-locale.po / .mo
twentytwentyfour-de_DE.po      # German (Germany) translation
twentytwentyfour-de_DE.mo      # compiled binary WordPress loads
twentytwentyfour-fr_FR.po      # French (France)
twentytwentyfour.pot           # template, no locale suffix

Il textdomain corrisponde alla stringa passata come secondo argomento alle funzioni Gettext come __( 'Add to Cart', 'twentytwentyfour' ). La locale è un codice locale di WordPress come de_DE, fr_FR o pt_BR. Il modello .pot non ha un suffisso locale perché è indipendente dalla lingua.

La posizione è altrettanto importante quanto la denominazione. WordPress cerca in alcuni percorsi prevedibili:

• Le traduzioni dei temi vengono fornite nella cartella wp-content/themes/your-theme/languages/ del tema.
• Le traduzioni dei plugin vengono fornite in wp-content/plugins/your-plugin/languages/.
• Le traduzioni da translate.wordpress.org e le sovrascritture utente finiscono nelle directory globali wp-content/languages/themes/ e wp-content/languages/plugins/, che hanno priorità e sopravvivono agli aggiornamenti.

Metti un de_DE.mo correttamente nominato nella cartella giusta e i visitatori tedeschi vedranno il tedesco. Mettilo una cartella troppo in profondità, o scrivi male il dominio del testo, e WordPress tornerà silenziosamente all'inglese senza messaggi di errore. Se le tue traduzioni non vengono visualizzate, una mancata corrispondenza del nome o del percorso è il solito colpevole, e la guida alla risoluzione dei problemi per le traduzioni mancanti copre ogni causa comune.

Perché non dovresti mai modificare direttamente un file .mo

Poiché un .mo è un binario compilato, non esiste un modo sicuro per modificarlo a mano — e qualsiasi modifica che forzi verrà sovrascritta la prossima volta che il .po verrà ricompilato. Il .po è la fonte della verità; il .mo è un artefatto di build usa e getta.

Questa singola regola spiega una grande parte dei ticket di supporto "la mia traduzione è cambiata ma il sito non si è aggiornato". Qualcuno modifica una stringa, salva il .po e si dimentica di ricompilare il .mo. WordPress continua a caricare il vecchio binario, quindi la nuova formulazione non appare mai. La soluzione è sempre: modifica .po, ricompila in .mo, ricarica.

C'è una seconda ragione per cui la regola è importante: i file .mo non sono 'diff-friendly' nel controllo di versione. Poiché sono binari, una piccola modifica del testo produce un blob opaco nella cronologia Git che nessun revisore può leggere. Mantenere il .po come fonte di verità tracciata e trattare il .mo come un artefatto generato mantiene il tuo repository revisionabile e le tue traduzioni verificabili.

Fare questo manualmente su decine di lingue è noioso e soggetto a errori. È qui che un flusso di lavoro cloud risparmia tempo reale. Strumenti come SimplePoTranslate traducono le tue stringhe .po e restituiscono un singolo ZIP contenente il .po e .mo corrispondenti insieme — già compilati, denominati correttamente, pronti per essere inseriti in wp-content/languages/. Non c'è nulla da compilare manualmente e nessuna possibilità di avere un .mo obsoleto.

Applica anche il blocco della sintassi (Syntax Locking), che blocca ogni segnaposto come %s, %1$s e {name}, oltre ai tag HTML, prima della traduzione. Le tue variabili sopravvivono intatte, quindi non spedisci mai un .mo che rompe un layout. E poiché funziona interamente nel cloud, non c'è nessun plugin aggiuntivo che appesantisce il tuo sito — carichi un file e scarichi traduzioni finite e compilate.

Mettendo tutto insieme

Una volta che la distinzione file .po vs .mo diventa chiara, l'intero sistema di traduzione di WordPress smette di sembrare misterioso. Il .pot è il modello dello sviluppatore, il .po è la copia di lavoro modificabile del traduttore e il .mo è il binario compilato che WordPress serve effettivamente ai visitatori. Le traduzioni scorrono in un'unica direzione — dal modello al .po al .mo — e si modifica manualmente solo quello intermedio.

Ricorda le tre regole che prevengono il novanta percento dei mal di testa legati alla traduzione: non tradurre mai all'interno di un .pot, ricompilare sempre il .mo dopo aver modificato un .po e far corrispondere esattamente la denominazione textdomain-locale. Segui queste regole e le tue stringhe tradotte appariranno ogni volta.

Pronto a smettere di lottare con la compilazione e la denominazione manuale dei file di traduzione? Prova SimplePoTranslate gratuitamente — nessuna carta di credito richiesta. Carica il tuo .po o .pot e ottieni un pacchetto .po + .mo pronto all'uso sul piano gratuito in pochi minuti.