Internazionalizzazione di WordPress: come tradurre temi e plugin

Rendi il tuo tema o plugin WordPress pronto per la traduzione. Questa guida copre i text domain, le funzioni gettext, la generazione di file POT e il meccanismo di caricamento che mostra le traduzioni agli utenti. PTC (Private Translation Cloud) traduce quindi i file di risorse ed effettua una revisione visiva del tema o del plugin renderizzato in ogni lingua.

Questa guida è rivolta agli sviluppatori che scrivono il codice. Se hai già un file POT o PO e devi solo tradurlo, vai alla pagina dei file PO per il flusso di lavoro in 3 passaggi.

Al termine di questa guida, il tuo tema o plugin sarà:

Internazionalizzato correttamente secondo gli standard di codifica di WordPress.
Traducibile da PTC in oltre 40 lingue.
Distribuibile tramite i Language Pack di WordPress.org.
Verificabile a ogni rilascio con la revisione visiva della traduzione di PTC.

Cos'è l'internazionalizzazione di WordPress?

L'internazionalizzazione (i18n) è il lavoro di preparazione del codice affinché possa essere tradotto. La localizzazione (l10n) è il passaggio successivo: produce le stringhe tradotte effettive per lingue specifiche.

Per i temi e i plugin WordPress, i18n significa tre cose:

Racchiudere ogni stringa rivolta all'utente in funzioni gettext in modo che WordPress possa sostituirle a runtime.
Definire un text domain che colleghi le tue traduzioni al tuo progetto.
Generare un file POT su cui lavoreranno i traduttori (o PTC).

Una volta completato questo lavoro, avrai tutto il necessario per produrre file PO, MO, JSON e .l10n.php tradotti per qualsiasi lingua.

PTC traduce i file POT in MO, JSON e .l10n.php per WordPress

Sono cinque le estensioni di file che intervengono in qualsiasi flusso di lavoro di traduzione di WordPress. PTC traduce da .pot (il tuo file di origine) in .po, .mo, .json e .l10n.php per ogni lingua di destinazione. Ogni formato ha un ruolo specifico:

POT (Portable Object Template). Il file di origine generato dal tuo codice. Elenca ogni stringa traducibile senza traduzioni associate. Consegni questo file a PTC.
PO (Portable Object). Una copia del POT con l'aggiunta delle traduzioni per una lingua specifica. Testo semplice, leggibile dall'uomo. PTC restituisce un PO per ogni lingua di destinazione.
MO (Machine Object). La versione binaria compilata di un PO. WordPress legge i file MO a runtime perché si caricano più velocemente del testo PO.
JSON. L'equivalente JavaScript di MO. WordPress non può leggere i file MO da JavaScript, quindi la pipeline di build produce file JSON per le stringhe lato browser.
.l10n.php. Un'alternativa più recente a MO, introdotta in WordPress 6.5. Si carica più velocemente e consuma meno memoria. WordPress lo sceglie automaticamente quando ne esiste uno accanto al file MO.

Abilita .l10n.php per i nuovi progetti. È decisamente migliore di MO sulle versioni di WordPress supportate.

Perché la traduzione della community non è sufficiente

WordPress.org offre la traduzione della community tramite GlotPress. In pratica, copre solo una piccola frazione di ciò di cui la maggior parte dei plugin e dei temi ha bisogno. Un'analisi di oltre 60.000 plugin e temi WordPress ha rilevato che la traduzione della community copre meno del 5% delle esigenze di traduzione in 40 lingue.

Due problemi strutturali spiegano questo divario:

I volontari scarseggiano nella maggior parte dei paesi. Solo una manciata di plugin con enormi basi di utenti attira traduttori. La maggior parte no.
Le traduzioni possono richiedere mesi o anni per apparire, se appaiono. Se vuoi che gli utenti vedano il tuo plugin o tema nella loro lingua fin dal primo giorno, non puoi fare affidamento sulla community.

Questa guida presuppone che tu voglia una copertura di traduzione completa e coerente, seguendo un programma di rilascio che controlli tu. Questo è ciò che offre PTC.

Preparare il tuo tema o plugin WordPress per la traduzione

Un text domain errato o una stringa non racchiusa in una funzione significano che quel testo non apparirà mai nel tuo output tradotto. I dettagli contano.

