Skip to content

5. Internacionalización

Una aplicación internacionalizada muestra sus textos en el idioma del usuario. El caso de estudio está en francés y en inglés. El principio es simple: las plantillas contienen textos marcados como “por traducir”, y un diccionario para cada idioma asocia cada texto con su traducción. El idioma seleccionado se almacena en una cookie.

[Django] utiliza [gettext] para ello, el sistema de traducción del proyecto GNU, que [Python] también reconoce (el módulo [gettext] de la biblioteca estándar) y que se encuentra en muchos programas de código abierto. Con [gettext], la clave de un texto es el propio texto, escrito en el idioma original: una plantilla escrita en [{% translate "Home" %}], y el diccionario francés asocia “Home” con “Accueil”. Una página sigue siendo legible y funcional incluso sin diccionario: el texto se muestra en el idioma original. Esto difiere de las versiones de [Symfony], [Laravel], [Flask], [Spring MVC], [ASP.NET Core MVC] y [NestJS] del caso de estudio, que utilizaban claves abstractas ([MENU.HOME]). Los diccionarios son archivos de texto en el formato [.po] (Portable Object), que las herramientas pueden extraer del código y que el software de traducción puede editar; [Django] lee su versión compilada, los archivos [.mo] (Machine Object). [gettext] también puede poner un texto en plural según las reglas de cada idioma. [Django] está traducido de esta misma manera: gracias a sus diccionarios puede mostrar sus mensajes de error en francés (desde el ejemplo 08 han estado en inglés, el idioma predeterminado). El formato de las fechas y los importes sigue siendo el del ejemplo 16.

5.1. Ejemplo 22: una aplicación bilingüe

22-i18n/
├── config/
│   ├── settings.py
│   ├── urls.py
│   └── ...
├── locale/
│   └── fr/
│       └── LC_MESSAGES/
│           ├── django.mo
│           └── django.po
├── pages/
│   ├── templatetags/
│   │   ├── __init__.py
│   │   └── formats.py
│   ├── __init__.py
│   ├── viewmodels.py
│   └── views.py
├── static/
│   └── ...
├── templates/
│   ├── fragments/
│   │   └── navbar.html
│   ├── pages/
│   │   ├── home.html
│   │   └── products.html
│   └── layout.html
└── manage.py

5.1.1. La configuración: config/settings.py

# config/settings.py: la configuración del ejemplo 22

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent
DEBUG = True
SECRET_KEY = "django-insecure-e%uqntr!nz5i2w(d^_-cwr6w=w^2z^mx6vpvpgsg91qvp)bnzl"
ALLOWED_HOSTS = []
TIME_ZONE = "Europe/Paris"
ROOT_URLCONF = "config.urls"
WSGI_APPLICATION = "config.wsgi.application"

# el idioma predeterminado y los idiomas que maneja la aplicación
LANGUAGE_CODE = "en"
LANGUAGES = [
    ("fr", "Français"),
    ("en", "English"),
]
# las carpetas de los DICCIONARIOS de la aplicación (archivos .po, compilados en .mo)
LOCALE_PATHS = [BASE_DIR / "locale"]
# la cookie que recuerda el idioma elegido (también es el nombre predeterminado)
LANGUAGE_COOKIE_NAME = "django_language"

INSTALLED_APPS = [
    "django.contrib.staticfiles",
    "pages",
]

MIDDLEWARE = [
    # LocaleMiddleware: el idioma de cada solicitud, leído de la cookie de idioma,
    # en su defecto del encabezado Accept-Language del navegador, y en su defecto de LANGUAGE_CODE
    "django.middleware.locale.LocaleMiddleware",
]

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.request",
                # la variable LANGUAGE_CODE: el idioma de la solicitud
                "django.template.context_processors.i18n",
            ],
        },
    },
]

