PTC
Registrati Passa a Pro Il suo account

Le traduzioni del plugin WordPress non compaiono? Risolvere le traduzioni mancanti

Traduzioni mancanti dopo un'esecuzione di PTC? Tre controlli individuano quasi ogni causa. Verifichi che la stringa abbia raggiunto PTC, che il nome del file .mo corrisponda a ciò che WordPress si aspetta e che il dominio di testo sia coerente in tutto il Suo codice. Questa guida illustra ogni controllo nell'ordine in cui eseguirlo.

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

Confermi che la stringa abbia raggiunto PTC

La prima domanda è se la stringa si trovi nel Suo progetto PTC. Se una stringa non è stata estratta nel Suo file .pot, PTC non l'ha mai vista. Il file .po non ha alcuna traduzione per essa. Il plugin in esecuzione mostra il ripiego sulla lingua di partenza.

Come controllare:

  1. Apra la stringa interessata nel plugin in esecuzione e copi il suo testo esatto.
  2. Vada alla Sua dashboard PTC, apra la scheda Translations e cerchi la stringa.
  3. Se non è presente, PTC non l'ha mai ricevuta.

Seguono tre cause comuni.

Causa 1: la stringa manca nel Suo file POT

wp i18n make-pot estrae solo le stringhe all'interno delle funzioni i18n riconosciute. Ciò significa __(), _e(), _n(), _x() e le varianti con escape, con il dominio di testo corretto. Le stringhe nel dominio sbagliato vengono ignorate. Le stringhe codificate in modo fisso al di fuori di una funzione i18n vengono ignorate.

Riesegua l'estrazione e verifichi 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. Ricarichi il nuovo .pot su PTC e ritraduca. Se grep non restituisce nulla, la stringa è codificata in modo fisso e non è racchiusa in __(). Questo è il Suo bug. Racchiuda la stringa ed esegua di nuovo l'estrazione.

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

Ogni stringa traducibile nel Suo codice ha bisogno di un wrapper. Usi __(), esc_html__(), _e(), _n() o _x() con il dominio di testo corretto:

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

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

Se il Suo plugin include testo traducibile in JavaScript:

  1. Nella dashboard PTC, vada in Settings > Monitored Files.
  2. Modifichi il file di risorse pertinente e abiliti "Is this a WordPress project with localizable JavaScript?"

Questo indica a PTC di analizzare i file JavaScript alla ricerca di stringhe traducibili. PTC rigenera le traduzioni e apre una nuova merge request con i file aggiornati.

Si assicuri poi che WordPress sappia dove caricare i file di traduzione .json che PTC ha prodotto. Chiami 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 Suo plugin o tema.

Confermi che WordPress stia caricando il Suo file .mo

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

Diagnostica 1: la lingua del sito è impostata correttamente? Vada in Settings > General > Site Language in wp-admin e confermi che corrisponda alla Sua lingua di destinazione. Per esempio, la imposti su "Espanol" per testare lo spagnolo. Se il sito è in inglese, il Suo .mo spagnolo non verrà mai caricato. Questo non è un bug.

Diagnostica 2: load_plugin_textdomain() viene effettivamente eseguito? Aggiunga 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 ) );
} );

Ricarichi una pagina e controlli il Suo log degli errori PHP. loaded: true significa che WordPress ha trovato e caricato un file .mo per la lingua corrente. loaded: false significa che non l'ha fatto. La causa è di solito una discrepanza nel nome del file (vedi la sezione successiva) o un percorso di directory errato.

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

Diagnostica 4: le traduzioni della community sovrascrivono i Suoi file inclusi? Per impostazione predefinita, WordPress dà priorità ai file di traduzione memorizzati in /wp-content/languages/. Se il Suo plugin o tema ha traduzioni fornite dalla community su WordPress.org, quei file possono sovrascrivere i file .mo inclusi nel Suo progetto. Per evitarlo, usi il filtro load_textdomain_mofile per forzare il caricamento del percorso del Suo file incluso prima che WordPress controlli la directory globale. I progetti con più domini di testo (un plugin che ne incorpora un altro) richiedono che ogni dominio venga caricato separatamente. Ogni dominio ha bisogno della propria chiamata load_plugin_textdomain() o load_theme_textdomain().

Si assicuri che il nome del file MO corrisponda allo schema di ricerca di WordPress