Passaggio 1: Definisci il tuo text domain e il domain path

Ogni tema o plugin ha bisogno di un text domain. Il text domain è un identificatore unico che dice a WordPress quali file di traduzione appartengono al tuo progetto. Deve corrispondere esattamente allo slug del tuo plugin o tema.

Dichiaralo nell'intestazione del file principale del tuo plugin:

<?php
/**
 * Plugin Name: My Plugin
 * Description: An example plugin.
 * Version: 1.0.0
 * Text Domain: my-plugin
 * Domain Path: /languages
 */

O nel file style.css del tuo tema:

/*
Theme Name: My Theme
Text Domain: my-theme
Domain Path: /languages
*/

Il domain path indica a WordPress dove si trovano i tuoi file di traduzione rispetto alla root del plugin o del tema. /languages è lo standard.

Passaggio 2: Racchiudi le tue stringhe PHP nelle funzioni gettext

Qualsiasi stringa che desideri rendere traducibile deve essere racchiusa in una delle funzioni gettext di WordPress. A runtime, queste funzioni cercano la traduzione corretta. Se non ne viene trovata nessuna, ripiegano sulla stringa originale.

Stringhe di base. Usa __() quando devi restituire una stringa. Per l'output HTML, usa le varianti con escape. Gli standard di codifica di WordPress raccomandano echo esc_html__() rispetto a _e(). La forma con escape garantisce che l'output sia protetto e previene l'XSS in fase di visualizzazione:

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

// Echo a translated string, escaped for HTML
echo esc_html__( 'Settings saved.', 'my-plugin' );

Stringhe con variabili. Non concatenare variabili nelle stringhe. I traduttori vedrebbero solo frammenti e non potrebbero riordinare le parole per le lingue con una sintassi diversa. Usa printf() o sprintf() con un segnaposto. Aggiungi un commento per il traduttore in modo che sappia cosa rappresenta %s:

printf(
    /* translators: %s: the user's display name */
    esc_html__( 'Welcome back, %s.', 'my-plugin' ),
    esc_html( $display_name )
);

Forme plurali. I plurali in inglese sono semplici (one comment, two comments). Altre lingue no. Usa _n() per gestire ogni regola del plurale nota a WordPress:

printf(
    esc_html( _n( '%s comment', '%s comments', $count, 'my-plugin' ) ),
    number_format_i18n( $count )
);

Stringhe che necessitano di contesto. Alcune parole hanno significati diversi a seconda di dove appaiono. Usa _x() per dare ai traduttori il contesto di cui hanno bisogno:

// "Export" as a noun (the file) vs. a verb (the action)
echo esc_html_x( 'Export', 'button label', 'my-plugin' );

Passaggio 3: Internazionalizza le tue stringhe JavaScript

WordPress fornisce il pacchetto wp-i18n in modo da poter utilizzare in JavaScript le stesse funzioni gettext che usi in PHP. Quando registri il tuo script, dichiara wp-i18n come dipendenza:

wp_register_script(
    'my-plugin-script',
    plugins_url( 'js/app.js', __FILE__ ),
    array( 'wp-i18n' ),
    '1.0.0',
    true
);

Quindi nel tuo file JavaScript:

const { __, _n, sprintf } = wp.i18n;

const message = __( 'Settings saved.', 'my-plugin' );

Se utilizzi un bundler come Webpack, installa @wordpress/babel-plugin-makepot. Estrae le stringhe traducibili dal tuo bundle come parte della build.

Passaggio 4: Genera il tuo file POT

Una volta racchiuse le stringhe, genera un file POT. Il POT è il file di origine su cui lavora PTC (o qualsiasi traduttore). Contiene ogni stringa traducibile ma nessuna traduzione.

wp i18n make-pot . languages/my-plugin.pot

WP-CLI scansiona i tuoi file PHP, JavaScript e block.json alla ricerca di chiamate gettext. Le compila in un unico POT. Se il tuo team usa Composer, aggiungi questo comando come script Composer. Ciò garantisce la coerenza nell'uso di WP-CLI in tutto il team senza richiedere un'installazione globale.

La suite completa di comandi wp i18n copre il resto della pipeline:

