Aperçu

Le but de l'internationalisation d'une application est de permettre à une application web de proposer son contenu et ses fonctionnalités dans de multiples langages.

En tant que développeur Django vous pouvez atteindre ce but en ajoutant quelques appels de fonctions à votre code Python et à vos templates. Ces appels de fonctions sont appelés "texte à traduire" (translation strings). Elles indiquent à Django : "Ce texte devrait être traduit dans la langue de l'utilisateur, si une traduction pour ce texte est disponible dans cette langue".

Django se charge d'utiliser ces appels pour traduire à la volée les applications selon les préférences de l'utilisateur.

Essentiellement Django fait 2 choses :

• Il laisse aux développeurs et aux auteurs de templates le soin d'indiquer quelles parties de leurs applications devraient être traduites.
• Il utilise les appels "texte à traduire" pour traduire les applications web pour les utilisateurs selon leurs préférences de langue.

Si vous n'avez pas besoin de l'internationalisation

Les fonctions d'internationalisation de Django sont activées par défaut, cela signifie une surcharge dans certaines parties du framework. Si vous n'utilisez pas l'internationalisation, vous devriez prendre 2 secondes pour mettre USE_I18N = False dans votre fichier paramètre. Si USE_I18N est positionné à False, Django peut alors procéder à quelques optimisations telles que ne pas charger la machinerie relative à l'internationalisation.

Voir la documentation pour USE_I18N.

Comment spécifier les appels "texte à traduire"

Les appels "texte à traduire" signifient "Ce texte devrait être traduit". Ces appels peuvent apparaître dans votre code Python et vos templates. Il est de votre responsabilité de marquer les textes à traduire; le système ne peut traduire que les textes dont il a connaissance.

def my_view(request):
    output = _("Bienvenue sur mon site.")
    return HttpResponse(output)

from django.utils.translation import gettext
def my_view(request):
    output = gettext("Bienvenue sur mon site.")
    return HttpResponse(output)

def my_view(request):
    words = ['Bienvenue', 'sur', 'mon', 'site.']
    output = _(' '.join(words))
    return HttpResponse(output)

def my_view(request):
    sentence = 'Bienvenue sur mon site.'
    output = _(sentence)
    return HttpResponse(output)

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

from django.utils.translation import gettext_lazy

class MyThing(models.Model):
   name = models.CharField(help_text=gettext_lazy("Ceci est le texte d'aide"))

from django.utils.translation import gettext_lazy as _

class MyThing(models.Model):
    name = models.CharField(help_text=_("Ceci est le texte d'aide"))

from django.utils.translation import gettext_lazy as _

class MyThing(models.Model):
    name = models.CharField(_('name'), help_text=_("Ceci est le texte d'aide"))
    class Meta:
        verbose_name = _('my thing')
        verbose_name_plural = _('mythings')

from django.utils.translation import ngettext
def hello_world(request, count):
    page = ngettext("Il y'a %(count)d objet", "Il y'a %(count)d objets", count) % {
        'count': count,
    }
    return HttpResponse(page)

<title>{% trans "Ceci est un titre" %}</title>

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

{% blocktrans %}Ceci aura une {{ valeur }} à l'intérieur.{% endblocktrans %}

{% blocktrans with value|filter as myvar %}
Ceci aura {{ myvar }} à l'intérieur.
{% endblocktrans %}

{% blocktrans with book|title as book_t and author|title as author_t %}
Le livre {{ book_t }} de l'auteur {{ author_t }}
{% endblocktrans %}

{% blocktrans count list|count as counter %}
Il y'a seulement un objet {{ name }}
{% plural %}
Il y'a {{ counter }} objets {{ name }}.
{% endblocktrans %}

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

{% some_special_tag _("Page non trouvée") value|yesno:_("oui,non") %}

Comment créer des fichiers de langues

Une fois que vous avez marqué vos textes pour une future traduction, vous devez écrire (ou obtenir) les traductions proprement dites. Voici comment cela fonctionne :

bin/make-messages.py -l de

_("Bienvenue sur mon site.")

#: chemin/vers/python/module.py:23
msgid "Bienvenue sur mon site."
msgstr ""

