Internazionalizzazione di WordPress: come tradurre temi e plugin

Prepara il tuo tema o plugin WordPress per la traduzione. Questa guida tratta 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 poi i file di risorse e sottopone a revisione visiva della traduzione il tema o 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.

Alla fine di questa guida, il tuo tema o plugin sarà:

Internazionalizzato correttamente secondo gli standard di programmazione 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.

Che 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 di WordPress, i18n significa tre cose:

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

Una volta completato questo lavoro, hai tutto ciò che ti serve per produrre i file PO, MO, JSON e .l10n.php tradotti per qualsiasi lingua.

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

In qualsiasi flusso di lavoro di traduzione per WordPress compaiono cinque estensioni di file. PTC traduce da .pot (la tua 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 allegate. È quello che consegni a PTC.
PO (Portable Object). Una copia del POT con le traduzioni aggiunte per una lingua specifica. Testo normale, leggibile da esseri umani. 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 rispetto al testo dei 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 usa meno memoria. WordPress lo sceglie automaticamente quando ne esiste uno accanto al file MO.

Abilita .l10n.php per i nuovi progetti. È nettamente superiore a MO sulle versioni di WordPress supportate.

Perché le traduzioni della community non sono sufficienti

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

Due problemi strutturali spiegano questo divario:

I volontari scarseggiano nella maggior parte dei locale. Una manciata di plugin con un'enorme base di utenti attira i traduttori. La maggior parte no.
Le traduzioni possono impiegare mesi o anni per apparire, se mai appaiono. Se vuoi che gli utenti vedano il tuo plugin o tema nella loro lingua fin dal primo giorno, non puoi affidarti alla community.

Questa guida presuppone che tu voglia una copertura di traduzione completa e coerente, con un programma di rilascio sotto il tuo controllo. Questo è ciò che offre PTC.

Preparare il tuo tema o plugin WordPress per la traduzione

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

Passaggio 1: definisci il tuo text domain e il percorso del dominio

Ogni tema o plugin ha bisogno di un text domain. Il text domain è un identificatore univoco 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 percorso del dominio 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 vuoi 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, usano la stringa originale come fallback.

Stringhe di base. Usa __() quando devi restituire una stringa. Per l'output HTML, usa le varianti escaped. Gli standard di programmazione di WordPress consigliano echo esc_html__() rispetto a _e(). La forma escaped rende esplicito l'escape dell'output e previene gli XSS nel punto di output:

// 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 le variabili nelle stringhe. I traduttori vedono solo frammenti e non possono riordinare le parole per lingue con sintassi diversa. Usa printf() o sprintf() con un segnaposto. Aggiungi un commento per il traduttore in modo che i traduttori sappiano 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 inglesi sono semplici (un commento, due commenti). Altre lingue non lo sono. Usa _n() per gestire ogni regola sui plurali 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 usare 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 usi un bundler come Webpack, installa @wordpress/babel-plugin-makepot. Estrae le stringhe traducibili dal tuo bundle come parte della tua build.

Passaggio 4: genera il tuo file POT

Una volta racchiuse le tue 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 analizza i tuoi file PHP, JavaScript e block.json alla ricerca di chiamate gettext. Li compila in un singolo POT. Se il tuo team usa Composer, aggiungi questo comando come script Composer. In questo modo l'uso di WP-CLI rimane coerente in tutto il team senza un'installazione globale.

L'intera suite di comandi wp i18n copre il resto della pipeline:

Comando	Cosa fa
`wp i18n make-pot`	Genera un file POT dal sorgente.
`wp i18n update-po`	Sincronizza i file PO esistenti quando il tuo 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 i 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 MO/JSON. PTC gestisce la traduzione e restituisce ogni formato di file richiesto da 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 è stato creato pensando agli sviluppatori WordPress. Inizia con un file POT e ottieni in cambio file di traduzione pronti per la produzione. La prova di 30 giorni copre fino a 20.000 parole in due lingue.

Imposta il tuo primo progetto di traduzione

Carica il tuo file POT. Scegli di quali formati di output hai bisogno. PTC restituisce qualsiasi combinazione di:

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

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

PTC analizza la struttura gettext durante il caricamento. Riconosce i segnaposto (%s, %1$s, %d), le forme plurali (le voci estratte con _n() con la loro intestazione Plural-Forms) e i contesti (le voci _x() con msgctxt). Quindi genera le categorie plurali corrette per ogni 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 tuoi primi file, esegui l'upgrade a Pay-As-You-Go. Collega PTC al tuo repository GitHub, GitLab o Bitbucket. Da quel momento in poi 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: Translate with PTC
        run: |
          cat > .ptc-config.yml <<'EOF'
          source_locale: en
          files:
            - file: languages/my-plugin.pot
              output: languages/my-plugin-{{lang}}.po
              additional_translation_files:
                - type: mo
                  path: languages/my-plugin-{{lang}}.mo
          EOF
          curl -fsSL https://raw.githubusercontent.com/OnTheGoSystems/ptc-cli/main/ptc-cli.sh -o ptc-cli.sh
          chmod +x ptc-cli.sh
          ./ptc-cli.sh --config-file .ptc-config.yml --api-token="${{ secrets.PTC_API_TOKEN }}"

Hai due modi per automatizzare questo processo. Con l'integrazione Git, PTC monitora il tuo repository e apre una merge request con le traduzioni aggiornate ogni volta che il file di origine cambia. Per eseguire invece la traduzione all'interno del tuo job CI, usa la CLI di PTC: carica il file modificato, attende che la traduzione finisca e scarica i file tradotti. I modelli 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 merge request o un download con i file .po, .mo, .json e .l10n.php aggiornati. Consulta il riferimento API PTC per la documentazione completa sui webhook e sull'API REST.

La decisione di includere o meno nel commit i file .mo nel tuo repository dipende dalle policy del team. Molti plugin li generano invece al momento del rilascio. L'integrazione CI di PTC li produce a ogni esecuzione della traduzione. Includili nel commit solo se desideri i file tradotti nella cronologia delle versioni.

Caricare le traduzioni in WordPress

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

Scegliere i nomi file corretti

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

Il nome file previsto dipende da dove posizioni il file:

Posizione	Modello	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 usano una convenzione di denominazione più breve quando i file sono raggruppati all'interno del tema. Nella directory globale delle lingue, sia i plugin che i temi usano il modello {text-domain}-{locale}.

Caricare le traduzioni per i plugin (PHP)

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

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

Caricare le 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' );
} );

