Come internazionalizzare il tuo sito Web WordPress

Il 30 settembre 2017, la comunità internazionale di WordPress si è unita per 24 ore per tradurre l'ecosistema WordPress. Per la terza volta, #WPTranslationDay ha unito una maratona di traduzioni di un'intera giornata con eventi digitali e giornalieri per i contributori progettati per promuovere il valore della creazione di esperienze accessibili per gli utenti globali, meglio conosciute come "localizzazione".

Come comunità open source, dovremmo tutti sforzarci di localizzare i nostri contributi open source. Prima di poter trascrivere le tue risorse digitali, però, devi internazionalizzare la tua base di codice.

I termini “internazionalizzazione” e “localizzazione” sono spesso usati in modo intercambiabile, sebbene tecnicamente rappresentino due aspetti diversi del processo traduttivo.

• L'internazionalizzazione (I18N) è il processo di internazionalizzazione o adattamento del tuo tema o plugin per tradurlo in qualsiasi lingua del mondo.
• La localizzazione (L10N) è il successivo processo di localizzazione o traduzione degli strumenti internazionalizzati in una determinata lingua.

WordPress è attualmente completamente localizzato per oltre 65 lingue e offre traduzioni parziali per altre 95 localizzazioni. L'uso internazionale continua ad aumentare man mano che vengono introdotte più localizzazioni.

Gli utenti di WordPress non di lingua inglese hanno superato gli utenti di lingua inglese nel 2014 e inavvertitamente continuano a diluire la percentuale di torta degli utenti inglesi nel 2017 man mano che crescono sforzi come #WPTranslateDay.

Man mano che WordPress diventa sempre più linguisticamente accessibile, la conoscenza di I18N e L10N è essenziale per gli sviluppatori di plugin e temi per prosperare nell'economia globale di WordPress. Per le aziende in crescita, queste capacità di sviluppo possono aprire le porte ai mercati esteri. L'accessibilità al Web, inclusa l'accessibilità linguistica, è positiva per le aziende e migliore per le persone.

Come continuazione di #WPTranslationDay , ecco una guida aggiornata per internazionalizzare i tuoi plugin e temi WordPress.

Ecco una breve panoramica del processo che esploreremo oggi.

• Scoperta
  • Conosci i file di traduzione
    • File POT
    • Archivio PO
    • File MO
  • GlotPress e Language Pack
  • Effettua il backup e prepara il tuo ambiente
• Plugin I18N
  • Intestazione del plug-in
  • Carica dominio di testo
  • Verifica delle stringhe
  • Genera file POT
• Tema I18N
  • Intestazione del tema
  • Carica dominio di testo
  • Verifica delle stringhe
  • Genera file POT
• JavaScript I18N
• Risorse addizionali

Scoperta

Scopri i file di traduzione

WordPress utilizza la libreria gettext GNU per facilitare I18N.

Per prima cosa, acquisiamo familiarità con i file di traduzione gettext generati durante il processo.

File modello oggetto portatile (POT)

Durante il processo I18N, utilizzeremo uno strumento per trovare stringhe internazionalizzate e generare un file POT contenente tutto il testo traducibile nei plugin e nel tema.

File oggetto portatile (PO)

In apparenza, non ci sono differenze notevoli tra un file POT e un file PO . Sono sintatticamente uguali e si differenziano solo per gli scopi previsti.

Dopo aver generato un file POT, le stringhe di testo dovrebbero essere interpretate da un traduttore nella tua lingua preferita. Il file PO conterrà eventualmente stringhe di testo nella tua lingua madre, nonché le traduzioni appropriate.

File oggetto macchina (MO)

Infine, il file PO viene convertito in un documento leggibile dalla macchina o in un file Machine Object. Questo file vivrà nella tua directory del tema o del plug-in affinché WordPress possa richiamarlo quando è il momento di pubblicare una versione tradotta.

Eseguire il backup e preparare l'ambiente

Prima di modificare qualsiasi markup, fai un backup del tuo plugin, tema o del tuo intero sito (qualunque cosa tu stia internazionalizzando!) e metti in ordine i tuoi ambienti di sviluppo.