make-messages.py -a

bin/compile-messages.py

Comment Django identifie les préférences de langue

Une fois que vos traductions sont prêtes -- ou, si vous désirez utiliser uniquement les traductions livrées avec Django -- vous devez activer la traduction pour votre application.

Derrière les rideaux, Django a un mécanisme très souple pour décider quelle langue devrait être utilisée -- propre à l'installation, pour un utilisateur en particulier, ou pour les 2.

Pour indiquer des préférences de langue propres à une installation de Django, positionnez LANGUAGE_CODE dans votre fichier de paramètres Django. Django utilise cette langue comme la langue par défaut -- si aucune autre n'est trouvée.

Si tout ce que vous voulez est de lancer Django sous votre langue natale, et un fichier de langue est disponible pour celle-ci, tout ce que vous avez à faire est de positionner LANGUAGE_CODE.

Si vous voulez que chaque utilisateur puisse indiquer quelle langue il ou elle préfère, utilisez LocaleMiddleware. LocaleMiddleware active la sélection de langue en fonction de données fournies dans la requête. Il adapte le contenu pour chaque utilisateur.

Pour utiliser LocaleMiddleware, ajoutez 'django.middleware.locale.LocaleMiddleware' à votre paramètre MIDDLEWARE_CLASSES. Parce que l'ordre des middleware compte, vous devriez suivre ces conseils:

• Soyez sûr que c'est un des premiers middlewares installé.
• Il devrait suivre SessionMiddleware, parce que LocaleMiddleware utilise les données de session.
• Si vous utilisez CacheMiddleware, mettez LocaleMiddleware après lui.

Par exemple, votre MIDDLEWARE_CLASSES pourrait ressembler à ceci:

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

