PTC
Registrati Passa a Pro Il tuo account

Le traduzioni del plugin WordPress non vengono visualizzate? Risolvi il problema delle traduzioni mancanti

Mancano delle traduzioni dopo un'esecuzione di PTC? Quattro controlli permettono di individuare quasi ogni causa. Verifica che la stringa sia arrivata a PTC, che il nome del file .mo corrisponda a quello previsto da WordPress e che il text domain sia coerente in tutto il tuo codice. Questa guida illustra ogni controllo nell'ordine in cui eseguirlo.

Lo stesso ordine diagnostico funziona sia che tu abbia tradotto con PTC (Private Translation Cloud), GlotPress o qualsiasi altro strumento basato su gettext. Le modalità di errore sono intrinseche alla pipeline i18n di WordPress, non a un traduttore in particolare.

Conferma che la stringa sia arrivata a PTC

La prima domanda è se la stringa si trova nel tuo progetto PTC. Se una stringa non è stata estratta nel tuo file .pot, PTC non l'ha mai vista. Il file .po non ha alcuna traduzione per essa. Il plugin in esecuzione mostra il fallback della lingua di origine.

Come verificare:

  1. Apri la stringa interessata nel plugin in esecuzione e copia il suo testo esatto.
  2. Vai al tuo pannello di controllo di PTC, apri la scheda Translations e cerca la stringa.
  3. Se non c'è, PTC non l'ha mai ricevuta.

Di seguito sono riportate tre cause comuni.

Causa 1: la stringa manca dal tuo file POT

wp i18n make-pot estrae solo le stringhe all'interno delle funzioni i18n riconosciute. Questo significa __(), _e(), _n(), _x() e le varianti con escape, con il text domain corretto. Le stringhe all'interno del dominio sbagliato vengono ignorate. Le stringhe hardcoded al di fuori di una funzione i18n vengono ignorate.

Esegui nuovamente l'estrazione e verifica che la stringa sia ora nel .pot:

wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin
grep "Save Changes" languages/my-plugin.pot

Se grep restituisce la stringa con un msgid, l'estrazione funziona. Ricarica il nuovo .pot su PTC e ritraduci. Se grep non restituisce nulla, la stringa è hardcoded e non è racchiusa in __(). Questo è il tuo bug. Racchiudi la stringa e ripeti l'estrazione.

Causa 2: il testo non è racchiuso in una funzione gettext

Ogni stringa traducibile nel tuo codice ha bisogno di un wrapper. Usa __(), esc_html__(), _e(), _n() o _x() con il text domain corretto:

__( 'Hello, world!', 'your-plugin' );

Causa 3: le stringhe JavaScript non sono state contrassegnate come traducibili

Se il tuo plugin include testo traducibile in JavaScript:

  1. Nel pannello di controllo di PTC, vai su Settings > Monitored Files.
  2. Modifica il file di risorse pertinente e abilita “Is this a WordPress project with localizable JavaScript?”

Questo indica a PTC di scansionare i file JavaScript alla ricerca di stringhe traducibili. PTC rigenera le traduzioni e apre un nuovo merge request con i file aggiornati.

Quindi assicurati che WordPress sappia dove caricare i file di traduzione .json prodotti da PTC. Richiama wp_set_script_translations() con il percorso corretto:

// For plugins
wp_set_script_translations(
    'script-handle',
    'text-domain',
    plugin_dir_path( __FILE__ ) . 'languages'
);

// For themes
wp_set_script_translations(
    'script-handle',
    'text-domain',
    get_template_directory() . '/languages'
);

Questo indica a WordPress di caricare i file .json dalla cartella del tuo plugin o tema.

Conferma che WordPress stia caricando il tuo file .mo

Se la stringa è in PTC e il file .mo esiste nella directory languages/ del tuo plugin ma il plugin visualizzato mostra ancora l'inglese, WordPress non riesce a caricare il .mo.