Assicurati di eseguire un rapido controllo del plug-in se prevedi di localizzare il tuo sito web. Elimina o disattiva tutti i plug-in che non stai più utilizzando attivamente. Questo rapido controllo ti farà risparmiare tempo a lungo termine.

Internazionalizza i tuoi plugin

INTESTAZIONE DEL PLUGIN

Innanzitutto, aggiorneremo l'intestazione del plug-in. Nello specifico, il dominio di testo e il percorso del dominio .

Esempio di intestazione del plugin

 /* Plugin Name: My Rad Plugin Plugin URI: https://myradplugin.com Description: Custom Plugin That Makes My Site Rad Author: Rad Plugin Creator Version: 1.0 Author URI: https://radplugincreator.com Text Domain: rad-plugin Domain Path: /languages/ */

Dominio di testo

Il dominio di testo è un identificatore univoco per WordPress per riconoscere tutto il testo appartenente a un plug-in e deve corrispondere allo slug del plug-in .

Questo è particolarmente importante se il tuo plugin è ospitato su WordPress.org; questi devono corrispondere affinché GlotPress possa importare correttamente le traduzioni per il tuo plugin.

Nel nostro esempio, il file del plugin è denominato rad-plugin.php e il dominio di testo è rad-plugin

Potresti già avere un dominio di testo impostato. In caso contrario, ricorda di utilizzare i trattini, non i trattini bassi.

Percorso del dominio

Il percorso del dominio è la cartella in cui risiedono i file di traduzione finalizzati. Dovresti creare una nuova cartella all'interno della directory del plug-in, come /languages/ , e aggiornare il percorso del dominio, in modo che WordPress sappia esattamente dove cercare i file di traduzione.

CARICA IL DOMINIO DEL TESTO

Successivamente, caricheremo il dominio di testo aggiungendo la seguente funzione al nostro codice.

load_plugin_textdomain()

 load_plugin_textdomain( $domain, $abs_rel_path, $plugin_rel_path );

Se è disponibile un file di traduzione per la lingua dell'utente, la funzione di caricamento del dominio di testo indicherà a WordPress di consegnarlo.

Parametri

• $domain — dominio di testo (obbligatorio)
• $abs_rel_path — false (facoltativo, deprecato)
• $plugin_rel_path — /lingue/ (opzionale, questo è il percorso relativo alla directory contenente i file di traduzione. Nel nostro esempio, /lingue/. A partire dalla versione 4.6, WordPress cercherà questi file nella directory /lingue/ del plug-in, se non viene specificato.)

Esempio di plug-in Rad

Per caricare il dominio di testo, ci collegheremo all'azione 'plugins_loaded'.

 add_action( 'plugins_loaded', 'rad_plugin_load_text_domain' ); function rad_plugin_load_text_domain() { load_plugin_textdomain( 'rad-plugin', false, dirname( plugin_basename( __FILE__ ) ) . '/languages/' ); }

VERIFICA DELLE STRINGE

Il passaggio successivo consiste nel racchiudere tutte le stringhe di testo del plug-in nelle funzioni di traduzione.

Le funzioni di traduzione più comuni sono __() per restituire una stringa tradotta e _e() per fare eco a una stringa tradotta.

Esempio di plug-in Rad

 __() $text = __( 'Super Rad!', 'rad-plugin' );

Questa funzione funzionerà per traduzioni semplici. Tiene conto di due parametri; la stringa di testo e il dominio di testo .

 _e( 'Super Rad!', 'rad-plugin' );

Questa funzione riproduce semplicemente il valore. In caso contrario, funziona esattamente come la funzione precedente.

Ci sono una serie di funzioni di traduzione aggiuntive che dovrebbero essere utilizzate anche quando appropriato.

Altre funzioni di base

 __() _e() _x() _ex() _n() _nx() _n_noop() _nx_noop() translate_nooped_plural()

Funzioni di data e numero

 number_format_i18n() date_i18n()

Funzioni di fuga

Non dimenticare di eseguire l'escape di tutti i dati che vengono emessi utilizzando le seguenti funzioni di escape.

 esc_html__() esc_html__() esc_html_x() esc_attr__() esc_attr_e() esc_attr_x()

Nel nostro esempio Rad, potremmo avere una riga di codice del plugin simile a questa:

 function create_section() { esc_html_e( 'Below are your settings for Rad Plugin', 'rad-plugin' ); }