(Pour plus d'informations sur les middleware, voir la documentation sur les middleware.)

LocaleMiddleware tente de déterminer les préférences de langue de l'utilisateur en suivant cet algorithme:

• Premièrement, il recherche une clé django_language dans la session courante de l'utilisateur.
• Si cela échoue, il recherche un cookie de nom django_language.
• Si cela échoue, il recherche un en-tête HTTP Accept-Language. Cet en-tête est envoyé par votre navigateur et indique au serveur quel(s) langue(s) vous préférez, par ordre de priorité décroissante. Django essai chaque langue dans cet en-tête jusqu'à ce qu'il trouve une traduction existante.
• Si tout cela échoue, il utilise la préférence globale LANGUAGE_CODE.

Notes:

• À chacun de ces endroits, la préférence de langue est attendue dans le format standard, comme une chaîne de caractères. Par exemple, le brésilien est indiqué comme pt-br.

• Si une langue de base est disponible mais le dialecte spécifié ne l'est pas, Django utilise la langue de base. Par exemple, si un utilisateur indique de-at (allemand autrichien) mais Django ne dispose que de de, Django utilisera de.

• Seules les langues listées dans le paramètre LANGUAGES peuvent être sélectionnées. Si vous voulez restreindre la sélection de langue à un sous-ensemble des langues fournies (parce que par exemple votre application ne fournie pas toutes ces langues); positionnez LANGUAGES à une liste appropriées. Par exemple:

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

  Cet exemple limite les langues disponibles pour une

  sélection automatique à l'allemand et l'anglais (et tous les dialectes correspondants, comme de-ch ou en-us).

• Si vous définissez le paramètre LANGUAGES, comme

  expliqué dans le point ci-dessus, il est possible d'indiquer les langues comme des chaînes à traduire -- mais utilisez une fonction gettext() "vide", pas celle dans le module django.utils.translation. Vous ne devriez jamais importer django.utils.translation à partir de votre fichier paramètres, parce que ce module dépend lui même des paramètres, ce qui créerait un import circulaire.

  La solution est d'utiliser une fonction gettext vide. Ci-dessous un exemple de fichier paramètre:

  gettext = lambda s: s
  
  LANGUAGES = (
          ('de', gettext('German')),
          ('en', gettext('English')),
  )
  

  Avec ce code, make-messages.py trouvera et marquera toujours ces chaînes comme à traduire, mais la traduction ne se fera pas lors de l'exécution du code -- aussi vous devrez vous rappeler d'englober les chaînes à traduire avec la véritable fonction gettext() dans tout code qui utilise LANGUAGES lors de l'exécution du code.

• Le LocaleMiddleware peut sélectionner uniquement les langues pour lesquelles Django fournit une traduction de base. Si vous désirez fournir une traduction pour votre application qui n'est pas déjà dans l'ensemble des traductions incluses dans les sources Django, vous devrez au moins fournir une traduction de base pour cette langue. Par exemple, Django utilise des messages ID technique pour traduire les formats de date et de temps -- aussi vous aurez au minimum besoin d'avoir ces traductions pour que le système fonctionne correctement.

  Un bon point de départ est de copier le fichier .po anglais et de traduire au minimum les messages techniques -- peut être également les messages de validation.

  Les messages ID techniques sont facilement reconnaissables; ils sont tous en majuscules. Vous ne traduisez pas les messages ID comme les autres messages, vous fournissez la variante locale correcte correspondante à la valeur anglaise. Par exemple, avec DATETIME_FORMAT (ou DATE_FORMAT ou TIME_FORMAT), cela serait la chaîne de format que vous voulez utiliser pour cette langue. Le format est identique aux chaînes de format utilisées avec le tag de template now.

Une fois que LocaleMiddleware a déterminé la préférence de l'utilisateur, il rend cette préférence disponible dans request.LANGUAGE_CODE pour chaque objet requête. Vous êtes libre d'utiliser cette valeur dans votre code. Voici un simple exemple:

def hello_world(request, count):
    if request.LANGUAGE_CODE == 'de-at':
        return HttpResponse("Vous préférez lire l'allemand autrichien")
    else:
        return HttpResponse("Vous préférez lire une autre langue")

Notez qu'avec une traduction statique (sans middleware), la langue est dans settings.LANGUAGE_CODE, tandis qu'avec une traduction dynamique (middleware) elle est dans request.LANGUAGE_CODE.

La vue de redirection set_language

À titre de facilité, Django est fournie avec une vue, django.views.i18n.set_language, qui positionne les préférences de langue de l'utilisateur puis redirige vers la page précédente.

Activez cette vue en ajoutant la ligne suivante dans votre URLconf:

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

(Notez que cet exemple rend la vue disponible à l'url /i18n/setlang/.)

La vue attend a être appelée via la méthode GET, avec un paramètre language positionné dans la chaîne de requête. Si le support des sessions est activé, la vue sauvegarde le choix de la langue dans la session de l'utilisateur. Autrement, elle sauvegarde le choix de la langue dans un cookie django_language.

Après avoir positionné le langage choisi, Django redirige l'utilisateur, selon l'algorithme suivant:

• Django recherche un paramètre de nom next dans la chaîne de requête.
• Si celui-ci n'existe pas, ou est vide, Django essai l'URL de l'en-tête Referer.
• Si celui-ci est vide -- disons, si le navigateur de l'utilisateur supprime cet en-tête -- alors l'utilisateur sera redirigé vers / (la racine du site) à défaut.

Ci-dessous un exemple HTML dans un template:

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

Utilisation des traductions dans vos propres projets

Django recherche des traductions en suivant cet algorithme:

• Premièrement, il recherche un répertoire locale dans le répertoire de l'application de la vue qui est appelée. Si il trouve une traduction pour la langue sélectionnée, elle sera installée.
• Ensuite, il recherche un répertoire locale dans le répertoire du projet Django. Si il trouve une traduction, elle sera installée.
• Finalement, il vérifie les traductions de base dans django/conf/locale.

De cette manière vous pouvez écrire des applications qui inclut leur propre traductions, et vous pouvez redéfinir les traductions de base dans votre répertoire projet Django. Ou, vous pouvez élaborer un grand projet à partir de plusieurs applications et mettre l'ensemble des traductions dans un grand et unique fichier messages du projet. Le choix vous appartient.

L'ensemble des répertoires de fichiers messages ont une structure identique :

• $APPPATH/locale/<langue>/LC_MESSAGES/django.(po|mo)
• $PROJECTPATH/locale/<langue>/LC_MESSAGES/django.(po|mo)
• Tous les chemins indiqués dans la variable LOCALE_PATHS de votre fichier paramètres sont parcourus dans cet ordre à la recherche de fichiers <langue>/LC_MESSAGES/django.(po|mo)
• $PYTHONPATH/django/conf/locale/<langue>/LC_MESSAGES/django.(po|mo)

Pour créer des fichiers de traduction, vous utilisez le même utilitaire que pour la traduction des fichiers de traduction Django, à savoir make-messages.py. Vous devez seulement vous assurer que vous êtes au bon endroit -- soit dans le répertoire parent de conf/locale (si dans la hiérarchie source Django) soit dans le répertoire parent de locale/``(si il s'agit de traductions de projets ou d'applications). Et vous utilisez le même utilitaire ``compile-messages.py pour générer les fichiers binaires django.mo utilisés par gettext.

Les fichiers de traduction des applications sont plus difficiles à détecter -- ils ont besoin de LocaleMiddleware. Si vous n'utilisez pas le middleware, seuls les fichiers de traduction de Django et des projets seront traités.

Pour finir, vous devriez réfléchir à la structure de vos fichiers de traduction. Si vos applications doivent être distribuées à d'autres utilisateurs pour être utilisées dans d'autres projets, vous pourriez vouloir faire des traductions spécifiques à vos applications. Mais faire des traductions spécifiques à des applications ou à des projets pourrait générer des problèmes avec make-messages: make-messages parcourt l'ensemble des répertoires situés sous le chemin courant et en conséquence pourrait mettre des messages ID dans le fichier de traduction du projet qui sont déjà dans les fichiers de traduction des applications.

Le meilleur moyen de s'en sortir est de mettre les applications qui ne font pas partie du projet (et donc qui comportent leur propre traductions) en dehors de la hiérarchie du projet. De cette manière, make-messages lancé à partir du répertoire du projet ne traduira que les chaînes qui sont spécifiques à votre projet et non les chaînes distribuées indépendamment.

Traductions et Javascript

Ajouter des traductions à Javascript pose certains problèmes :

• Le code Javascript n'a pas accès à la librairie gettext.
• Le code Javascript n'a pas accès aux fichiers .po ou .mo; ils doivent être envoyés par le serveur.
• Le catalogue des chaînes traduites pour Javascript devrait être aussi léger que possible.

Django fournit une solution intégrée pour ces problèmes : il transmet les traductions à Javascript de telle manière que vous puissiez appeler gettext, etc... à partir de votre code Javascript.

js_info_dict = {
    'packages': ('votre.application.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="/chemin/vers/jsi18n/"></script>

document.write(gettext('ceci est à traduire'));

d = {
    count: 10
};
s = interpolate(ngettext("il y'a %(count)s objet", "il y'a ù%count)s objets", d.count), d);

s = interpolate(ngettext("il y'a %s objet", "il y a %s objets", 11), [11]);

make-messages.py -d djangojs -l de

Particularités de la traduction Django

Si vous connaissez gettext vous pourriez remarquer ces particularités dans la manière dont Django effectue les traductions:

• La chaîne de domaine est django ou djangojs. La chaîne de domaine est utilisée pour différencier entre différents programmes qui stockent leurs données dans un fichier des messages commun (généralement /usr/share/locale). Le domaine django est utilisé par Python et les chaînes de traduction des templates et est chargé dans les catalogues de traductions globaux. Le domaine djangojs est uniquement utilisé pour les catalogues de traductions Javascript pour être sûr qu'ils sont le plus lèger possible.
• Django utilise uniquement gettext et gettext_noop. Parce que Django utilise toujours les chaînes DEFAULT_CHARSET de manière interne. Il n'y a pas beaucoup matière à utiliser ugettext car vous devrez toujours fournir utf-8 dans tous les cas.
• Django n'utilise pas xgettext seul. Il utilise des enveloppes Python autour de xgettext et msgfmt. Principalement pour convenance.