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
5.1.1. La configuración: config/settings.py
- 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
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:
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:
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
- 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.
- 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
- 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]).
- 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).
- 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.
- 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”:


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


El cambio de idioma, visto con [curl]. La opción [-H] proporciona el encabezado [Referer] que enviaría el navegador:
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í:
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]):
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.