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 vistas ya no contienen texto, sino claves ([MENU.HOME]), y un diccionario por cada idioma asocia un texto a cada clave. El idioma seleccionado se almacena en una cookie.

El ecosistema de [Flask] ofrece una extensión para este fin, [Flask-Babel], que se apoya en el sistema de traducción estándar [gettext]: los textos se extraen del código con una herramienta, se traducen en archivos [.po] y luego se compilan en archivos [.mo]. Es un sistema potente, pero requiere herramientas específicas y un paso de compilación. En su lugar, escribiremos una pequeña clase que lee diccionarios JSON: son los mismos archivos que los de las versiones [ASP.NET Core MVC], [NestJS], y [Spring MVC] del caso de estudio, y su formato puede leerse y escribirse sin herramientas especiales. La biblioteca [Babel], en cambio, se sigue usando para formatear fechas e importes (ejemplo 16).

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

22-i18n/
├── app.py
├── controllers/
│   ├── language.py
│   └── pages.py
├── i18n/
│   ├── en.json
│   └── fr.json
├── static/css/
│   └── styles.css
├── templates/
│   ├── fragments/
│   │   └── navbar.html
│   ├── layout.html
│   └── pages/
│       ├── home.html
│       └── products.html
└── translation/
    ├── formats.py
    └── translator.py

5.1.1. Diccionarios

El archivo [i18n/fr.json]:

{
  "MENU": {
    "HOME": "Accueil",
    "PRODUCTS": "Produits"
  },
  "HOME": {
    "TITLE": "Bienvenue",
    "HELLO": "Bonjour {name} !",
    "DATE": "Nous sommes le {date}."
  },
  "PRODUCTS": {
    "TITLE": "Nos produits",
    "NAME": "Produit",
    "PRICE": "Prix",
    "COUNT": "{n} produit(s) au catalogue."
  }
}

Las claves se agrupan por tema dentro de objetos JSON anidados: el texto de menú “Home” tiene la clave completa [MENU.HOME]. Una cadena de texto puede contener marcadores de posición, escritos como [{name}], que se reemplazan durante la traducción. El archivo [i18n/en.json] tiene exactamente las mismas claves:

{
  "MENU": {
    "HOME": "Home",
    "PRODUCTS": "Products"
  },
  "HOME": {
    "TITLE": "Welcome",
    "HELLO": "Hello {name}!",
    "DATE": "Today is {date}."
  },
  "PRODUCTS": {
    "TITLE": "Our products",
    "NAME": "Product",
    "PRICE": "Price",
    "COUNT": "{n} product(s) in the catalogue."
  }
}

5.1.2. El servicio de traducción: translation/translator.py

# translation/translator.py: el servicio de traducción
import json
import re
from pathlib import Path

from flask import g


