Le funzioni WordPress per la localizzazione

Le funzioni WordPress prese in considerazione in questo articolo sono quelle che influenzano la generazione di un file .POT. Si suddividono in funzioni PHP e funzioni JavaScript.

Le funzioni PHP

Le funzioni PHP sono contenute nei file wp-includes/l10n.php.

Possono essere suddivise nelle seguenti categorie:

• funzioni di base (6)
• funzioni di base con gestione del contesto (4)
• funzioni che gestiscono la forma plurale (1)
• funzioni che gestiscono la forma plurale e il contesto (1)

Per ciascuna categoria, verrà illustrato il diverso effetto sul file .POT.

Schema riassuntivo

Funzioni che non prevedono la gestione della forma plurale:

output	escaping	base	base con contesto
restituzione del testo tradotto	senza escape del testo	__()	_x()
	con escape per attributo HTML	esc_attr__()	esc_attr_x()
	con escape per output HTML	esc_html__()	esc_html_x()
echo del testo tradotto	senza escape del testo	_e()	_ex()
	con escape per attributo HTML	esc_attr_e()	echo esc_attr_x()
	con escape per output HTML	esc_html_e()	echo esc_html_x()

Funzioni che prevedono la gestione della forma plurale:

output	escaping	forma plurale	forma plurale con contesto
restituzione del testo tradotto	senza escape del testo	_n()	_nx()
	con escape per attributo HTML	esc_attr( _n() )	esc_attr( _nx() )
	con escape per output HTML	esc_html( _n() )	esc_html( _nx() )
echo del testo tradotto	senza escape del testo	echo _n()	echo _nx()
	con escape per attributo HTML	echo esc_attr( _n() )	echo esc_attr( _nx() )
	con escape per output HTML	echo esc_html( _n() )	echo esc_html( _nx() )

Funzioni di base

Funzione __()

La funzione __() restituisce la traduzione di un testo $text, presa da un dominio $domain. Se non viene trovata la traduzione, la funzione restitusice il testo originale $text.

function __( $text, $domain = 'default' ) {
    return translate( $text, $domain );
}

Funzione esc_attr__()

La funzione esc_attr__() è come la __(), a cui aggiunge un filtro per rimuovere i caratteri speciali e rendere il testo tradotto compatibile con un attributo HTML.

function esc_attr__( $text, $domain = 'default' ) {
    return esc_attr( translate( $text, $domain ) );
}

Funzione esc_html__()

La funzione esc_html__() è come la __(), a cui aggiunge un filtro per rimuovere i caratteri speciali per rendere il testo tradotto compatibile con un output HTML.

function esc_html__( $text, $domain = 'default' ) {
	return esc_html( translate( $text, $domain ) );
}

Funzione _e()

La funzione _e() è come la __(), ma invece che restituire il testo tradotto, lo stampa direttamente in output con il comando echo.

function _e( $text, $domain = 'default' ) {
	echo translate( $text, $domain );
}

Funzione esc_attr_e()

La funzione esc_attr_e() è come la esc_attr__(), ma invece che restituire il testo tradotto, lo stampa direttamente in output con il comando echo.

function esc_attr_e( $text, $domain = 'default' ) {
	echo esc_attr( translate( $text, $domain ) );
}

Funzione esc_html_e()

La funzione esc_html_e() è come la esc_html__(), ma invece che restituire il testo tradotto, lo stampa direttamente in output con il comando echo.

function esc_attr_e( $text, $domain = 'default' ) {
	echo esc_attr( translate( $text, $domain ) );
}

Effetto sul file .POT

Le funzioni di base producono 4 record sul file .POT:

• una riga di commento (che inizia con i caratteri #:) indicante il file e la riga in cui compare il testo da tradurre
• una riga msgid con il testo da tradurre
• una riga msgstr vuota (conterrà il testo tradotto nella lingua appropriata su ciascun file .PO)
• una riga vuota di separazione.

Ad esempio, l’istruzione:

$description = __( "Validation errors occurred", 'contact-form-7' );

produrrà il seguente output sul file contact-form-7.pot:

#: includes/contact-form-template.php:165
msgid "Validation errors occurred"
msgstr ""

Funzioni di base con gestione del contesto

Soprattutto nel caso di singoli termini o brevi frasi, può succedere che uno stesso testo debba essere tradotto in modo diverso in base al contesto in cui viene utilizzato; le seguenti funzioni permettono di indicare il contesto a cui si deve fare riferimento.

Funzione _x()

La funzione _x() è come la __(), con la differenza che il testo tradotto viene prelevato dal contesto indicato nel parametro $context.

function _x( $text, $context, $domain = 'default' ) {
	return translate_with_gettext_context( $text, $context, $domain );
}

Funzione esc_attr_x()

La funzione esc_attr_x() è come la esc_attr__(), con la differenza che il testo tradotto viene preso dal contesto indicato nel parametro $context.

function esc_attr_x( $text, $context, $domain = 'default' ) {
	return esc_attr( translate_with_gettext_context( $text, $context, $domain ) );
}

Funzione esc_html_x()

La funzione esc_html_x() è come la esc_html__(), con la differenza che il testo tradotto viene preso dal contesto indicato nel parametro $context.

function esc_attr_x( $text, $context, $domain = 'default' ) {
	return esc_attr( translate_with_gettext_context( $text, $context, $domain ) );
}

Funzione _ex()

La funzione _ex() è come la _x(), ma invece che restituire il testo tradotto, lo stampa direttamente in output con il comando echo.

function _ex( $text, $context, $domain = 'default' ) {
	echo _x( $text, $context, $domain );
}

Effetto sul file .POT

Le funzioni per la gestione del contesto producono 5 record sul file .POT:

• una riga di commento (che inizia con i caratteri #:) indicante il file e la riga in cui compare il testo da tradurre
• una riga msgctxt con il contesto
• una riga msgid con il testo da tradurre
• una riga msgstr vuota (conterrà il testo tradotto nella lingua appropriata su ciascun file .PO)
• una riga vuota.

Ad esempio, l’istruzione:

echo esc_html_x( "Contact Lists: Select lists to which newly added contacts are to belong.", 'Constant Contact', 'contact-form-7' );

produrrà il seguente output sul file contact-form-7.pot:

#: modules/constant-contact.php:587
msgctxt "Constant Contact"
msgid "Contact Lists: Select lists to which newly added contacts are to belong."
msgstr ""

Rappresentazione del contesto su POEdit

Nel tool POEdit, il contesto viene visualizzato con uno sfondo azzurro, subito prima del testo da tradurre:

Funzioni che gestiscono la forma plurale

Quando un messaggio contiene un valore numerico, si presenta la necessità di adeguarne il contenuto alla forma singolare oppure alla forma plurale. La funzione _n() permette di gestire questi casi.

Funzione _n()

La funzione _n() accetta i seguenti parametri:

• $single: il testo da tradurre se il numero passato è singolare
• $plural: il testo da tradurre se il numero passato è plurale
• $number: il numero da utilizzare per decidere il testo da tradurre
• $domain: il dominio a cui far riferimento

La funzione restituirà la traduzione di $single se nella specifica lingua $number è considerato singolare e la traduzione di $plural nel caso contrario.

function _n( $single, $plural, $number, $domain = 'default' ) {
	$translations = get_translations_for_domain( $domain );
	$translation  = $translations->translate_plural( $single, $plural, $number );
	return apply_filters( 'ngettext', $translation, $single, $plural, $number, $domain );
}

Effetto sul file .POT

La funzione _n() produce 5 record sul file .POT:

• una riga di commento (che inizia con i caratteri #:) indicante il file e la riga in cui compare il testo da tradurre
• una riga msgid con il testo da tradurre nella forma singolare
• una riga msgid_plural con il testo da tradurre nella forma plurale
• una riga msgstr[0] vuota (conterrà il testo singolare tradotto nella lingua appropriata su ciascun file .PO)
• una riga msgstr[1] vuota (conterrà il testo plurale tradotto nella lingua appropriata su ciascun file .PO)
• una riga vuota.

Ad esempio, l’istruzione :

_n(
	/* translators: %s: number of errors detected */
	'%s configuration error detected',
	'%s configuration errors detected',
	$count_errors, 'contact-form-7' 
)

produrrà il seguente output sul file contact-form-7.pot:

#. translators: %s: number of errors detected
#: admin/includes/class-contact-forms-list-table.php:137
msgid "%s configuration error detected"
msgid_plural "%s configuration errors detected"
msgstr[0] ""
msgstr[1] ""

Rappresentazione della forma plurale su POEdit

Nel tool POEdit, è possibile inserire le traduzioni nella forma singolare e plurale in modo facilitato:

• nella sezione “testo sorgente” sono presenti entrambi i testi (singolare e plurale)
• nella sezione “Traduzione” è possibile cliccare su “singolare” per inserire la forma singolare della traduzione o su “plurale” per inserire la forma plurale.

Funzioni che gestiscono la forma plurale e il contesto

Funzione _nx()

Funzione _nx() gestisce il caso, piuttosto raro, di un testo con forma plurale che richieda traduzioni diverse, in base al contesto. A tal fine, la funzione prevede il parametro aggiuntivo $context.

function _nx( $single, $plural, $number, $context, $domain = 'default' ) {
    $translations = get_translations_for_domain( $domain );
    $translation  = $translations->translate_plural( $single, $plural, $number, $context );
 
    $translation = apply_filters( 'ngettext_with_context', $translation, $single, $plural, $number, $context, $domain );

    $translation = apply_filters( "ngettext_with_context_{$domain}", $translation, $single, $plural, $number, $context, $domain );
 
    return $translation;
}

Le funzioni JavaScript

Le funzioni JavaScript sono un sottoinsieme di quelle PHP e sono contenute nel file \wp-includes\js\dist\i18n.js:

• funzione __() per le traduzioni base
• funzione _x() per le traduzioni che richiedono un contesto
• funzione _x() per le traduzioni che contemplano la forma plurale
• funzione _nx() per le traduzioni che richiedono un contesto e contemplano la forma plurale

Corrispondenza con le funzioni gettext

Di seguito l’elenco delle funzioni WordPress per la localizzazione che hanno una corrispondenza con le funzioni gettext.

Funzioni WordPress PHP	Funzioni WordPress JavaScript	Funzioni gettext
__()	__()	dgettext()
_x()	_x()	dpgettext()
_n()	_n()	dngettext()