STATIC_URL = "static/"
STATICFILES_DIRS = [
    BASE_DIR / "static",
    BASE_DIR.parent / "common" / "static",
]
  • Línea 14: el idioma predeterminado de la aplicación, que se utiliza para las solicitudes que no especifican un idioma (ejemplo 08). Es también el idioma de los textos de las plantillas; por lo tanto, el inglés no requiere un diccionario;
  • Líneas 15–18: los idiomas admitidos por la aplicación;
  • Línea 20: [LOCALE_PATHS], las carpetas donde [Django] busca los diccionarios de la aplicación, además de las carpetas [locale] de cada aplicación (incluidas las de [Django] mismo). Cada diccionario se almacena en una carpeta [<language>/LC_MESSAGES], con el nombre [django.po] (y [django.mo]): esta es la organización que exige [gettext];
  • línea 22: el nombre de la cookie que almacena el idioma seleccionado. [django_language] es el valor predeterminado; lo incluimos aquí para que sea visible;
  • líneas 29–33: el middleware [LocaleMiddleware] de [Django] reemplaza a nuestro middleware [SetLanguage] del ejemplo 16. Para cada solicitud, selecciona el idioma entre los especificados en la configuración [LANGUAGES]: el idioma indicado en la cookie de idioma, si existe; si no, el idioma preferido del navegador, según el encabezado [Accept-Language] (ejemplo 12); si no, [LANGUAGE_CODE]. Lo activa ([translation.activate], ejemplo 16) y lo almacena en [request.LANGUAGE_CODE]. Por último, agrega a la respuesta el encabezado [Content-Language] (el idioma de la página), junto con el encabezado [Vary: Accept-Language], que advierte a las cachés que la respuesta depende de este encabezado;
  • línea 43: el procesador de contexto [i18n] agrega a las plantillas las variables [LANGUAGE_CODE] (el idioma de la solicitud), [LANGUAGES] y [LANGUAGE_BIDI] (verdadera para un idioma que se escribe de derecha a izquierda).

5.1.2. El diccionario: locale/fr/LC_MESSAGES/django.po

# locale/fr/LC_MESSAGES/django.po: el diccionario francés del ejemplo 22.
# msgid: el texto original, tal como está escrito en las plantillas (en inglés);
# msgstr: su traducción. Este archivo se compila en django.mo (el archivo que
# Django lee) con el comando: python manage.py compilemessages
msgid ""
msgstr ""
"Language: fr\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n > 1);\n"

#: templates/fragments/navbar.html:6
msgid "Home"
msgstr "Accueil"

#: templates/fragments/navbar.html:7
msgid "Products"
msgstr "Produits"

#: templates/pages/home.html:4 templates/pages/home.html:7
msgid "Welcome"
msgstr "Bienvenue"

#: templates/pages/home.html:9
#, python-format
msgid "Hello %(name)s!"
msgstr "Bonjour %(name)s !"

#: templates/pages/home.html:11
#, python-format
msgid "Today is %(date)s."
msgstr "Nous sommes le %(date)s."

#: templates/pages/products.html:4 templates/pages/products.html:7
msgid "Our products"
msgstr "Nos produits"

#: templates/pages/products.html:9
msgid "Product"
msgstr "Produit"

#: templates/pages/products.html:9
msgid "Price"
msgstr "Prix"

#: templates/pages/products.html:21
#, python-format
msgid "%(n)s product in the catalogue."
msgid_plural "%(n)s products in the catalogue."
msgstr[0] "%(n)s produit au catalogue."
msgstr[1] "%(n)s produits au catalogue."