class Translator:

    LANGUAGES = ("fr", "en")
    DEFAULT_LANGUAGE = "en"

    # {name}: un parámetro en un texto
    PARAMETER = re.compile(r"\{(\w+)\}")

    def __init__(self, folder: Path):
        # idioma -> (clave completa "HOME.HELLO" -> texto)
        self._dictionaries: dict[str, dict[str, str]] = {}
        for language in self.LANGUAGES:
            with open(folder / f"{language}.json", encoding="utf-8") as file:
                self._dictionaries[language] = self._flatten(json.load(file))

    # el idioma admitido que corresponde a [code]: "fr" -> "fr"; "de" o None -> "en"
    @classmethod
    def language(cls, code: str | None) -> str:
        return code if code in cls.LANGUAGES else cls.DEFAULT_LANGUAGE

    # translate("HOME.HELLO", name="Marie") -> "Hello Marie!", en el
    # idioma de la solicitud actual (g.language, vea app.py)
    def translate(self, key: str, **parameters) -> str:
        # una clave ausente muestra la clave misma: un descuido se ve en pantalla
        text = self._dictionaries[g.language].get(key, key)
        # cada {name} se reemplaza por el valor del parámetro del mismo nombre
        return self.PARAMETER.sub(
            lambda m: str(parameters.get(m.group(1), m.group(0))), text)

    # { "MENU": { "HOME": "Home" } } -> { "MENU.HOME": "Home" }
    @classmethod
    def _flatten(cls, node: dict, prefix: str = "") -> dict[str, str]:
        result = {}
        for key, value in node.items():
            full_key = f"{prefix}.{key}" if prefix else key
            if isinstance(value, dict):
                result.update(cls._flatten(value, full_key))
            else:
                result[full_key] = value
        return result
  • líneas 11–12: los idiomas admitidos y el idioma predeterminado, atributos de clase compartidos por todos los objetos de la clase y accesibles sin un objeto ([Translator.LANGUAGES]);
  • línea 15: la expresión regular de un parámetro: una llave de apertura ([\{], precedida de una [\] porque la llave tiene un significado específico en las expresiones regulares), uno o más caracteres de palabra ([\w+]) y una llave de cierre. Los paréntesis capturan el nombre del parámetro. [re.compile] analiza la expresión una sola vez y para siempre;
  • líneas 17–22: el constructor lee los diccionarios una sola vez, cuando se crea el servicio. [json.load] convierte el contenido de un archivo JSON en objetos [Python] (diccionarios anidados). [with open(...) as file] abre el archivo y garantiza que se cierre al final del bloque; [encoding="utf-8"] es esencial, porque la codificación predeterminada depende del sistema (en [Windows], no siempre es [UTF-8]);
  • líneas 25–27: un método de clase (decorador [@classmethod]) recibe la clase ([cls]) en lugar de un objeto; se llama sobre la clase: [Translator.language("en")]. Devuelve el idioma admitido que corresponde a un código, o el idioma predeterminado si el código es desconocido o falta;
  • líneas 31–36: la traducción de una clave, en el idioma de la solicitud actual, leído de [g.language] (véase el ejemplo 16). Una clave ausente del diccionario se muestra tal cual: una omisión es visible de inmediato en pantalla. Los parámetros se reciben como parámetros con nombre ([**parameters]); el método de expresión regular [sub] reemplaza cada parámetro encontrado en el texto por el resultado de una función (en este caso, una función anónima ([lambda m: ...]) que recibe la coincidencia encontrada ([m]): [m.group(1)] es el nombre capturado, [m.group(0)] es el texto completo [{name}], que se conserva si no se proporcionó el parámetro;
  • líneas 40–48: los objetos JSON anidados se “aplanan” en un único diccionario cuyas claves son las claves completas: [{"MENU": {"HOME": "Home"}}] pasa a ser [{"MENU.HOME": "Home"}]. El método es recursivo: se llama a sí mismo para cada objeto anidado, usando la clave actual como prefijo.

5.1.3. Formato según el idioma de la solicitud: translation/formats.py

# translation/formats.py: fechas y montos, con el formato del idioma de la solicitud (vea el ejemplo 16)
from datetime import date
from decimal import Decimal

from babel.dates import format_date
from babel.numbers import format_currency
from flask import g


# una fecha en palabras completas
def long_date(day: date) -> str:
    return format_date(day, format="full", locale=g.language)


# un monto en euros
def money(amount: Decimal) -> str:
    return format_currency(amount, "EUR", locale=g.language)

Los filtros del ejemplo 16, que esta vez usan [g.language]. [Babel] acepta un idioma solo ([fr], [en]) o un idioma y un país ([fr_FR]); para [en], aplica las convenciones de Estados Unidos.

5.1.4. Configuración: app.py

# app.py: la aplicación del ejemplo 22
from pathlib import Path

from flask import Blueprint, Flask, g, request

from controllers.language import LANGUAGE_COOKIE, language
from controllers.pages import pages
from translation import formats
from translation.translator import Translator

# Bootstrap, compartido por los ejemplos (vea el ejemplo 15)
BOOTSTRAP = Path(__file__).resolve().parent.parent / "common" / "bootstrap"


def create_app():
    app = Flask(__name__)
    app.jinja_env.trim_blocks = True
    app.jinja_env.lstrip_blocks = True
    # el servicio de traducción: los diccionarios, leídos UNA SOLA VEZ, al iniciar
    translator = Translator(Path(app.root_path) / "i18n")
    app.extensions["translator"] = translator
    app.register_blueprint(Blueprint("bootstrap", __name__, static_folder=BOOTSTRAP,
                                     static_url_path="/bootstrap"))
    app.register_blueprint(language)
    app.register_blueprint(pages)

    # el idioma de cada solicitud: el de la cookie [language], inglés en caso contrario
    @app.before_request
    def set_language():
        g.language = Translator.language(request.cookies.get(LANGUAGE_COOKIE))

    # en las vistas: {{ t('KEY') }}, {{ day | long_date }}, {{ price | money }}
    app.add_template_global(translator.translate, "t")
    app.add_template_filter(formats.long_date)
    app.add_template_filter(formats.money)
    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • líneas 20–21: el servicio, creado una sola vez al iniciar. [app.root_path] es la carpeta de la aplicación (la de [app.py]);
  • líneas 28–30: antes de cada acción, el idioma de la solicitud se establece con el de la cookie [language] si existe y es admitido; de lo contrario, se usa inglés por defecto. [request.cookies] es el diccionario de cookies enviadas por el navegador;
  • línea 33: el método [translate] del servicio se pone a disposición de las vistas como función global con un nombre corto, [t] (el segundo parámetro de [add_template_global]). Un método de objeto se usa como una función: [translator.translate] es un método asociado al objeto [translator].

5.1.5. Selección del idioma: controllers/language.py

# controllers/language.py: la elección del idioma
from urllib.parse import urlsplit

from flask import Blueprint, abort, redirect, request

from translation.translator import Translator

language = Blueprint("language", __name__)

LANGUAGE_COOKIE = "language"


# GET /language/fr: guarda la elección en una cookie y luego regresa a la página anterior
@language.get("/language/<code>")
def change(code):
    if code not in Translator.LANGUAGES:
        abort(404)
    response = redirect(origin_page())
    # 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)
    response.set_cookie(LANGUAGE_COOKIE, code, max_age=365 * 24 * 3600, httponly=True,
                        samesite="Lax")
    return response


# la página de la que venimos (encabezado Referer), de la cual conservamos solo la ruta:
# redirigir a una dirección completa proveniente de la solicitud permitiría
# enviar al usuario a otro sitio (falla de "open redirect")
def origin_page() -> str:
    url = urlsplit(request.headers.get("Referer", ""))
    path = url.path
    # "//site.com/..." sería interpretado por el navegador como una dirección
    # de OTRO sitio: también se rechaza
    if not path.startswith("/") or path.startswith("//"):
        return "/"
    return f"{path}?{url.query}" if url.query else path
  • línea 16: un código de idioma desconocido: 404;
  • línea 18: la acción responde con una redirección a la página de la que venía el usuario: este vuelve a esa página, en el nuevo idioma;
  • líneas 21–22: la respuesta incluye una cookie, que el navegador reenviará con cada solicitud. [max_age] es 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. A diferencia de la cookie de sesión (ejemplo 20), esta cookie no está firmada: no es un problema que el usuario la modifique, ya que el servidor solo acepta los idiomas admitidos;
  • líneas 29–36: la página de origen se indica en el encabezado [Referer] de la solicitud (la grafía incorrecta, con una sola [r], es la que se usa en el estándar HTTP), que el navegador completa con la URL de la página que contenía el enlace. Pero este encabezado proviene del cliente, que puede poner en él lo que quiera. Redirigir ciegamente a esa dirección convertiría nuestra aplicación en una *redirección abierta* (open redirect): un enlace malicioso con nuestro nombre de dominio podría enviar al usuario a un sitio malicioso. Por eso conservamos solo la ruta y los parámetros de la URL ([urlsplit] la descompone en sus componentes) y rechazamos toda ruta que comience con [//], que el navegador interpretaría como la dirección de otro sitio.

5.1.6. Acciones: controllers/pages.py

# controllers/pages.py: las acciones no saben nada del idioma:
# proporcionan datos, las vistas los traducen y los formatean
from dataclasses import dataclass
from datetime import date
from decimal import Decimal

from flask import Blueprint, render_template

pages = Blueprint("pages", __name__)


@dataclass
class Product:
    name: str
    price: Decimal


@pages.get("/")
def home():
    return render_template("pages/home.html", name="Marie", today=date(2026, 9, 23))


@pages.get("/products")
def products():
    return render_template("pages/products.html", products=[
        Product("Keyboard", Decimal("25")),
        Product("Mouse", Decimal("12.5")),
        Product("Screen", Decimal("1149")),
    ])

Las acciones son independientes del idioma: proporcionan datos sin procesar (un nombre, una fecha, importes). La traducción y el formato corresponden a las vistas.

5.1.7. Traducir en las vistas

<!doctype html>
{# g.language: el idioma de la solicitud, "fr" o "en" #}
<html lang="{{ g.language }}">
<head>
  <meta charset="utf-8">
  {# el título es una CLAVE, proporcionada por la página (variable title_key), traducida por el layout #}
  <title>{{ t(title_key) }}</title>
  <link rel="stylesheet" href="{{ url_for('bootstrap.static', filename='css/bootstrap.min.css') }}">
  <link rel="stylesheet" href="{{ url_for('static', filename='css/styles.css') }}">
</head>
<body>
  <div class="container py-3">
    {% include "fragments/navbar.html" %}
    <main>
      {% block content %}{% endblock %}
    </main>
  </div>
</body>
</html>
  • línea 3: el atributo [lang] de la página indica su idioma a los navegadores, los motores de búsqueda y los lectores de pantalla;
  • línea 7: el título de la página es distinto en cada página, pero lo traduce la plantilla. Cada página proporciona la clave de su título en una variable, [title_key].
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <div class="navbar-nav me-auto">
    {# t('KEY'): la traducción de una clave, en el idioma de la solicitud #}
    <a class="nav-link" href="/">{{ t("MENU.HOME") }}</a>
    <a class="nav-link" href="/products">{{ t("MENU.PRODUCTS") }}</a>
  </div>
  {# el idioma actual aparece resaltado #}
  <div class="btn-group btn-group-sm">
    {% for code in ["fr", "en"] %}
    <a class="btn {{ 'btn-primary' if g.language == code else 'btn-outline-primary' }}"
       href="/language/{{ code }}">{{ code | upper }}</a>
    {% endfor %}
  </div>
</nav>
  • líneas 4–5: los textos del menú, traducidos;
  • líneas 9–12: un botón por idioma, que lleva a la acción [/language/<code>]. El idioma actual aparece resaltado ([btn-primary], botón relleno).
{% extends "layout.html" %}
{# una variable definida FUERA de los bloques es visible para el layout #}
{% set title_key = "HOME.TITLE" %}

{% block content %}
  <h1>{{ t("HOME.TITLE") }}</h1>
  {# un parámetro: un parámetro con nombre de la función t #}
  <p>{{ t("HOME.HELLO", name=name) }}</p>
  {# la fecha, formateada primero y luego pasada como parámetro [date] #}
  <p>{{ t("HOME.DATE", date=today | long_date) }}</p>
{% endblock %}
  • línea 3: una variable definida fuera de los bloques de una página que extiende una plantilla es visible para la plantilla: así es como la página le pasa su clave de título. (En cambio, una variable definida dentro de un bloque seguiría siendo local a ese bloque.);
  • línea 8: un parámetro de texto es un parámetro con nombre de la función [t];
  • línea 10: la fecha, formateada en el idioma de la solicitud y luego pasada como parámetro.
{% extends "layout.html" %}
{% set title_key = "PRODUCTS.TITLE" %}

{% block content %}
  <h1>{{ t("PRODUCTS.TITLE") }}</h1>
  <table class="table table-sm w-auto">
    <thead><tr><th>{{ t("PRODUCTS.NAME") }}</th><th class="text-end">{{ t("PRODUCTS.PRICE") }}</th></tr></thead>
    <tbody>
      {% for product in products %}
      <tr>
        <td>{{ product.name }}</td>
        <td class="text-end">{{ product.price | money }}</td>
      </tr>
      {% endfor %}
    </tbody>
  </table>
  <p>{{ t("PRODUCTS.COUNT", n=products | length) }}</p>
{% endblock %}
  • línea 17: un parámetro calculado. En cambio, los nombres de los productos no se traducen: son datos que, en una aplicación real, provendrían de una base de datos.

5.1.8. Ejecución

La página de inicio, en inglés (el idioma predeterminado), y luego en francés después de 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:5000/products" http://localhost:5000/language/en
1
2
3
4
5
6
HTTP/1.1 302 FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 205
Location: /products
Set-Cookie: language=en; Expires=Sun, 26 Sep 2027 13:37:04 GMT; Max-Age=31536000; HttpOnly; Path=/; SameSite=Lax
...

La redirección lleva de vuelta a la página de origen y la cookie se establece por un año. Un [Referer] que apunte a otro sitio no redirige hacia allá: solo se conserva su ruta.

curl -i -H "Referer: https://pirate.example/trap" http://localhost:5000/language/en
curl -i -H "Referer: http://localhost:5000//pirate.example/x" http://localhost:5000/language/fr
1
2
3
4
5
6
HTTP/1.1 302 FOUND
...
Location: /trap
HTTP/1.1 302 FOUND
...
Location: /

La página [/trap] no existe en nuestro sitio: el usuario recibirá un error 404, pero permanecerá en nuestro sitio. Por último, la página de inicio, solicitada con la cookie [language=en] (opción [-b] de [curl]):

curl -b "language=en" http://localhost:5000/
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Welcome</title>
  ...
    <a class="nav-link" href="/">Home</a>
    <a class="nav-link" href="/products">Products</a>
  ...
  <h1>Welcome</h1>
  <p>Hello Marie!</p>
  <p>Today is Wednesday, September 23, 2026.</p>
...

Otra manera de seleccionar el idioma habría sido leer el encabezado [Accept-Language] del navegador (ejemplo 12). Con frecuencia se combinan ambas: el idioma del navegador en la primera visita y, después, el idioma que el usuario haya seleccionado. Este caso de estudio se centra en la cookie, con el inglés como idioma predeterminado.