CREA UN FILE POT

Il passaggio finale è creare un file POT. Sono disponibili alcuni strumenti diversi per generare questo tipo di file, ma per questo tutorial ci atterremo ai consigli del codice di WordPress e utilizzeremo Poedit, una GUI facile da usare per la gestione delle traduzioni.

Nota : se il tuo plugin o tema è già nel repository di WordPress.org, puoi saltare questo processo e generare un file POT dalla pagina di amministrazione. In questo caso, non è necessario generare un file .po per ogni lingua. L'introduzione di GlotPress e dei language pack nel 2015 ha semplificato il processo di traduzione; tutto ciò che serve per GlotPress è il file .pot, che verrà importato da WordPress.org e servito ai traduttori attraverso la dashboard di translate.wordpress.org. I collaboratori di tutto il mondo utilizzeranno questa dashboard per fornire traduzioni su #WPTranslateDay.

Scarica Poedit

Configurazione di Poedit

Proprietà di traduzione

Inizia andando su File > Nuovo . Quindi seleziona la lingua nativa del tuo plug-in e premi OK .

Quindi, seleziona Catalogo > Nuovo . Immettere il nome del progetto, la versione, il contatto e la lingua.

Percorsi

Seleziona quindi la scheda Percorsi di origine. Se si tratta di un nuovo file, dovrai prima salvare il file.

Seguendo il nostro esempio, selezioniamo File > Salva con nome per salvare come file .po nella directory /languages/ all'interno di rad-plugin. Ancora una volta, il nome del file dovrebbe corrispondere allo slug del tuo plugin.

 rad-plugin.po

Dopo il salvataggio, inserisci il percorso relativo alla directory in cui rimarranno i tuoi file di traduzione. In questo scenario, lingue .

Parole chiave

Seleziona la scheda Parole chiave sorgenti . Fare clic sull'icona + per aggiungere i nomi delle funzioni appropriati.

Cheatsheet

 __ _e _x _ex _n _nx _n_noop _nx_noop translate_nooped_plural number_format_i18n date_i18n esc_html__ esc_html__ esc_html_x esc_attr__ esc_attr_e esc_attr_x

Successivamente, puoi fare clic su OK e quindi su File > Salva .

Poedit salverà sia un file .mo che un file .po. Puoi creare il file .pot copiando il file .po e aggiungendo un'estensione .pot. Gli utenti internazionali possono utilizzare il file modello .pot per tradurre le stringhe nella loro lingua.

Internazionalizza il tuo tema

Il processo per internazionalizzare il tuo tema è praticamente identico a I18N per i plugin. Inizieremo controllando l'intestazione del tema e finiremo generando un altro file POT.

INTESTAZIONE DEL TEMA

Ricontrolla l'intestazione del tema per assicurarti che il dominio di testo e il percorso del dominio siano impostati.

Esempio di intestazione del tema

 /* Theme Name: Rad Theme Author: Rad Theme Author Text Domain: rad-theme Domain Path: /languages/ */

CARICA IL DOMINIO DEL TESTO

Il passaggio successivo è caricare un dominio di testo nel file functions.php del tuo tema questa volta.

load_theme_textdomain()

 load_theme_textdomain( 'radtheme', get_template_directory() . '/languages' );

Affinché questi file vengano caricati, devi registrarli con l'azione after_setup_theme.

 add_action( 'after_setup_theme', 'rad_theme_setup' ); function rad_theme_setup() { load_theme_textdomain( 'radtheme', get_template_directory() . '/languages' ); }

VERIFICA DELLE STRINGE

Tempo per un altro audit delle stringhe! A questo punto dovresti avere familiarità con le funzioni di traduzione di base.

Diamo un'occhiata ad alcune traduzioni più complicate.

Segnaposto

Le variabili PHP come l'esempio seguente non verranno tradotte correttamente senza l'uso di segnaposto.

 echo "We added $count rad points.";

printf() e sprintf()

Queste funzioni utilizzano segnaposto come %s o %d per interi, per interpolare una stringa di testo con contenuto dinamico.

Esempio di tema Rad

 /* Translators: %d is the number of rad points added */ printf( esc_html__( 'We added %d rad points.', 'rad-plugin' ), $count );