Un archivo [.po] es una secuencia de entradas, separadas por líneas en blanco:

  • líneas 1–4: un comentario;
  • líneas 5–11: la entrada de encabezado: una cadena vacía ([msgid ""]), cuya “traducción” ([msgstr]) contiene la información del diccionario: el idioma, el juego de caracteres y la regla de plurales del idioma ([Plural-Forms]: en francés, dos formas, la segunda para todo número mayor que 1);
  • líneas 13–15: una entrada estándar: [msgid] es el texto fuente, tal como está escrito en la plantilla; [msgstr] es su traducción. La línea [#:] indica dónde se encontró el texto (una plantilla y una línea): es un comentario para el traductor;
  • líneas 25–28: un texto que contiene una variable. En el diccionario, una variable se escribe [%(name)s] (la sintaxis de las cadenas de formato de [Python], ejemplo 10); la línea [#, python-format] lo señala a las herramientas. La traducción puede reubicar la variable o cambiar la puntuación que la rodea (en francés, el signo de exclamación va precedido de un espacio);
  • líneas 47–52: una forma plural: [msgid] es la forma singular, [msgid_plural] es la forma plural, y cada forma de la traducción está numerada ([msgstr[0]], [msgstr[1]]), en el orden especificado por la regla [Plural-Forms]. En francés, 0 y 1 son singular, mientras que en inglés 0 es plural (“0 products”): [gettext] lo sabe gracias a esta regla. Es una mejora respecto del “product(s)” utilizado en las versiones anteriores del caso de estudio.

Este archivo no se escribe a mano. El comando:

python manage.py makemessages -l fr

examina las plantillas del proyecto y el código [Python], extrae todos los textos marcados “por traducir” y crea o actualiza el archivo [locale/fr/LC_MESSAGES/django.po]: los textos nuevos se agregan con una traducción vacía y las traducciones existentes se conservan. Solo queda escribir las traducciones, ya sea en un editor de texto o en un software especializado ([Poedit], por ejemplo). El comando:

python manage.py compilemessages

compila luego cada archivo [.po] en un archivo [.mo], un archivo binario de lectura rápida, que es el que utiliza [Django]. Es necesario reiniciar el servidor después de una compilación: los diccionarios se cargan una sola vez. Estos dos comandos utilizan los programas de [gettext] ([xgettext], [msgfmt]...), que deben estar instalados (para [Linux], el paquete [gettext]; para [Windows], por ejemplo, los binarios distribuidos en el sitio mlocati.github.io). Como el archivo [django.mo] se incluye con el ejemplo, no es necesario instalar estos paquetes para ejecutarlo.

5.1.3. Selección del idioma: rutas y vistas

# config/urls.py: la tabla de enrutamiento principal

from django.urls import path, re_path

from pages import views

urlpatterns = [
    path("", views.home, name="home"),
    path("products", views.products, name="products"),
    # re_path: una ruta descrita por una expresión regular; un idioma distinto
    # de fr o en no coincide con la ruta (404)
    re_path(r"^language/(?P<code>fr|en)$", views.change_language, name="language"),
]
  • Línea 12: [re_path] describe una ruta mediante una expresión regular, en lugar de la sintaxis de [path] (ejemplo 02). [^] y [$] marcan el inicio y el fin de la ruta; [(?P<code>fr|en)] es un grupo con nombre: el texto que reconoce, [fr] o [en] (la barra vertical significa “o”), se pasa a la vista en el parámetro [code]. Otro idioma no coincide con ninguna ruta: [/language/de] devuelve un error 404.
# pages/views.py: las vistas no saben nada del idioma: proporcionan
# los datos, las plantillas los traducen y les dan formato

from datetime import date

from django.conf import settings
from django.shortcuts import redirect, render
from django.utils.http import url_has_allowed_host_and_scheme
from django.views.decorators.http import require_GET

from .viewmodels import Product


@require_GET
def home(request):
    return render(request, "pages/home.html", {"name": "Marie", "today": date(2026, 9, 23)})


@require_GET
def products(request):
    return render(request, "pages/products.html", {"products": [
        Product("Keyboard", 2500),
        Product("Mouse", 1250),
        Product("Screen", 114900),
    ]})


# GET /language/fr: recuerda la elección en la cookie de idioma y luego vuelve a la
# página anterior
@require_GET
def change_language(request, code):
    response = redirect(origin_page(request))
    # la cookie: un año de vida, ilegible para el JavaScript de la página (httponly),
    # nunca enviada con una solicitud POST proveniente de otro sitio (samesite Lax)
    response.set_cookie(settings.LANGUAGE_COOKIE_NAME, code, max_age=365 * 24 * 3600,
                        httponly=True, samesite="Lax")
    return response


# la página de la que venimos (encabezado Referer), si pertenece a ESTE sitio: redirigir
# a cualquier dirección proveniente de la solicitud permitiría enviar
# al usuario a otro sitio (vulnerabilidad de "open redirect")
def origin_page(request):
    referer = request.headers.get("Referer", "")
    # url_has_allowed_host_and_scheme: verdadero para una dirección relativa, o una dirección
    # absoluta cuyo host es el de la solicitud
    if url_has_allowed_host_and_scheme(referer, allowed_hosts={request.get_host()}):
        return referer
    return "/"
  • Líneas 14–25: las vistas de inicio y de productos no conocen el idioma; proporcionan datos sin procesar (un nombre, una fecha, importes en centavos). La traducción y el formato están a cargo de las plantillas. La clase [Product] tiene un nombre y un precio en centavos; la biblioteca [formats] es la del ejemplo 16: su filtro [long_date] escribe una fecha en el formato “completo” del idioma activo (“Wednesday, September 23, 2026”, “mercredi 23 septembre 2026”), y su filtro [money] muestra un importe;
  • líneas 30–37: la vista de cambio de idioma responde redirigiendo al usuario a la página de la que venía; el usuario regresa a su página original en el nuevo idioma;
  • líneas 35–36: la respuesta incluye una cookie, que el navegador reenviará con cada solicitud. [set_cookie] recibe su nombre, su valor y sus opciones: [max_age], su duración en segundos (un año); [httponly=True] la hace invisible para el [JavaScript] de la página; [samesite="Lax"] impide que el navegador la envíe con una solicitud POST originada en otro sitio. Se agrega a la respuesta como un encabezado [Set-Cookie];
  • líneas 43–49: la página original se indica mediante el encabezado [Referer] de la solicitud (la grafía incorrecta, con una sola [r], es la del estándar HTTP), que el navegador rellena con la URL de la página que contenía el enlace. Pero este encabezado proviene del cliente, que puede poner en él cualquier cosa. Redirigir a ciegas a esta dirección convertiría nuestra aplicación en una redirección abierta: un enlace malicioso con el nombre de nuestro dominio podría enviar al usuario a un sitio malicioso. La función [url_has_allowed_host_and_scheme] de [Django] ([django.utils.http]) verifica si una dirección es relativa o si apunta a una de las máquinas permitidas (en este caso, la de la solicitud: [request.get_host()]); de lo contrario, se redirige al usuario a la página de inicio.

[Django] también proporciona una vista lista para usar para cambiar el idioma, [django.views.i18n.set_language], que realiza la misma tarea mediante un formulario (POST); escribimos la nuestra para demostrarlo y para permitir el cambio de idioma con un simple enlace.

5.1.4. Traducción en las plantillas

<!doctype html>
{% load static %}
{# LANGUAGE_CODE: el idioma de la solicitud, "fr" o "en" #}
<html lang="{{ LANGUAGE_CODE }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {# el título: el bloque [title] de la página, ya traducido #}
  <title>{% block title %}{% endblock %}</title>
  <link rel="stylesheet" href="{% static 'bootstrap/css/bootstrap.min.css' %}">
  <link rel="stylesheet" href="{% static 'css/styles.css' %}">
</head>
<body>
  <div class="container py-3">
    {% include "fragments/navbar.html" %}
    <main>
      {% block content %}{% endblock %}
    </main>
  </div>
</body>
</html>
  • línea 4: el atributo [lang] de la página indica su idioma a los navegadores, los motores de búsqueda y los lectores de pantalla; [LANGUAGE_CODE] es el idioma de la solicitud, proporcionado por el procesador de contexto [i18n];
  • Línea 9: el título de la página lo proporciona la propia página, ya traducido (bloque [title]).
{# i18n: la biblioteca de las etiquetas de traducción #}
{% load i18n %}
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <div class="navbar-nav me-auto">
    {# translate: la traducción de un texto, en el idioma de la solicitud #}
    <a class="nav-link" href="{% url 'home' %}">{% translate "Home" %}</a>
    <a class="nav-link" href="{% url 'products' %}">{% translate "Products" %}</a>
  </div>
  {# get_available_languages: los idiomas de la configuración LANGUAGES, pares (código, nombre) #}
  {% get_available_languages as languages %}
  <div class="btn-group btn-group-sm">
    {% for code, name in languages %}
      {# el idioma actual aparece resaltado #}
      <a class="btn {% if code == LANGUAGE_CODE %}btn-primary{% else %}btn-outline-primary{% endif %}"
         href="{% url 'language' code %}" title="{{ name }}">{{ code|upper }}</a>
    {% endfor %}
  </div>
</nav>
  • línea 2: las etiquetas de traducción están en la biblioteca [i18n], que cada plantilla debe cargar (ejemplo 16);
  • líneas 6–7: la etiqueta [{% translate %}] devuelve la traducción de un texto al idioma de la solicitud (o el texto mismo, si no tiene traducción);
  • líneas 10–17: la etiqueta [{% get_available_languages %}] almacena en una variable los idiomas de la configuración [LANGUAGES], pares de (código, nombre), que el bucle recorre a continuación ([for code, name in languages]). Un botón por idioma, que enlaza con la vista [/language/<code>]. El idioma actual aparece resaltado ([btn-primary], botón sólido).
{% extends "layout.html" %}
{% load i18n formats %}

{% block title %}{% translate "Welcome" %}{% endblock %}

{% block content %}
  <h1>{% translate "Welcome" %}</h1>
  {# blocktranslate: un texto que contiene variables {{ name }} #}
  <p>{% blocktranslate %}Hello {{ name }}!{% endblocktranslate %}</p>
  {# with: la fecha, formateada primero (filtro long_date, ver ejemplo 16), luego insertada en el texto #}
  <p>{% blocktranslate with date=today|long_date %}Today is {{ date }}.{% endblocktranslate %}</p>
{% endblock %}
  • línea 4: el bloque [title], traducido, para la plantilla padre;
  • línea 9: la etiqueta [{% blocktranslate %}] traduce textos que contienen variables: [{{ name }}] se convierte en [%(name)s] en el diccionario. Aquí solo se permiten variables simples (sin filtros ni puntos);
  • línea 11: por lo tanto, una variable calculada solo puede incluirse en el texto mediante [with]: la fecha, formateada en el idioma de la solicitud por el filtro [long_date], se almacena en la variable [date] dentro del texto.
{% extends "layout.html" %}
{% load i18n formats %}

{% block title %}{% translate "Our products" %}{% endblock %}

{% block content %}
  <h1>{% translate "Our products" %}</h1>
  <table class="table table-sm w-auto">
    <thead><tr><th>{% translate "Product" %}</th><th class="text-end">{% translate "Price" %}</th></tr></thead>
    <tbody>
      {% for product in products %}
        <tr>
          <td>{{ product.name }}</td>
          {# el filtro money del ejemplo 16: el formato depende del idioma #}
          <td class="text-end">{{ product.price_cents|money }}</td>
        </tr>
      {% endfor %}
    </tbody>
  </table>
  {# el plural: count elige la forma según el número n; plural separa las formas #}
  <p>{% blocktranslate count n=products|length %}{{ n }} product in the catalogue.{% plural %}{{ n }} products in the catalogue.{% endblocktranslate %}</p>
{% endblock %}
  • línea 15: el filtro [money], cuyo resultado depende del idioma;
  • línea 21: el plural. [count n=products|length] devuelve el número que determina la forma ([length], ejemplo 14); la etiqueta [{% plural %}] separa la forma singular de la forma plural, escritas en el idioma fuente. Los nombres de los productos, en cambio, no se traducen: son datos que, en una aplicación real, provendrían de una base de datos.

Fuera de las plantillas, la traducción está a cargo de las funciones del módulo [django.utils.translation]: [gettext("Home")] (a menudo importada con el nombre corto [_]: [_("Home")]), [ngettext] para el plural y [gettext_lazy], una traducción “diferida” que se realiza solo cuando se utiliza el texto: es la que debe usarse para los textos definidos al cargar un módulo (la etiqueta de un campo de formulario, por ejemplo), cuando el idioma de la solicitud aún no se conoce. El caso de estudio la utiliza.

5.1.5. Ejecución

La página de inicio, en inglés (el idioma predeterminado) y luego en francés tras hacer clic en el botón “FR”:

Image

Image

La página de productos, en ambos idiomas. Los importes siguen las convenciones de cada idioma:

Image

Image

El cambio de idioma, visto con [curl]. La opción [-H] proporciona el encabezado [Referer] que enviaría el navegador:

curl -i -H "Referer: http://localhost:8000/products" http://localhost:8000/language/fr
1
2
3
4
5
6
HTTP/1.1 302 Found
Content-Type: text/html; charset=utf-8
Location: http://localhost:8000/products
Vary: Accept-Language
Content-Language: en
Set-Cookie: django_language=fr; expires=Mon, 27 Sep 2027 17:37:43 GMT; HttpOnly; Max-Age=31536000; Path=/; SameSite=Lax

La redirección lleva de vuelta a la página original y la cookie se establece con una duración de un año. La respuesta en sí sigue estando en inglés ([Content-Language: en]): el idioma solo se seleccionó cuando llegó la solicitud, antes de que existiera la cookie. Un [Referer] que apunta a otro sitio no permite ser redirigido allí:

curl -i -H "Referer: https://pirate.example/trap" http://localhost:8000/language/fr
1
2
3
4
HTTP/1.1 302 Found
Content-Type: text/html; charset=utf-8
Location: /
...

El usuario regresa a la página de inicio y permanece en nuestro sitio. Por último, la página de inicio, solicitada con la cookie [django_language=fr] (opción [-b] de [curl]):

curl -b "django_language=fr" http://localhost:8000/
<!doctype html>
<html lang="fr">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Bienvenue</title>
...
    <a class="nav-link" href="/">Accueil</a>
    <a class="nav-link" href="/products">Produits</a>
...
  <h1>Bienvenue</h1>
  <p>Bonjour Marie !</p>
  <p>Nous sommes le mercredi 23 septembre 2026.</p>
...

La cookie no está firmada: se transmite en texto plano y el usuario puede modificarla. Esto no es un problema: no contiene información confidencial y [LocaleMiddleware] solo acepta los idiomas especificados en la configuración [LANGUAGES]. El siguiente ejemplo ilustra el nivel de confianza que se puede depositar en una cookie. Sin una cookie, [LocaleMiddleware] lee el encabezado [Accept-Language] del navegador: [curl -H "Accept-Language: fr-FR,fr;q=0.9" http://localhost:8000/] muestra la página en francés. Los dos mecanismos se combinan así de manera natural: el idioma del navegador en la primera visita, seguido del idioma elegido por el usuario. Un tercer enfoque, frecuente, coloca el idioma en la URL ([/fr/products]): la función [i18n_patterns] de [Django] antepone entonces el idioma a las rutas, y [LocaleMiddleware] lo lee de la ruta. Este caso de estudio se centra en la cookie.