Le livre de

Préciser les chaînes de traduction dans du code Python

Les chaînes de traduction précisent que «ces chaînes de caractère doivent être traduites». Ces chaînes peuvent apparaîtres dans votre code Python ou dans vos gabarits. Le marquage des chaînes traduisibles reste à votre charge; le système ne peut traduire que les chaînes dont il à connaissance.

def my_view(request):
    output = _("Welcome to my site.")
    return HttpResponse(output)

from django.utils.translation import gettext
def my_view(request):
    output = gettext("Welcome to my site.")
    return HttpResponse(output)

def my_view(request):
    words = ['Welcome', 'to', 'my', 'site.']
    output = _(' '.join(words))
    return HttpResponse(output)

def my_view(request):
    sentence = 'Welcome to my site.'
    output = _(sentence)
    return HttpResponse(output)

def my_view(request, n):
    output = _('%(name)s is my name.') % {'name': n}
    return HttpResponse(output)

from django.utils.translation import gettext_lazy

class MyThing(models.Model):
    name = models.CharField(help_text=gettext_lazy('This is the
    help text'))

from django.utils.translation import gettext_lazy as _

class MyThing(models.Model):
    name = models.CharField(help_text=_('This is the help text'))

from django.utils.translation import gettext_lazy as _

class MyThing(models.Model):
    name = models.CharField(_('name'), help_text=_('This is the
    help text'))
    class Meta:
        verbose_name = _('my thing')
        verbose_name_plural = _('mythings')

from django.utils.translation import ngettext
def hello_world(request, count):
    page = ngettext(
        'there is %(count)d object',
        'there are %(count)d objects', count
    ) % {'count': count}
    return HttpResponse(page)

Préciser les chaînes de traduction dans le code du gabarit

L’utilisation des traductions dans les gabarits Django repose sur deux balises de gabarits et une légère différence de syntaxe par rapport au code Python. Pour donner à votre gabarit l’accès à ces balises, placez {% load i18n %} en haut de votre gabarit.

La balise de gabarit {% trans %} marque une chaîne à traduire:

<title>{% trans "This is the title." %}</title>

Si vous voulez seulement marquer une valeur à traduire, mais faire la traduction plus tard, utlisez l’option noop:

<title>{% trans "value" noop %}</title>

Il n’est pas possible d’utiliser les variables de gabarit au sein de {% trans %} - seules les chaînes constantes, entre simple ou double parenthèses, sont permises. Si votre traduction nécessite des variables (substitutions), utilisez {% blocktrans %}, par exemple:

{% blocktrans %}This will have {{ value }} inside.{% endblocktrans %}

Pour traduire une expression de gabarit - disons, utiliser les filtres de gabarit - vous devez lier l’expression à une variable locale à utiliser dans le bloc de traduction:

{% blocktrans with value|filter as myvar %}
  This will have {{ myvar }} inside.
{% endblocktrans %}

Si vous devez lier plus d’une expression à l’intérieur d’une balise blocktrans, séparez les parties à l’aide de and:

{% blocktrans with book|title as book_t and author|title as author_t %}
  This is {{ book_t }} by {{ author_t }}
{% endblocktrans %}

Pour pluraliser, précisez à la fois les formes singulière et plurielle avec la balise {% plural%}, qui apparait entre {% blocktrans %} et {% endblocktrans %}, par exemple:

{% blocktrans count list|length as counter %}
  There is only one {{ name }} object.
{% plural %}
  There are {{ counter }} {{ name }} objects.
{% endblocktrans %}

En interne, tous les blocs et les traductions en ligne utilisent l’appel gettext/ngettext approprié.

Lorsque vous utilisez RequestContext (lisez le Chapitre 10), vos gabarits ont accès à trois variables spécifique à la traduction:

• {{ LANGUAGES }} est une liste de tuples dans laquelle le premier élément est le code de langue et le second est le nom de la langue (dans cette langue).
• {{ LANGUAGE_CODE }} est la langue courante préférée de l’utilisateur, sous forme de chaîne (par exemple, en-us). (Lisez «Comment Django trouve la préférence linguistique» pour plus d’information).
• {{ LANGUAGE_BIDI }} est la langue courante du système d’écriture. Si elle est à True, il sagit d’une langue de-droite-à-gauche (par exemple, l’Arabe, l’Hébreu). Si elle est à False, il s’agit d’une langue de gauche-à-droite (par exemple, l’Anglais, le Français, l’Allemand).

Vous pouvez aussi charger ces valeurs en utilisant les balises de gabarits:

{% load i18n %}
{% get_current_language as LANGUAGE_CODE %}
{% get_available_languages as LANGUAGES %}
{% get_current_language_bidi as LANGUAGE_BIDI %}

Les points d’entrée de traduction sont aussi disponibles dans tous les blocs de gabarit qui acceptent des chaînes constantes. Dans ces cas, utilisez la syntaxe _() pour préciser une chaîne de traduction, par exemple:

{% some_special_tag _("Page not found") value|yesno:_("yes,no") %}

Dans ce cas, la balise et le filtre verront la chaîne déjà traduite (c’est à dire aue la chaîne est traduite avant d’être transmise au fonctions gestionnaires de balise), aussi n’ont-elles pas besoin d’être au courant des traducitons.

Créer des fichiers de langue

Une fois que vous avez balisé vos chaînes pour une traduction ultérieure, vous devez écrire (ou obtenir) les langues de traduction elles-mêmes. Dans cette section nous expliquons comment cela fonctionne.

bin/make-messages.py -l de

_("Welcome to my site.")

#: path/to/python/module.py:23
msgid "Welcome to my site."
msgstr ""

msgid ""
"There's been an error. It's been reported to the site administrators
via e-"
"mail and should be fixed shortly. Thanks for your patience."
msgstr ""
"Ha ocurrido un error. Se ha informado a los administradores del
sitio "
"mediante correo electr?nico y deber?a arreglarse en breve. Gracias
por su "
"paciencia."

make-messages.py -a

bin/compile-messages.py

Comment Django trouve la préférence linguistique

Lorsque vous avez préparé vos traductions - ou, si vous voulez seulement utiliser les traductions qui sont incluses dans Django - vous devrez activer la traduction pour votre application.

En coulisses, Django possède un modèle très flexible pour décider quel est la langue à utiliser - pour toute l’installation, pour un utilisateur particulier, ou les deux.

Pour paramétrer une préférence de langue sur l’ensemble du site, configurez LANGUAGE_CODE dans votre fichier de paramètres. Django utilise cette langue comme celle étant la traduction par défaut - c’est à dire en dernier recours si aucun traducteur ne trouve de traduction.

Si vous voulez simplement lancer Django avec votre langue native, et qu’un fichier de langue est disponible pour celle-ci, il suffit de configurer LANGUAGE_CODE.

Si vous voulez laisser chaque utilisateur individuel préciser la langue qu’il ou elle préfère, utilisez LocaleMiddleware. LocaleMiddleware active la selection des langues sur la base des données issues de la requête. Il personnalise le contenu pour chaque utilisateur.

Pour utiliser LocaleMiddleware, ajoutez 'django.middleware.locale.LocaleMiddleware' à votre paramètre MIDDLEWARE_CLASSES. Puisque l’ordre des middlewares importe, vous devez suivre ces consignes:

• Assurez vous qu’il est parmi les premières classes de middleware installées.
• il doit être placé après SessionMiddleware, parce que LocaleMiddleware utilise les données de session.
• Si vous utilisez CacheMiddleware, placez LocaleMiddleware après lui (autrement les utilisateurs peuvent obtenir du contenu en cache depuis la mauvaise localisation).

Par exemple, votre MIDDLEWARE_CLASSES doit ressembler à ceci:

MIDDLEWARE_CLASSES = (
   'django.middleware.common.CommonMiddleware',
   'django.contrib.sessions.middleware.SessionMiddleware',
   'django.middleware.locale.LocaleMiddleware'
)

LocaleMiddleware essaie de déterminer la préférence de langue de l’utilisateur en suivant cet algorithme:

• premièrement, il cherche une clef django_language dans la session courante de l’utilisateur.
• si cela échoue, il cherche un cookie appelé django_language.
• si cela échoue, il cherche l’en-tête HTTP Accept-Language. Cet en-tête est envoyé par votre navigateur et indique au serveur quelle(s) langue(s) vous préféré, selon l’odre des priorité. Django essaie chaque langue de l’en-tête jusqu’a ce qu’il en trouve un ayant des traductions disponibles.
• si cela échoue, il utilise le paramètre global LANGUAGE_CODE.

Dans chaquun de ces endroits, la préférence de langue est censée être au format de langue standard, sous forme de chaîne. Par exemple, le Portuguais Brésilien est pt-br. Si une langue de base est disponible mais que le sous-langage précisé ne l’est pas, Django utilise la langue de base. Par exemple, si un utilisateur précise de-at (Allemand Autrichien) mais que Django ne possède que de de disponible, Django utilise de.

Seules les langues listées dans le paramètre LANGUAGES peuvent être choisies. Si vous voulez restreindre la selection des langues à une poignée parmi les langues disponibles, (parce que votre application ne fourni pas toutes ces langues), fixez votre paramètre LANGUAGES sous forme de liste de langues, par exemple:

LANGUAGES = (
    ('de', _('German')),
    ('en', _('English')),
)

Cet exemple restreint les langues disponibles pour une selection automatique à l’Allemand et à l’Anglais (et tout les dérivés, tels que de-ch ou en-us).

Si vous définissez des LANGUAGES personalisés, il est possible de marquer ces langues comme étant des chaînes de traduction - il faut alors utiliser la fonction factice gettext() et non celle présente dans django.utils.translation. Vous ne devez jamais importer django.utils.translation depuis votre fichier de paramètres, parce que ce module dépend lui-même des paramètres, ceci pourrait créer un import circulaire.

La solution est d’utiliser la fonction factice gettext(). Voici un fichier de paramètre pour l’exemple:

_ = lambda s: s

LANGUAGES = (
      ('de', _('German')),
      ('en', _('English')),
)

Avec cet arrangement, make-messages.py continuera à trouver et à marquer ces chaînes pour traduction, mais la traduction n’arrivera pas lors de l’exécution, vous devrez donc vous souvenir d’emballer les langues dans la fonction gettext() réelle au sein de n’importe quel code qui utilise LANGUAGES lors de l’exécution.

LocaleMiddleware peut seulement sélectioner les langues pour lesquelles il existe une base de traduction fournie par Django. Si vous voulez fournir des traductions pour votre application qui ne sont pas encore dans le jeu de traduction de l’arborescence de Django, vous devrez fournir au moins une traduction basique pour cette langue. Par exemple, Django utilise les IDs des messages techniques pour traduire les formats de date et d’heure - vous aurez donc au moins besoin de ces traduction pour que le système fonctionne coorectement.

Un bon point de départ consiste à copier le fichier Anglais .po et de traduire au moins les messages techniques, et peut être aussi les messages de validation.

Les IDs de message technique sont facilement reconnaissables; ils sont tous en capitales. Vous n’avez pas traduire le message ID comme comme pour les autres messages; au lieu de cela, vous fournissez la variante locale correcte pour la valeur Anglaise prévue. Par exemple, avec DATETIME_FORMAT (ou DATE_FORMAT ou TIME_FORMAT), ceci pourrait être le format de la chaîne que vous voulez utiliser dans votre langue. Le format est identique au format des chaînes utilisées par la balise de gabarit now.

Une fois que le LocaleMiddleware determine la préférence de l’utilisateur, il met à disposition cette varaibel sous la forme de request.LANGUAGE_CODE pour chaque objet requête. N’hésitez pas à lire cette valeur dans le code de votre vue. Voici un simple exemple:

def hello_world(request, count):
    if request.LANGUAGE_CODE == 'de-at':
        return HttpResponse("You prefer to read Austrian
        German.")
    else:
        return HttpResponse("You prefer to read another
        language.")

Notez qu’avecla traduction statique (c’est à dire sans middleware), la langue se trouve dans settings.LANGUAGE_CODE, alors qu’avec une traduction dynamique (midleware), elle se trouve dans request.LANGUAGE_CODE.

La vue de redirection set_language

Par commodité, Django propose une vue, django.views.i18n.set_language, qui fixe la préférence de langue d’un utilisateur puis redirige sur la page précédente.

Acitvez cette vue en ajoutant la ligne suivante à votre URLconf:

(r'^i18n/', include('django.conf.urls.i18n')),

(Notez que cet exemple rends la vue disponible à l’adresse /i18n/setlang/.)

Cette vue s’attend à être appelée via la méthode GET, avec un paramètre language fixé dans la chaîne de requête. Si le support de session est activé, la vue conserve le choix de la langue dans la session de l’utilisateur. Autrement, elle conserve le choix de la langue dans une cookie django_language.

Après avoir déterminer le choix de la langue, Django redirige l’utilisateurn en suivant cet algorithme:

• Django recherche un paramètre next dans la chaîne de requête.
• S’il n’existe pas ou s’il est vide, Django essaie l’URL du Referer de l’en-tête.
• Si cela est vide - admettons que le navigateur d’un utilisateur supprime cet en-tête - alors l’utilisateur sera redirigé vers / (la racine du site) en ultime recours.

Voici un exemple de code HTML pour un gabarit:

<form action="/i18n/setlang/" method="get">
<input name="next" type="hidden" value="/next/page/" />
<select name="language">
{% for lang in LANGUAGES %}
<option value="{{ lang.0 }}">{{ lang.1 }}</option>
{% endfor %}
</select>
<input type="submit" value="Go" />
</form>

Utiliser les chaînes de traduction dans vos propres projets

Utiliser les chaînes de traduction dans vos propres projets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Django recherche les traductions ensuivant cet algorithme:

• Tout d’abord, il cherche un répertoire de locale dans le dossier de l’application correspondant à la vue qui est appelée. S’il trouve une traduciton pour la langue sélectionnée, la traduction sera installée.
• Ensuite, il recherche un répertoire locale dans le dossier du projet. S’il trouve une traduction, celle-ci sera installée.
• Enfin, il regarde vers la traduction de base dans django/conf/locale.

De cette façon, vous pouvez écrire des applications qui embarquent leurs propres traductions, et vous pouvez outrepasser les traductions de base dans le chemin de votre projet. Vous pouvez aussi simplement construire un gros projet à partir de plusieurs applications et placer toutes les traductions dans un seul gros fichier message de ce projet. C’est vous qui décidez.

Tous les dépôts de fichier message sont structurés de la même façon:

• $APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)
• $PROJECTPATH/locale/<language>/LC_MESSAGES/django.(po|mo)
• tous les chemins listés dans le LOCALE_PATHS de votre fichier de paramètres sont recherchés dans cet ordre <language>/LC_MESSAGES/django.(po|mo)
• $PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)

Pour créer des fichiers message, utilisez le même outil make-messages.py tout comme pour les fichiers message. Vous aurez seulement besoin d’être à la bonne place - dans le répertoire où se trouve soit conf/locale (dans le cas de l’arborescence source), soit dans le répertoire ou se trouve locale/ (dans le cas des messages de l’application ou des messages du projet). Vous utiliserez de même compile-messages.py pour produire les fichiers binaires django.mo qui sont utilisés par gettext.

Les fichiers message des applications sont un peu plus compliqués à trouver - ils nécessitent LocaleMiddleware. Si vous n’utilisez pas le middleware, seul les fichiers message de Django et les fichiers message de projet seront traités.

Finallement, vous devrez penser à la structure de vos fichiers de traduction. Si vos applications doivent être livrées à d’autres utilisateur pour être utilisées dans d’autres projets, vous pourriez vouloir utiliser des traductions spécifique à l’application. Utiliser des traductions spécifiques à l’application et des traductions de projet peut générer des problèmes étranges avec make-messages. make-messages parcourera tous les répertoires appartenant au chemin courant et peut donc placer des IDs de message dans le fichier de message du projet qui sont déjà dans les fichiers message de l’application.

La manière la plus simple de s’en sortir consiste à stocker les applications qui ne font pas partie du projet (et qui embarquent leurs propres traductions) à l’exterieur de l’arborescence du projet. De cette façon, make-messages au niveau du projet traduira uniquement les chaînes qui sont connectées à votre projet, sans les chaînes qui sont distribuées indépendament.

Traductions et Javascript

Ajouter des traductions au Javascript pose quelques problèmes:

• le code JavaScript n’a pas accès à une implémentation de gettext.
• le code JavaScript n’a pas accès aux fichiers .po ou .mo; ils doivent être fournis par le serveur.
• les catalogues de traductions pour Javascript doivent être gardés aussi petits que possible.

Django fourni une solution intégrée pour ces problèmes: elle transmet les traductions au Javascript, ainsi pouvez-vous appeler gettext et consort depuis Javascript.

js_info_dict = {
    'packages': ('your.app.package',),
}

urlpatterns = patterns('',
    (r'^jsi18n/$', 'django.views.i18n.javascript_catalog',
    js_info_dict),
)

urlpatterns = patterns('',
    (r'^jsi18n/(?P<packages>\S+?)/$,
    'django.views.i18n.javascript_catalog'),
)

<script type="text/javascript" src="/path/to/jsi18n/"></script>

document.write(gettext('this is to be translated'));

d = {
    count: 10
};
s = interpolate(ngettext('this is %(count)s object', 'this are
%(count)s objects', d.count), d);

s = interpolate(ngettext('this is %s object', 'this are %s objects', 11),[11]);

make-messages.py -d djangojs -l de

Notes pour les utilisateurs familier de gettext

Si vous connaissez gettext, vous pouvez notez la façon particulière dont Django effectue les traductions:

• le domaine de chaîne est django ou djangojs. Le domaine de chaîne est utilisé pour différencier des programmes qui stockent leurs données dans une bibliothèque standard de fichier message (habituellement /usr/share/locale/). Le domaine django est utilisé pour Python et pour les chaînes de traduction de gabarit, et est chargé globalement dans les catalogues de traduction. Le domaine djangojs est seulement utilisé pour les catalogues de traduction Javascript afin de s’assurer que ceux-ci sont aussi petits que possible.
• Django utilise uniquement gettext et gettext_noop. C’est parce que Django utilise toujours les chaînes DEFAULT_CHARSET en interne. Il n’y a pas beaucoup de bénéfice à utliser ugettext, puisque vous aurez toujours besoin de produire de l’UTF-8 quoi qu’il en soit.
• Django n’utilise pas xgettext seul. Il utilise un emballage Python autour de xgettext et de msgfmt. C’est principalement par commodité.

Et ensuite ?

Ce chapitre assure la couverture des fonctionnalités de Django. Vous devez en savoir assez pour commencer à produire vos propres sites Django.

Cependant, écrire le code est seulement la première étape dans le déploiement réussi d’un site web. Les deux prochains chapitres couvrent les choses dont vous devrez connaître si vous voulez que votre site survive au monde réel. Le chapitre 19 aborde la façon dont vous pouvez sécuriser vos sites et vos utilisateurs des attaques malicieuses, et le chapitre 20 détaille la façon de déployer une application Django sur un ou plusieurs serveurs.

<< précédent ◊ suivant >>