Comando	Cosa fa
`wp i18n make-pot`	Genera un file POT dai sorgenti.
`wp i18n update-po`	Sincronizza i file PO esistenti quando il POT cambia.
`wp i18n make-mo`	Compila i file PO in file MO binari.
`wp i18n make-json`	Estrae le stringhe JS dai PO in file JSON.
`wp i18n make-php`	Genera file `.l10n.php` (WordPress 6.5+).

Non hai bisogno di Poedit. Tutto in questo flusso di lavoro passa attraverso WP-CLI e PTC. WP-CLI gestisce la generazione del POT e la compilazione di MO/JSON. PTC gestisce la traduzione e restituisce ogni formato di file necessario a WordPress. Poedit è un utile editor desktop per la traduzione manuale, ma non fa parte di questo flusso di lavoro.

Tradurre i file POT con PTC

PTC è costruito pensando agli sviluppatori WordPress. Inizia con un file POT e ottieni file di traduzione pronti per la produzione. La prova gratuita di 30 giorni copre fino a 20.000 parole in due lingue.

Configura il tuo primo progetto di traduzione

Carica il tuo file POT. Scegli i formati di output necessari. PTC restituisce qualsiasi combinazione di:

File .po per ogni lingua di destinazione.
File .mo, compilati e pronti per la spedizione.
File .json per le tue stringhe JavaScript.
File .l10n.php per un caricamento più rapido su WordPress 6.5+.

La procedura guidata di configurazione ti chiede di descrivere il tuo tema o plugin. PTC usa la descrizione per generare traduzioni con il tono e il contesto corretti. Aggiungi i termini specifici del brand al glossario in questa fase. Il glossario mantiene coerenti i nomi, le etichette delle funzionalità e qualsiasi altra terminologia in tutte le lingue.

PTC analizza la struttura gettext al caricamento. Riconosce i segnaposto (%s, %1$s, %d), le forme plurali (voci estratte da _n() con la loro intestazione Plural-Forms) e i contesti (voci _x() con msgctxt). Genera quindi le categorie plurali corrette per lingua. Il polacco ottiene one / few / many / other. Il giapponese ottiene solo other. L'arabo ottiene sei forme.

Passa alla localizzazione continua

Una volta tradotti i primi file, passa al Pay-As-You-Go. Collega PTC al tuo repository GitHub, GitLab o Bitbucket. Da quel momento non caricherai più i file manualmente:

# .github/workflows/translate.yml
name: Regenerate POT for PTC
on:
  push:
    branches: [main]
    paths:
      - 'languages/my-plugin.pot'
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate POT
        run: |
          wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin
      - name: Trigger PTC translation
        run: |
          curl -X POST https://api.ptc.wpml.org/v1/projects/${{ secrets.PTC_PROJECT_ID }}/sync \
            -H "Authorization: Bearer ${{ secrets.PTC_API_KEY }}"

Hai due modi per automatizzare questo processo. Con l'integrazione Git, PTC monitora il tuo repository e apre una pull request con le traduzioni aggiornate ogni volta che il file di origine cambia. Per eseguire la traduzione all'interno del tuo job CI, usa la CLI di PTC: carica il file modificato, attende il completamento della traduzione e scarica i file tradotti. I template di workflow pronti all'uso per GitHub Actions, GitLab CI e Bitbucket Pipelines si trovano nella guida alla configurazione della pipeline CI/CD.

Entrambi i flussi forniscono una pull request o un download con i file .po, .mo, .json e .l10n.php aggiornati. Consulta il riferimento API di PTC per il webhook completo e la REST API.

Il fatto di eseguire il commit dei file .mo nel tuo repository dipende dalla politica del team. Molti plugin li generano al momento del rilascio. L'integrazione CI di PTC li produce a ogni ciclo di traduzione. Effettua il check-in solo se desideri i file tradotti nella cronologia delle versioni.

Caricamento delle traduzioni in WordPress

Con i file tradotti in mano, posizionali correttamente e dì a WordPress dove trovarli. Il nome del file viene prima di tutto. WordPress cerca i file di traduzione utilizzando uno schema di denominazione specifico. Un nome file che non corrisponde significa che il file non verrà caricato.

