Come creare un file .pot per un tema o un plugin

Hai appena finito un plugin WordPress che vuoi condividere con il mondo. Il codice funziona, le funzionalità sono solide e qualcuno in Germania ti invia un'email chiedendoti come tradurlo in tedesco. Li indirizzi alla cartella languages e ti rendi conto che non c'è niente lì. Nessun template, nessuna stringa, nessun modo per un traduttore di sapere cosa deve essere tradotto. Il tuo plugin è tecnicamente "pronto per la traduzione" solo di nome.

Ogni progetto WordPress traducibile inizia con un file: il template .pot. Prima che chiunque possa produrre una versione tedesca, francese o giapponese, devi creare un file POT che elenchi ogni stringa rivolta all'utente presente nel tuo codice. Salta questo passaggio e i traduttori saranno costretti a leggere il tuo codice sorgente riga per riga, cercando di indovinare quali stringhe dovrebbero essere visibili.

Questa guida illustra le due metà del lavoro: preparare il tuo codice sorgente in modo che le stringhe siano individuabili e quindi generare il .pot stesso con tre diversi strumenti. Useremo WP-CLI, Poedit e l'approccio legacy makepot/grunt, con comandi reali che puoi copiare. Alla fine avrai un template pulito pronto da consegnare a qualsiasi traduttore.

Primo passaggio: contrassegna le tue stringhe come traducibili

Prima di poter creare un file POT, ogni stringa che un utente potrebbe vedere deve essere racchiusa in una funzione Gettext. Uno scanner può estrarre solo le stringhe che riconosce, e le riconosce tramite queste chiamate di funzione — i letterali stringa semplici gli sono invisibili.

WordPress fornisce una famiglia di funzioni di localizzazione, ciascuna per un contesto leggermente diverso:

// Return a translated string
$label = __( 'Add to Cart', 'my-plugin' );

// Echo a translated string directly
_e( 'Your cart is empty', 'my-plugin' );

// Translate with context to disambiguate identical words
$verb = _x( 'Post', 'verb: to publish', 'my-plugin' );

// Translate AND escape for safe HTML output
echo esc_html__( 'Welcome back', 'my-plugin' );

Il secondo argomento in ogni chiamata — 'my-plugin' — è il dominio di testo. Raggruppa tutte le stringhe di un plugin o tema sotto un unico namespace in modo che WordPress sappia quale file .mo caricare per esse. Ogni stringa traducibile nel tuo progetto deve condividere esattamente lo stesso dominio di testo, altrimenti alcune stringhe non verranno mai tradotte.

Usa _x() ogni volta che una parola è ambigua. L'inglese "Post" può essere un sostantivo o un verbo, e molte lingue li traducono in modo diverso. Le stringhe di contesto permettono ai traduttori di distinguerli. E scegli le varianti esc_html__() ed esc_attr__() ogni volta che la stringa tradotta viene stampata in HTML, così rimani sicuro e localizzato allo stesso tempo.

Ci sono alcune abitudini che mantengono le tue stringhe estraibili. Passa sempre un letterale stringa semplice come primo argomento — mai una variabile o una concatenazione come __( 'Hello ' . $name, 'my-plugin' ), perché lo scanner legge il testo sorgente staticamente e non può risolvere i valori in fase di esecuzione. Per le frasi con un numero, usa _n() in modo che le forme plurali vengano catturate correttamente, e per le frasi con un valore dinamico, usa sprintf() attorno a un placeholder come %s piuttosto che unire le stringhe. La coerenza qui è ciò che fa sì che il passaggio successivo — la generazione del template — produca un risultato completo e utilizzabile.

Secondo passaggio: dichiara il dominio di testo nell'intestazione

WordPress ha bisogno di due campi nell'intestazione per sapere dove si trovano le tue traduzioni: il Dominio di Testo e il Percorso del Dominio. Impostali nel file principale del tuo plugin o nel style.css del tuo tema, e WordPress caricherà automaticamente il .mo corretto in fase di esecuzione.

<?php
/**
 * Plugin Name:       My Plugin
 * Description:        A perfectly localized WordPress plugin.
 * Version:            1.0.0
 * Requires at least: 6.4
 * Text Domain:       my-plugin
 * Domain Path:       /languages
 */

Il Dominio di Testo deve corrispondere alla stringa che hai passato a ogni chiamata __() e _e() — my-plugin qui. Il Percorso del Dominio indica a WordPress quale sottocartella contiene i file di traduzione, rispetto alla radice del plugin o del tema. La convenzione è /languages, ed è esattamente dove dovrebbe risiedere il tuo .pot generato.

Con le stringhe racchiuse e l'intestazione dichiarata, il tuo codice è pronto per essere scansionato. Il quadro più ampio della preparazione di un progetto per la traduzione — inclusi temi che non sono i tuoi — è trattato in come localizzare qualsiasi tema WordPress anche se non sei uno sviluppatore.

Come si genera il file .pot? Tre metodi

Si genera un .pot eseguendo uno scanner sul tuo codice sorgente che trova ogni chiamata Gettext e scrive le stringhe in un template. Ecco tre modi affidabili per farlo, dal default moderno all'approccio legacy.

Metodo 1: WP-CLI (consigliato)

Il modo ufficiale e moderno per creare un file POT è WP-CLI con il comando i18n. Viene fornito come parte degli strumenti principali di WordPress, comprende le stringhe PHP e JavaScript e produce un template conforme agli standard in una sola riga.

# Run from your plugin or theme root directory
wp i18n make-pot . languages/my-plugin.pot