plurali

La funzione _n() può gestire traduzioni di stringhe più complesse come i plurali, ma non è consigliata a causa delle sue limitazioni all'interno del software di traduzione. Invece puoi scrivere una semplice dichiarazione if per distinguere tra parole singolari e plurali.

Esempio di plug-in Rad

 If ( 1 === $rad_points_found ) { $message = __( '1 rad point', 'rad-plugin' ); } else { /* Translators: %s is the number of rad points found */ $message = sprintf( __( '%s rad points' , 'rad-plugin' ) , $rad_points_found ); }

GENERARE FILE POT

Il processo per la generazione dei file POT del tema è lo stesso della generazione dei file POT del plug-in. Esplora alcuni metodi di seguito.

Riga di comando

Con WordPress Trunk e il pacchetto gettext GNU installati, puoi completare questo passaggio eseguendo lo script makepot.php nella riga di comando.

Aprire la riga di comando e passare alla directory degli strumenti I18N.

 cd wpdev/tools/i18n/

Lo script dovrebbe assomigliare a questo:

 php path/to/makepot.php wp-theme path/to/rad-theme rad-theme.pot

Lo script farà il suo dovere e il file finito, rad-theme.pot , finirà nella directory corrente.

Compiti di grugnito

Un altro metodo per creare un file POT consiste nell'eseguire attività Grunt utilizzando grunt-wp-i18n o grunt-pot. I task runner come Grunt possono automatizzare molte attività noiose, come la generazione di file POT.

Per creare il tuo file POT, assicurati di aver prima installato node.js. Quindi, installa Grunt nella directory della tua lingua tramite la riga di comando e il gioco è fatto. Ora puoi eseguire rapidamente questi comandi I18N e creare il tuo file di traduzione senza lasciare la comodità della riga di comando.

JavaScript I18N

Se sei uno sviluppatore moderno di temi o plugin, è probabile che utilizzi JavaScript per gestire alcuni componenti del tuo progetto. wp_localize_script è una funzione efficace per estrarre i dati PHP da fornire ai tuoi script ed è l'unico modo per tradurre JavaScript all'interno di WordPress.

WP_LOCALIZE_SCRIPT()

Questa funzione ci consentirà di localizzare le stringhe lato server in PHP e fornire stringhe di testo come oggetto JavaScript allo script.

 wp_localize_script( $handle, $name, $data );

PARAMETRI

• $ handle — handle dello script per cui i dati devono essere disponibili (richiesto — deve corrispondere all'handle dello script a cui sono destinati questi dati, vedere l'esempio di seguito)
• $name — nome dell'oggetto che contiene i dati (obbligatorio — deve essere univoco)
• $data — un array di dati da passare allo script (richiesto) .

ESEMPIO DI PLUGIN RAD

 add_action( 'wp_enqueue_scripts', 'rad_theme_scripts' ); function rad_theme_scripts() { wp_enqueue_script( 'rad-theme-script', get_template_directory_url() . '/js/rad-theme-script.js' ); wp_localize_script( 'rad-theme-script', 'rad-I18n', array( 'message' => __( 'Super Rad!', 'rad-theme' ), ) ); }

ACCEDI AI DATI IN JAVASCRIPT

Il semplice frammento di codice riportato di seguito è un esempio di come accedere a questi dati nel file JavaScript.

 alert( rad-I18n.message );

Risorse addizionali

• I18N per sviluppatori WordPress
• Manuale del tema WordPress: internazionalizzazione
• Manuale dei plugin di WordPress: Internazionalizzazione
• WordPress.tv: I18N

Avvolgendolo

Congratulazioni! Hai appena internazionalizzato il tuo tema e/o plug-in, rendendolo accessibile a persone di tutte le lingue native di cui trarne vantaggio. Indipendentemente dal fatto che il tuo progetto sia distribuito tramite il repository di WordPress o sviluppato su misura per il sito Web della tua organizzazione, c'è solo un vantaggio nell'internazionalizzare i tuoi file dall'inizio.

• Rendi i tuoi contributi open source accessibili a livello globale.
• Crea conversazioni con nuovi clienti nei mercati esteri.
• Risparmia tempo e riduci i laboriosi aggiornamenti in futuro.

Internazionalizzare sempre.