La ricerca dei file .mo di WordPress segue una rigida convenzione di denominazione. Anche un solo carattere fuori posto e WordPress ripiega silenziosamente sull'inglese.

La convenzione dipende da dove colloca il file:

Posizione Schema 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 concreti:

  • 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 (alcune lingue non hanno suffisso di regione)

Errori comuni:

  • Prefisso del dominio di testo errato. Se l'intestazione Text Domain del Suo 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 di Text Domain.
  • Codice di lingua errato. es.mo invece di es_ES.mo. WordPress usa codici di lingua regionali. es_ES, es_MX ed es_AR sono file diversi. Un codice di lingua semplice funziona solo quando non esiste alcun file regionale.
  • Trattino vs trattino basso. I codici di lingua usano il trattino basso (es_ES), mai il trattino (es-ES). Questo fa inciampare gli sviluppatori che copiano i codici di lingua dalle intestazioni Accept-Language del browser o da fonti BCP 47, dove il trattino è lo standard.
  • Directory errata. L'intestazione Domain Path deve puntare alla directory che contiene i Suoi file .mo. Se Domain Path è /languages e i Suoi file .mo si trovano in /lang/, WordPress non li troverà.

Controlli elencando i file prodotti da PTC rispetto alla lingua che il Suo sito sta usando:

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, esegua la diagnostica load_plugin_textdomain() sopra per confermare che WordPress trovi la directory.

Verifichi che il Suo dominio di testo sia coerente in tutto il Suo codice

Questo è l'assassino silenzioso. Ogni chiamata __(), _e(), _n(), _x() nel Suo codice passa un dominio di testo come ultimo argomento. Se anche una sola chiamata passa il dominio sbagliato, quell'unica stringa non verrà tradotta. Ogni altra stringa nel plugin funzionerà perfettamente.

// 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' );

Trovi le incoerenze cercando nella Sua base di codice:

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

Guardi l'ultimo argomento di ogni corrispondenza. Dovrebbero tutti essere il dominio di testo del Suo plugin. Se trova errori di battitura o errori di copia-incolla, li corregga e riesegua wp i18n make-pot per aggiornare il .pot.

Per il codice JavaScript che usa @wordpress/i18n, vale la stessa regola. wp_set_script_translations() in PHP deve anch'esso passare il dominio corrispondente:

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

Intercetti gli stessi problemi prima del rilascio con la revisione visiva con IA

Il ciclo diagnostico sopra è reattivo. Una traduzione manca e Lei va a caccia della causa. La revisione visiva con IA di PTC intercetta gli stessi problemi prima del rilascio. Ispeziona il plugin renderizzato in ogni lingua di destinazione dopo ogni aggiornamento della traduzione e segnala ciò che manca o è errato.

Per una stringa inglese codificata in modo fisso al di fuori di __() (causa 1 sopra), la revisione visiva con IA vede la stringa non tradotta nel plugin renderizzato. PTC genera un prompt pronto da incollare per Cursor o Claude Code per racchiudere la stringa in __(). Per una discrepanza del dominio di testo (il controllo della sezione precedente), vede la stringa non tradotta mentre altre stringhe sulla stessa schermata sono tradotte, e segnala l'incoerenza.

Se non ha ancora abilitato la revisione visiva con IA, consulti il tutorial su temi e plugin WordPress per la configurazione.

Quando tutti e tre i controlli passano e le traduzioni mancano ancora

Se ha controllato tutte e tre le cause e le traduzioni continuano a non comparire, scriva un'e-mail al supporto PTC con:

  • Il dominio di testo del Suo plugin.
  • Uno dei nomi di file .mo (ad es., my-plugin-es_ES.mo).
  • Uno screenshot della dashboard PTC che mostra la stringa interessata con la sua traduzione.
  • L'impostazione della lingua del sito da Settings > General.

La maggior parte dei casi di "traduzione mancante" si riconduce a una delle cause sopra. I casi limite (versioni specifiche di WordPress, risoluzione della lingua in MultiSite, conflitto con un altro plugin i18n) richiedono a volte un secondo esame.

Mantenga i rilasci futuri sincronizzati con la localizzazione continua

Una volta che le Sue traduzioni si caricano correttamente, configuri il workflow di localizzazione continua affinché i rilasci futuri restino sincronizzati con le Sue traduzioni - automaticamente, a ogni push su main.