# Add a text domain explicitly if auto-detection misses it
wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin

# Scan only specific paths and exclude vendor folders
wp i18n make-pot . languages/my-plugin.pot --exclude=vendor,node_modules

Il primo argomento è la directory sorgente (. per la cartella corrente), e il secondo è il percorso di output. WP-CLI analizza i tuoi file, estrae ogni stringa racchiusa, registra il file sorgente e il numero di riga come commento, e scrive il .pot. È veloce, scriptabile e la scelta giusta per qualsiasi progetto serio.

Il template generato include utili metadati che puoi personalizzare con flag aggiuntivi. Passa --headers per impostare il nome del progetto, la versione e l'indirizzo di contatto dei traduttori, in modo che il blocco di intestazione del .pot sia compilato correttamente anziché lasciato come placeholder. WP-CLI estrae automaticamente anche le stringhe JavaScript dalle chiamate wp_set_script_translations(), il che è importante per i temi a blocchi moderni e i plugin Gutenberg dove metà del testo rivolto all'utente risiede in JavaScript anziché in PHP. Un solo comando copre entrambi i mondi.

Metodo 2: Poedit (grafico)

Se preferisci un'applicazione desktop, Poedit può scansionare la tua sorgente e generare il template tramite la sua interfaccia. Apri Poedit, scegli di creare una nuova traduzione da POT o di scansionare direttamente le sorgenti, indirizzalo alla cartella del tuo progetto e configura le parole chiave sorgente (__, _e, _x, esc_html__) nelle proprietà del catalogo.

Le funzionalità di scansione delle sorgenti e generazione .pot di Poedit risiedono nella sua edizione Pro, ma il flusso di lavoro è amichevole per gli sviluppatori che preferirebbero cliccare piuttosto che digitare comandi. È anche un solido editor per la fase di traduzione successiva. Poedit e diverse altre opzioni desktop sono confrontate in i 5 migliori strumenti gratuiti per modificare e tradurre file PO su Mac e Windows.

Metodo 3: makepot / grunt (legacy)

Prima di WP-CLI, lo strumento standard era lo script makepot.php dal repository WordPress i18n-tools, spesso integrato in un task di build di Grunt con grunt-wp-i18n. Lo incontrerai ancora in plugin e temi più vecchi.

# Legacy makepot.php invocation
php makepot.php wp-plugin /path/to/my-plugin languages/my-plugin.pot

Funziona, ma non è mantenuto rispetto a WP-CLI ed è più lento da configurare. Usalo solo quando stai mantenendo un progetto legacy che già ne dipende; per qualsiasi cosa di nuovo, preferisci wp i18n make-pot.

Mantieni il template aggiornato man mano che il codice cambia

Un .pot è un'istantanea delle tue stringhe in un dato momento. Ogni volta che aggiungi una funzionalità, modifichi un'etichetta o correggi un errore di battitura in una stringa visibile, il template diventa obsoleto e i traduttori perdono la nuova formulazione.

Rendi la rigenerazione parte della tua routine di rilascio. Esegui nuovamente wp i18n make-pot prima di ogni aumento di versione, quindi unisci il template aggiornato nelle traduzioni esistenti con wp i18n update-po o msgmerge in modo che i traduttori mantengano il loro lavoro finito e vedano solo le nuove lacune. Tratta il .pot come un artefatto di build che rigeneri, non un file che modifichi manualmente.

Un template obsoleto causa un fallimento sottile e frustrante: nuove stringhe appaiono in inglese anche su un sito "completamente tradotto", perché non sono mai state nel .pot da cui ha lavorato il traduttore. Catturare questo è semplice come scriptare la rigenerazione nel tuo build, in modo che il template non possa mai rimanere indietro rispetto al codice. Alcuni team aggiungono un controllo CI che fa fallire il build se la rigenerazione del .pot produce una differenza, garantendo che il template committato corrisponda sempre alla sorgente attuale.

Una volta che i traduttori restituiscono i file .po finiti, questi devono ancora essere compilati nel .mo binario che WordPress carica effettivamente — e se preferisci saltare l'intero ciclo di download-traduzione-ricompilazione, uno strumento cloud può gestirlo end-to-end. SimplePoTranslate accetta direttamente il tuo .pot, lo traduce con un'IA contestuale che comprende il significato di ogni stringa nella tua interfaccia, e restituisce un singolo ZIP con i file .po, .mo e altro già creati e nominati. La sua Sintassi Bloccata congela i placeholder come %s e %1$s in modo che le tue variabili non si rompano mai nella traduzione.

Conclusione

Per creare un file POT nel modo giusto, prima rendi il tuo codice individuabile — racchiudi ogni stringa visibile in __(), _e(), _x() o una variante di escaping, tutte condividendo un unico dominio di testo, e dichiara quel dominio più il Domain Path nella tua intestazione. Quindi genera il template con WP-CLI per i nuovi progetti, Poedit se preferisci una GUI, o makepot solo quando mantieni codice legacy.

Genera presto, rigenera spesso e non lasciare mai che il tuo template rimanga indietro rispetto al tuo codice. Un .pot aggiornato è la differenza tra un plugin genuinamente pronto per il mondo e uno che solo pretende di esserlo.

Pronto a trasformare il tuo template .pot in traduzioni finite senza il faticoso processo di compilazione manuale? Prova SimplePoTranslate gratuitamente — non è richiesta alcuna carta di credito. Carica il tuo template nel piano gratuito e scarica i file di traduzione pronti per la spedizione in pochi minuti.