Internazionalizzazione di WordPress: come tradurre temi e plugin di WordPress

Preparare il tuo tema o plugin WordPress per la traduzione

Prima di poter tradurre qualsiasi cosa, devi impostare correttamente il tuo codice. Ciò significa definire un text domain, racchiudere tutte le stringhe rivolte all’utente nelle funzioni gettext e generare un file POT.

Nulla di tutto ciò è complicato, ma i dettagli contano. Un text domain errato o una stringa non racchiusa significano che quel testo non apparirà mai nel tuo output tradotto.

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

Dichiaralo nell’intestazione del file principale del tuo plugin:

/**
 * Plugin Name: My Plugin
 * Text Domain: my-plugin
 * Domain Path: /languages
 */

/**
 * Plugin Name: My Plugin
 * Text Domain: my-plugin
 * Domain Path: /languages
 */

Oppure nel tuo tema style.css:

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

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

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

Qualsiasi stringa che vuoi rendere traducibile deve essere racchiusa in una delle funzioni gettext di WordPress. In fase di esecuzione, queste funzioni cercano la traduzione corretta e tornano alla stringa originale se non viene trovata alcuna traduzione.

Stringhe di base

Usa __() quando devi restituire una stringa. Per l’output HTML (che è quasi sempre il caso), usa le varianti con escape:

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

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

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

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

Gli standard di codifica di WordPress raccomandano echo esc_html__() rispetto a _e() perché rende esplicito l’escaping dell’output. È una buona abitudine da applicare con costanza.

Stringhe con variabili

Se concateni una variabile direttamente in una stringa, i traduttori vedranno solo i frammenti e non la frase completa. Ciò rende impossibile tradurre correttamente, specialmente nelle lingue in cui l’ordine delle parole è diverso. Usa invece printf() o sprintf() con un placeholder e aggiungi un commento per i traduttori, in modo che sappiano cosa rappresenta %s:

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

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

Forme plurali

In inglese i plurali sono semplici: un commento, due commenti. Altre lingue non sono così immediate. Alcune hanno diverse forme plurali a seconda del numero. Usa _n() per gestire correttamente questa situazione, indipendentemente dalla lingua in cui viene tradotto il tuo plugin:

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

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 per ottenere la traduzione corretta:

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

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

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

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

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

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

Se stai usando un bundler come Webpack, usa @wordpress/babel-plugin-makepot per estrarre le stringhe traducibili dal tuo bundle come parte del processo di build.

Una volta racchiuse le stringhe, devi generare un file POT (Portable Object Template). Questo è il file sorgente su cui lavora PTC (o qualsiasi traduttore). Contiene tutte le tue stringhe traducibili ma ancora nessuna traduzione.

Esegui questo comando dalla directory root del tuo plugin o tema:

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

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

WP-CLI scansiona i tuoi file PHP, JavaScript e block.json alla ricerca di chiamate gettext e le compila in un unico file POT. Se stai usando Composer, puoi aggiungerlo come script di Composer in modo che il comando rimanga coerente in tutto il team e non richieda un’installazione globale di WP-CLI.

La suite completa wp i18n include tutto il resto di cui avrai bisogno in seguito nel flusso di lavoro: