Internazionalizzazione di WordPress: come tradurre temi e plugin

Prepara il tuo tema o plugin WordPress per la traduzione. Questa guida copre i text domain, le funzioni gettext, la generazione dei file POT e il meccanismo di caricamento che mostra le traduzioni agli utenti. PTC (Private Translation Cloud) traduce poi i file di risorse ed esegue una revisione visiva del tema o del plugin visualizzato 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 codifica di WordPress.
• Traducibile da PTC in 40+ lingue.
• Distribuibile tramite i Language Pack di WordPress.org.
• Verificabile a ogni release con la revisione visiva della traduzione di PTC.

Cos'è l'internazionalizzazione di WordPress?

L'internazionalizzazione (i18n) è il lavoro di preparazione del tuo 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 colleghi le tue traduzioni al tuo progetto.
• Generare un file POT su cui lavorano i traduttori (o PTC).

Una volta completato questo lavoro, hai 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

In qualsiasi flusso di lavoro di traduzione di 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. È il file che consegni a PTC.
• PO (Portable Object). Una copia del file POT con le traduzioni aggiunte per una lingua specifica. Testo normale, leggibile da esseri umani. PTC restituisce un file PO per ogni lingua di destinazione.
• MO (Machine Object). La versione binaria compilata di un file PO. WordPress legge i file MO a runtime perché si caricano più velocemente rispetto al testo dei file 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 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 una piccola frazione di ciò di cui la maggior parte dei plugin e dei temi ha bisogno. Un'analisi su 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 questa lacuna:

• I volontari sono scarsi nella maggior parte dei locale. Una manciata di plugin con un'enorme base di utenti attrae 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 della traduzione completa e coerente, con un programma di release che controlli tu. 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 indicano che il testo non apparirà mai nel tuo output tradotto. I dettagli sono importanti.

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
 */

Oppure nel style.css del tuo tema:

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

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

Step 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, eseguono il fallback 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 consigliano echo esc_html__() rispetto a _e(). La forma con escape rende esplicito l'escape dell'output e previene gli attacchi XSS al momento dell'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 in inglese sono semplici (one comment, two comments). Altre lingue non lo sono. Usa _n() per gestire ogni regola per i plurali conosciuta da WordPress:

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

Stringhe che richiedono contesto. Alcune parole hanno significati diversi a seconda di dove compaiono. Usa _x() per fornire 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' );

Step 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
);

Poi 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.

Step 4: Genera il tuo file POT

Una volta che le tue stringhe sono racchiuse, 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. Li compila in un singolo POT. Se il tuo team usa Composer, aggiungi questo comando come script di Composer. Questo mantiene l'utilizzo di WP-CLI coerente all'interno del team senza un'installazione globale.

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

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

Tradurre i file POT con PTC

PTC è stato creato pensando agli sviluppatori WordPress. Inizia con un file POT e ottieni file di traduzione pronti per la produzione. La prova 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 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 (voci estratte con _n() con la loro intestazione Plural-Forms) e i contesti (voci _x() con msgctxt). Genera quindi 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, passa a Pay-As-You-Go. Collega PTC al tuo repository GitHub, GitLab o Bitbucket. Da quel momento in poi non carichi più i file manualmente.

Esegui il commit di un .ptc-config.yml indicando il tuo file di origine e dove vanno inserite le traduzioni:

# .ptc-config.yml
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

Quindi aggiungi l'azione PTC Translate al tuo workflow. Contiene al suo interno una versione fissata della CLI di PTC, in modo che la tua build non scarichi nulla in fase di esecuzione:

# .github/workflows/translate.yml
name: Regenerate POT for PTC
on:
  push:
    branches: [main]
    paths:
      - 'languages/my-plugin.pot'
  workflow_dispatch: {}

jobs:
  translate:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - name: Generate POT
        run: |
          wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin
      - uses: OnTheGoSystems/ptc-action@v1
        with:
          api-token: ${{ secrets.PTC_API_TOKEN }}
          create-pr: true

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

La decisione di eseguire il commit dei file .mo nel tuo repository dipende dalle policy del team. Molti plugin, invece, li generano al momento della release. L'integrazione CI di PTC li produce a ogni esecuzione della traduzione. Esegui il commit di questi file solo se desideri che i file tradotti siano presenti nella cronologia delle versioni.

Caricare le traduzioni in WordPress

Una volta ottenuti i file tradotti, posizionali correttamente e indica a WordPress dove trovarli. Il nome del file è la prima cosa a cui devi prestare attenzione. WordPress cerca i file di traduzione utilizzando uno specifico pattern di denominazione. Se il nome del file non corrisponde, il file non verrà caricato.

Scegliere i nomi dei file corretti

I codici del locale seguono il formato language_COUNTRY. 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 del file previsto dipende da dove posizioni il file:

I temi utilizzano una convenzione di denominazione più breve quando i file sono inclusi all'interno del tema. Nella directory globale delle lingue, sia i plugin che i temi utilizzano il pattern {text-domain}-{locale}.

Caricare le traduzioni per i plugin (PHP)

Registra le traduzioni con WordPress sull'hook init. Non utilizzare plugins_loaded. Questo attiva un avviso di deprecazione nelle versioni attuali 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() agganciato 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 qui 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'
    );
} );

Verificare il caricamento

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

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

Lingue da destra a sinistra (RTL) e layout bidirezionali

Il workflow 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 in più 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 separatori decimali e delle migliaia in base al locale.

Queste funzioni non fanno parte del workflow dei file di traduzione. Sono però 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 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 fornire il JSON al blocco.

L'output del blocco visualizzato sul front end utilizza le stesse chiamate __() del resto del tuo codice PHP. Non c'è lavoro aggiuntivo da fare.

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 tue 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, tutte nello stesso progetto affinché la terminologia rimanga 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 far sì che le traduzioni vadano in produzione lì, segui il processo di importazione di WordPress.org.

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

I plugin che memorizzano dati generati dagli utenti (plugin di forum, di recensioni, di commenti) possono tradurre quei contenuti non appena arrivano. L'API REST 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 visualizzato: rilascia senza QA manuale per lingua

Un file .po tradotto è necessario, ma non sufficiente. Il tema o plugin tradotto ha comunque bisogno 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 al di fuori di __() verrà visualizzata 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 visualizzati nel browser (sia wp-admin che il front end). La versione 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 adatta 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( __( ... ) ).

Rilasci un plugin multilingue e verificato a ogni release. 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. Quando la prova finisce, 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 ha un calcolatore dei costi. Iscriviti con un'email aziendale per una prova aziendale estesa.

Pronto a rilasciare un plugin o tema verificato?

PTC genera le traduzioni e revisiona il plugin visualizzato. Tu confermi il risultato e rilasci. L'intero ciclo viene eseguito senza QA manuale:

1. Genera il tuo file .pot con wp i18n make-pot.
2. Caricalo su PTC e ottieni indietro i file .po, .mo, .l10n.php e .json in pochi minuti.
3. 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, 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 le traduzioni della community rispetto a PTC.
• Le traduzioni del plugin WordPress non vengono mostrate? Risolvi le traduzioni mancanti - guida alla risoluzione dei problemi.
• Come importare le traduzioni di temi e plugin su WordPress.org - il processo CLPTE e un'alternativa più veloce.
• Riferimento API PTC - endpoint REST per l'integrazione CI.