Caricare le 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 dello 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 > Generali > 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 mostrate? Correggi le traduzioni mancanti per le cause più comuni.

Lingue right-to-left e layout bidirezionali

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

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

Localizzare date, numeri e valute

Una stringa tradotta non è tutto. Anche le date, i numeri e le 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 i separatori decimali e delle migliaia specifici per il locale.

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

Internazionalizzare i blocchi dell'editor a blocchi (Gutenberg)

I blocchi aggiungono due passaggi extra alla pipeline standard:

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

L'output renderizzato dal blocco sul front end usa le stesse chiamate __() del resto del tuo PHP. Nessun lavoro extra in questo caso.

Tradurre il tuo README e la scheda dello store su WordPress.org

Il tuo readme.txt non è un file di risorse. WP-CLI non lo rileverà durante la generazione di un POT. Per tradurlo, usa la funzionalità Paste to Translate 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 nello stesso modo, tutte nello stesso progetto affinché la terminologia rimanga coerente.

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

Tradurre i contenuti degli utenti del plugin con l'API PTC

I plugin che archiviano dati generati dagli utenti (plugin di forum, plugin di recensioni, plugin di commenti) possono tradurre quei contenuti man mano che arrivano. L'API REST PTC traduce post, commenti e recensioni degli utenti su richiesta con autenticazione Bearer, usando lo stesso glossario e la stessa voce del brand dei tuoi file .po.

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

Un file .po tradotto è necessario, ma non sufficiente. Il tema o plugin tradotto necessita ancora di verifica:

Un'etichetta tradotta potrebbe andare in 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 in inglese hardcoded esterna a __() verrà renderizzata non tradotta, indipendentemente da quante lingue rilasci.

La revisione visiva della traduzione di PTC sostituisce il ciclo di QA manuale. I temi e i plugin di WordPress vengono renderizzati nel browser (sia wp-admin che il front end). La variante giusta è 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'accezione errata, sceglie un sinonimo più corto 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 un wrapper __() mancante, una stringa in inglese hardcoded o una frase costruita per concatenazione che dovrebbe usare sprintf( __( ... ) ).

A ogni rilascio, distribuisci un plugin verificato e multilingue. Il lavoro residuo di QA manuale scompare.

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

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

Pronto a rilasciare un plugin o un tema verificato?

PTC genera le traduzioni e sottopone a revisione il plugin renderizzato. Tu confermi il risultato e rilasci. L'intero ciclo viene eseguito senza QA manuale:

Genera il tuo file .pot con wp i18n make-pot.
Caricalo su PTC e ottieni in cambio i 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 di 30 giorni: 20.000 parole offerte da noi, non è richiesta la carta di credito.

Correlati:

Traduci i 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 le traduzioni della community rispetto a PTC.
Le traduzioni del plugin WordPress non vengono mostrate? 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 PTC: endpoint REST per l'integrazione CI.