Assegnare i nomi corretti ai file

I codici locale seguono il formato lingua_PAESE. de_DE è tedesco (Germania). fr_FR è francese (Francia). pt_BR è portoghese (Brasile). zh_CN è cinese semplificato. Il portale di traduzione di WordPress elenca ogni locale supportato.

Il nome file previsto dipende da dove posizioni il file:

Posizione	Schema	Esempio
Cartella `/languages/` del plugin	`{text-domain}-{locale}.mo`	`my-plugin-de_DE.mo`
Cartella `/languages/` del tema	`{locale}.mo`	`de_DE.mo`
Directory globale delle lingue di WordPress (`/wp-content/languages/`)	`{text-domain}-{locale}.mo`	`my-plugin-de_DE.mo`

I temi utilizzano una convenzione di denominazione più breve quando i file sono inclusi nel tema. Nella directory globale delle lingue, sia i plugin che i temi utilizzano lo schema {text-domain}-{locale}.

Caricamento delle traduzioni per i plugin (PHP)

Registra le traduzioni con WordPress sull'hook init. Non usare plugins_loaded, poiché genera un avviso di deprecazione nelle versioni correnti di WordPress:

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

Caricamento delle traduzioni per i temi (PHP)

Usa load_theme_textdomain() collegato a after_setup_theme:

add_action( 'after_setup_theme', function () {
    load_theme_textdomain( 'my-theme', get_template_directory() . '/languages' );
} );

Caricamento delle traduzioni JavaScript

Dopo aver registrato il tuo script (Passaggio 3 sopra), chiama wp_set_script_translations(). WordPress caricherà quindi le traduzioni JSON per quell'handle di script:

add_action( 'init', function () {
    wp_set_script_translations(
        'my-plugin-script',
        'my-plugin',
        plugin_dir_path( __FILE__ ) . 'languages'
    );
} );

Verifica il caricamento

Imposta la lingua del tuo sito WordPress su un locale di destinazione. L'impostazione si trova in Impostazioni > Generale > Lingua del sito.
Ricarica il front-end e le pagine di amministrazione renderizzate dal tuo plugin o tema.
Le stringhe racchiuse in __() o esc_html__() dovrebbero apparire nella nuova lingua.

Se manca qualcosa, consulta Le traduzioni del plugin WordPress non vengono visualizzate? Correggi le traduzioni mancanti per le cause più comuni.

Lingue da destra a sinistra e layout bidirezionali

Il flusso di lavoro di traduzione è lo stesso per le lingue da destra a sinistra (RTL). Arabo, ebraico, persiano e urdu utilizzano la stessa pipeline POT/PO/MO.

Il passaggio extra consiste nell'assicurarsi che il tema supporti gli stili RTL. WordPress carica automaticamente un file rtl.css se ne esiste uno nella directory del tema. Usa la funzione is_rtl() per applicare condizionalmente stili o script specifici per RTL.

Localizzazione di date, numeri e valute

Una stringa tradotta non è tutto. Anche date, numeri e valute devono seguire il locale dell'utente. Usa le funzioni di formattazione integrate di WordPress invece di quelle native di PHP:

date_i18n() formatta le date in base al locale attivo.
number_format_i18n() formatta i numeri con separatori decimali e delle migliaia sensibili al locale.

Queste funzioni non fanno parte del flusso di lavoro dei file di traduzione. Sono fondamentali per un'esperienza completamente localizzata.

Internazionalizzazione dei blocchi del Block Editor (Gutenberg)

I blocchi aggiungono due passaggi extra alla pipeline standard:

Le traduzioni JavaScript necessitano di un file .json per locale. Generalo dal file .po con wp i18n make-json.
Lo script dell'editor del blocco necessita di wp_set_script_translations() in PHP. Questo dice a WordPress di servire il JSON al blocco.

L'output renderizzato dal blocco sul front-end utilizza le stesse chiamate __() del resto del PHP. Nessun lavoro extra richiesto.

Tradurre il README e la scheda su WordPress.org

Il tuo file readme.txt non è un file di risorse. WP-CLI non lo rileverà durante la generazione di un POT. Per tradurlo, usa la funzione Incolla per tradurre di PTC. Incolla il contenuto, scegli le lingue di destinazione e scarica il risultato. Le email rivolte ai clienti inviate dal plugin e la descrizione della pagina del plugin su WordPress.org si traducono allo stesso modo, tutto nello stesso progetto, così la terminologia rimane coerente.

