Internazionalizzazione e Localizzazione

Internazionalizzazione e localizzazione su Django sono gestiti separatamente e governati rispettivamente dalla configurazione USE_I18N e USE_L10N nei settings. Entrambi sono abilitati per default.

Internazionalizzazione

Per abilitare la traduzione su una lingua diversa per ogni sessione utente è necessario abilitare il middleware LocaleMiddleware, che andremo ad aggiungere alla configurazione MIDDLEWARE nel file settings.py:

MIDDLEWARE = [
   ...
   'django.contrib.sessions.middleware.SessionMiddleware',
   'django.middleware.locale.LocaleMiddleware',
   'django.middleware.common.CommonMiddleware',
   ...
]

Questo middleware deve essere inserito tra quello che gestisce la sessione SessionMiddleware e CommonMiddleware. Il middleware si occuperà di settare nella request passata ad ogni vista la variable LANGUAGE_CODE contenente la lingua corrente per la sessione dell'utente.

Sempre in settings.py è possibile configurare la lingua di default del sistema settando LANGUAGE_CODE. Ad esempio se vogliamo usare l'italiano per default:

LANGUAGE_CODE = 'it-it'

Le lingue per cui abilitiamo la traduzione devono essere listate esplicitamente nella configurazione LANGUAGES:

from django.utils.translation import gettext_lazy as _

LANGUAGES = [
    ('it', _('Italian'),
    ('en', _('English'),
]

Per far cambiare la lingua agli utenti Django offre una vista già implementata chiamata set_language che richiede il codice della lingua passato in POST nella variabile language.

Per essere usata basta includere le seguenti urls nel nostro progetto, ad esempio sotto il percorso i18n:

urlpatterns = [
   ...
   path('i18n/', include('django.conf.urls.i18n')),
]

In questo caso la vista sarà disponibile al percorso /i18n/setlang/. Si rimanda alla documentazione di set_language per maggiori dettagli.

Lo stato delle traduzioni per le varie lingue è disponibile su transifex.

Traduzioni nelle viste

Il sistema di traduzioni di Django è un wrapper sopra alle funzioni di GNU gettext.

La funzione base per tradurre una stringa è gettext che è consuetudine importare come _:

from django.http import HttpResponse
from django.utils.translation import gettext as _
from django.views import View


class HomepageView(View):
    def get(self, request):
        return HttpResponse(_("This is the homepage"))

Traduzioni lazy

Le stringhe possono essere tradotte in modo lazy cioè tradotte nel momento specifico in cui sono renderizzate e non quando sono definite. Queste tipo di traduzioni sono necessarie in alcuni punti come negli attributi help_text e verbose_name dei campi dei modelli, negli attributi verbose_name e verbose_name_plural nella classe Meta dei modelli e nel file settings.py.

Le traduzioni di tipo lazy si fanno usando la funzione gettext_lazy:

from django.db import models
from django.utils.translation import gettext_lazy as _


class Corso(models.Model):
    titolo = models.CharField(help_text=_('Titolo'))

Template

Le traduzioni nei template vengono fatte tramite il tag translate che opera indistintamente sia su stringhe costanti che su variabili:

<h1>{% translate "Il titolo" %}</h1>
<h2>{% translate sottotitolo %}</h2>

Generare i file delle traduzioni

I file delle traduzioni sono cercati per default in directory chiamate locale all'interno di ogni applicazione configurata e in ogni directory configurata in LOCALE_PATHS.

Le directory locale all'interno delle nostri applicazioni e quelle configurate in LOCALE_PATHS devono essere create manualmente. È buona cosa creare una directory locale per ogni applicazione che ha delle stringhe traducibili ed una generale per le stringhe che sono presenti nei file di progetto o nei templates condivisi.

Per estrarre le stringhe da tradurre per una singola lingua bisogna eseguire il comando makemessages:

django-admin makemessages -l it

In questo caso abbiamo estratto le stringhe da tradurre per la lingua italiana it. Le stringhe vengono estratte in file chiamati django.po all'interno di ogni directory it presente all'interno di ogni directory locale globale o della singola applicazione.

Una volta tradotti i file django.po possono essere compilati in file django.mo tramite il comando:

django-admin compilemessages

Localizzazione

Il sistema di localizzazione di Django permette di formattare date, orari e numeri nei template. Quando è attivato questi tipidi dato vengono formattati a seconda del linguaggio configurato nella sessione. La formattazione che inserisce il separatore per le migliaia va attivato separatamente tramite la configurazione USE_THOUSAND_SEPARATOR.

Le localizzazioni sono implementate in un file formats.py all'interno di ogni directory di lingua.

Nei template singoli valori possono essere localizzati o non localizzati usando i filtri localize o unlocalize:

{% load l10n %}

{{ value|localize }}

{{ value|unlocalize }}

Esercizi

Leggi la documentazione ufficiale sulla internazionalizzazione.

Leggi la documentazione su come settare il linguaggio preferito dagli utenti.

Consulta la documentazione sulle traduzioni lazy.

Consulta la documentazione dei comandi makemessages e compilemessages.

Leggi la documentazione ufficiale sulla localizzazione.

Un Corso Django