Diagnostica 1: il locale del sito è impostato correttamente? Vai su Impostazioni > Generali > Lingua del sito in wp-admin e conferma che corrisponda alla tua lingua di destinazione. Ad esempio, impostalo su «Español» per testare lo spagnolo. Se il sito è in inglese, il tuo .mo spagnolo non verrà mai caricato. Questo non è un bug.

Diagnostica 2: load_plugin_textdomain() è effettivamente in esecuzione? Aggiungi una riga di debug temporanea:

add_action( 'init', function() {
    $loaded = load_plugin_textdomain(
        'my-plugin',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages'
    );
    error_log( 'my-plugin textdomain loaded: ' . var_export( $loaded, true ) );
} );

Ricarica una pagina e controlla il tuo log degli errori PHP. loaded: true significa che WordPress ha trovato e caricato un file .mo per il locale corrente. loaded: false significa che non lo ha fatto. La causa di solito è una mancata corrispondenza del nome del file (vedi la sezione successiva) o un percorso della directory errato.

Diagnostica 3: il tempismo dell'hook è corretto? load_plugin_textdomain() deve essere eseguito sull'hook init. Quello è l'hook canonico affinché le traduzioni si applichino alle stringhe stampate a schermo durante la normale elaborazione della richiesta.

Diagnostica 4: le traduzioni della community stanno avendo la precedenza sui tuoi file inclusi nel bundle? Per impostazione predefinita, WordPress dà priorità ai file di traduzione archiviati in /wp-content/languages/. Se il tuo plugin o tema ha traduzioni fornite dalla community su WordPress.org, quei file possono avere la precedenza sui file .mo inclusi nel bundle con il tuo progetto. Per evitare che ciò accada, usa il filtro load_textdomain_mofile per forzare il caricamento del percorso del tuo file nel bundle prima che WordPress controlli la directory globale. I progetti multi-text-domain (un plugin che incorpora un altro plugin) necessitano che ogni dominio venga caricato separatamente. Ogni dominio ha bisogno della propria chiamata load_plugin_textdomain() o load_theme_textdomain().

Assicurati che il nome del file MO corrisponda al pattern di ricerca di WordPress

La ricerca dei file .mo di WordPress segue una rigorosa convenzione di denominazione. Basta un solo carattere sbagliato e WordPress esegue silenziosamente il fallback all'inglese.

La convenzione dipende da dove posizioni il file:

Posizione Pattern Esempio
/languages/ del plugin {text-domain}-{locale}.mo my-plugin-de_DE.mo
/languages/ del tema {locale}.mo de_DE.mo
Directory globale (/wp-content/languages/...) {text-domain}-{locale}.mo my-theme-de_DE.mo

Alcuni esempi pratici:

  • my-plugin-es_ES.mo per lo spagnolo (Spagna)
  • my-plugin-fr_FR.mo per il francese (Francia)
  • my-plugin-pt_BR.mo per il portoghese (Brasile)
  • my-plugin-zh_CN.mo per il cinese semplificato
  • my-plugin-ja.mo per il giapponese (alcuni locale non hanno il suffisso della regione)

Errori comuni:

  • Prefisso del text domain errato. Se l'intestazione Text Domain del tuo plugin è my-plugin ma il .mo si chiama myplugin-es_ES.mo (senza trattino), WordPress non lo troverà. Il prefisso deve corrispondere esattamente al valore Text Domain.
  • Codice del locale errato. es.mo invece di es_ES.mo. WordPress utilizza i codici dei locale regionali. es_ES, es_MX e es_AR sono file diversi. Un semplice codice della lingua funziona solo quando non esiste alcun file regionale.
  • Trattino contro trattino basso (underscore). I codici dei locale usano il trattino basso (es_ES), mai il trattino (es-ES). Questo trae in inganno gli sviluppatori che copiano i codici dei locale dalle intestazioni Accept-Language del browser o dalle fonti BCP 47, dove il trattino è lo standard.
  • Directory errata. L'intestazione Domain Path deve puntare alla directory che contiene i tuoi file .mo. Se Domain Path è /languages e i tuoi file .mo si trovano in /lang/, WordPress non li troverà.

Verifica confrontando l'elenco dei file prodotti da PTC con il locale che il tuo sito sta utilizzando:

ls plugins/my-plugin/languages/
# my-plugin-es_ES.mo
# my-plugin-es_ES.po
# my-plugin-fr_FR.mo
# my-plugin-fr_FR.po

Se i nomi sembrano corretti ma le traduzioni continuano a non caricarsi, esegui la diagnostica load_plugin_textdomain() riportata sopra per confermare che WordPress stia trovando la directory.

Verifica che il tuo text domain sia coerente in tutto il tuo codice

Questo è il killer silenzioso. Ogni chiamata __(), _e(), _n(), _x() nel tuo codice passa un text domain come ultimo argomento. Se anche una sola chiamata passa il dominio sbagliato, quella singola stringa non verrà tradotta. Ogni altra stringa nel plugin funzionerà correttamente.

// Correct - matches the plugin's Text Domain
$correct = __( 'Save Changes', 'my-plugin' );

// Wrong - text domain typo; this string is never translated
$wrong = __( 'Save Changes', 'myplugin' );  // missing hyphen

// Wrong - copy-pasted from another plugin
$wrong = __( 'Save Changes', 'other-plugin' );

// Wrong - WordPress core domain; works for core strings but not yours
$wrong = __( 'Save Changes', 'default' );

Trova le incoerenze usando grep sulla tua codebase:

grep -rE "__\(|_e\(|_n\(|_x\(" --include="*.php" .

Controlla l'ultimo argomento di ogni corrispondenza. Dovrebbe essere sempre il text domain del tuo plugin. Se trovi errori di battitura o di copia-incolla, correggili ed esegui di nuovo wp i18n make-pot per aggiornare il .pot.

Per il codice JavaScript che utilizza @wordpress/i18n, si applica la stessa regola. Anche wp_set_script_translations() in PHP deve passare il dominio corrispondente:

wp_set_script_translations( 'my-plugin-editor', 'my-plugin', '...' );
//                                                ^^^^^^^^^^^
//                                                Must match the JS calls

Individua gli stessi problemi prima del rilascio con AI Visual QA

Il ciclo diagnostico descritto sopra è reattivo. Manca una traduzione e devi andare a caccia della causa. L'AI Visual QA di PTC individua gli stessi problemi prima che vengano rilasciati. Ispeziona il plugin visualizzato in ogni lingua di destinazione dopo ogni aggiornamento delle traduzioni e segnala cosa manca o è sbagliato.

Per una stringa inglese hardcoded al di fuori di __() (Causa 1 qui sopra), l'AI Visual QA vede la stringa non tradotta nel plugin visualizzato. PTC genera un prompt pronto da incollare per Cursor o Claude Code per racchiudere la stringa in __(). Per una mancata corrispondenza del text domain (il controllo della sezione precedente), vede la stringa non tradotta quando altre stringhe sulla stessa schermata sono tradotte e segnala l'incoerenza.

Se non hai ancora abilitato l'AI Visual QA, consulta il tutorial su temi e plugin di WordPress per la configurazione.

Quando tutti e quattro i controlli vengono superati e le traduzioni mancano ancora

Se hai eseguito tutti e quattro i controlli e le traduzioni continuano a non essere visualizzate, invia un'email all'assistenza PTC con:

  • Il text domain del tuo plugin.
  • Uno dei nomi dei file .mo (ad es. my-plugin-es_ES.mo).
  • Una schermata del pannello di controllo di PTC che mostra la stringa interessata con la sua traduzione.
  • L'impostazione della lingua del sito da Impostazioni > Generali.

La maggior parte dei casi di «traduzione mancante» si riconduce a una delle cause precedenti. I casi limite (versioni specifiche di WordPress, risoluzione del locale in MultiSite, conflitto con un altro plugin i18n) a volte richiedono un esame più approfondito.

Mantieni le release future sincronizzate con la localizzazione continua

Una volta che le tue traduzioni si caricano correttamente, imposta il workflow di localizzazione continua in modo che le release future rimangano sincronizzate con le tue traduzioni: automaticamente, a ogni push su main.