Se il tuo plugin o tema è presente su WordPress.org, la descrizione tradotta appare nella scheda Dettagli del plugin nella lingua dell'utente. Per pubblicare le traduzioni lì, segui il processo di importazione di WordPress.org.

Traduci i contenuti utente del plugin con l'API di PTC

I plugin che memorizzano dati generati dagli utenti (plugin per forum, recensioni, commenti) possono tradurre tali contenuti man mano che arrivano. La REST API di PTC traduce post, commenti e recensioni degli utenti su richiesta con autenticazione Bearer-token, utilizzando lo stesso glossario e la stessa voce del brand dei tuoi file .po.

Revisione visiva della traduzione del tuo tema o plugin renderizzato: pubblica senza QA manuale per lingua

Un file .po tradotto è necessario, ma non sufficiente. Il tema o il plugin tradotto deve comunque essere verificato:

Un'etichetta tradotta potrebbe causare un overflow in un pulsante della pagina delle impostazioni in tedesco.
“Submit” potrebbe essere tradotto come sostantivo in francese quando l'azione di amministrazione richiedeva un verbo.
Una stringa inglese hardcoded al di fuori di __() verrà renderizzata non tradotta, indipendentemente dal numero di lingue fornite.

La revisione visiva della traduzione di PTC sostituisce il passaggio di QA manuale. I temi e i plugin WordPress vengono renderizzati nel browser (sia in wp-admin che nel front-end). La versione corretta è l'estensione del browser.

Installala una volta. Registra un percorso guidato del tuo tema o plugin su un sito di test. Copri le pagine delle impostazioni, le azioni di amministrazione e l'output del front-end. PTC riproduce la registrazione in ogni lingua di destinazione dopo ogni aggiornamento della traduzione. Cattura ogni schermata e segnala due tipi di correzioni:

Correzioni nei file .po quando PTC li controlla. PTC ritraduce un termine errato, sceglie un sinonimo più breve che si adatti a un pulsante o rigenera una forma plurale.
Prompt per Cursor o Claude Code quando il problema risiede nel tuo codice PHP o JavaScript. Gli esempi includono una funzione __() mancante, una stringa inglese hardcoded o una frase costruita per concatenazione che dovrebbe usare sprintf( __( ... ) ).

Pubblichi un plugin multilingue verificato a ogni rilascio. Il lavoro di QA manuale scompare.

Prezzi: prova gratuita di 30 giorni, poi Pay-As-You-Go

La prova gratuita copre 20.000 parole in 2 lingue senza carta di credito. Al termine della prova, PTC offre il Pay-As-You-Go. Nessun abbonamento. Nessun impegno minimo. Le prime 500 parole ogni mese sono gratuite. Paghi solo per il resto. La pagina dei prezzi include un calcolatore dei costi. Registrati con un'email aziendale per una prova business estesa.

Pronto a pubblicare un plugin o un tema verificato?

PTC genera le traduzioni e revisiona il plugin renderizzato. Tu confermi il risultato e pubblichi. L'intero ciclo avviene senza QA manuale:

Genera il tuo file .pot con wp i18n make-pot.
Caricalo su PTC e ottieni file .po, .mo, .l10n.php e .json in pochi minuti.
Installa l'estensione del browser per verificare il plugin in esecuzione in ogni lingua di destinazione.

Inizia la tua prova gratuita di 30 giorni: 20.000 parole offerte da noi, nessuna carta di credito richiesta.

Correlati:

Traduci file PO online con l'IA – la pagina canonica per la traduzione di PO/POT.
GlotPress vs PTC per la traduzione di plugin/temi WordPress – quando scegliere la traduzione della community rispetto a PTC.
Le traduzioni del plugin WordPress non vengono visualizzate? Correggi le traduzioni mancanti – guida alla risoluzione dei problemi.
Come importare le traduzioni di temi e plugin in WordPress.org – il processo CLPTE e un'alternativa più rapida.
Riferimento API di PTC – endpoint REST per l'integrazione CI.