6.27.1 API GNU gettext

Il modulo gettext definisce la seguente API, che è molto simile alla API GNU gettext. Se usate questa API i suoi effetti interesseranno la traduzione della vostra applicazione globalmente. Spesso è ciò che desiderate se la vostra applicazione è monolingua, con la scelta della localizzazione dipendente da quella del vostro utente. Se state localizzando un modulo Python, o se la vostra applicazione ha bisogno di cambiare linguaggio al volo, probabilmente vorrete usare, al suo posto, la classe basata su API.

bindtextdomain( domain[, localedir]): Collega il dominio domain alla directory locale localedir. Più concretamente, gettext cercherà i file binari .mo per il dominio fornito, usando il percorso (su Unix): localedir/language/LC_MESSAGES/domain.mo, dove languages viene cercato rispettivamente nelle variabili d'ambiente LANGUAGE, LC_ALL, LC_MESSAGES e LANG.
Se localedir viene omesso o è None, allora viene restituito il corrente collegamento per il dominio domain.^6.2

textdomain( [domain]): Cambia o interroga il corrente dominio globale. Se domain è None, viene restituito il corrente dominio globale, altrimenti questo viene impostato e restituito a domain.

gettext( message): Restituisce la traduzione localizzata del messaggio message, basata sui correnti dominio globale, linguaggio e directory di localizzazione. Questa funzione viene di solito usata come _ nello spazio dei nomi locale (vedete gli esempi a seguito).

dgettext( domain, message): Come gettext(), ma cerca il messaggio nel dominio domain specificato.

ngettext( singular, plural, n)

Come gettext(), ma considera le forme plurali. Se viene trovata una traduzione, applica la formula plurale a n, e restituisce il messaggio risultante (alcuni linguaggi hanno più di due forme plurali). Se non viene rinvenuta alcuna traduzione, restituisce singular (NdT: singolare) se n è 1; altrimenti restituisce plural (NdT: plurale).

La formula Plurale viene presa dall'header del catalogo. È un'espressione in C o in Python che ha una variabile libera n; l'espressione valuta l'indice del plurale nel catalogo. Vedete la documentazione di GNU gettext per la sintassi esatta da usare nei file .po, e le formule per i vari linguaggi.

Nuovo nella versione 2.3.

dngettext( domain, singular, plural, n): Come ngettext(), ma cerca il messaggio nel dominio domain specificato.
Nuovo nella versione 2.3.

Notate che GNU gettext definisce anche un metodo dcgettext(), ma questo è stato definito inutile e quindi non più implementato.

Ecco un esempio di uso tipico di questa API:

import gettext
gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')
gettext.textdomain('myapplication')
_ = gettext.gettext
# ...
print _('This is a translatable string.')

Footnotes

...domain.^6.2: La directory predefinita contenente la localizzazione è dipendente dal sistema; per esempio,su RedHat Linux è /usr/share/locale, ma su Solaris è /usr/lib/locale. Il modulo gettext non cerca di supportare queste impostazioni dipendenti dal sistema, ma mantiene la propria impostazione predefinita in sys.prefix/share/locale. Per questo motivo, è sempre meglio chiamare bindtextdomain() con il suo percorso assoluto, all'inizio della vostra applicazione.

Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.