Skip to content

5. Internacionalização

Uma aplicação internacionalizada exibe seus textos no idioma do usuário. O estudo de caso está em francês e inglês. O princípio é simples: as views não contêm mais texto, e sim chaves ([MENU.HOME]), e um dicionário para cada idioma associa um texto a cada chave. O idioma selecionado é armazenado em um cookie.

O ecossistema do [Flask] oferece uma extensão para essa finalidade, [Flask-Babel], que se apoia no sistema de tradução padrão [gettext]: os textos são extraídos do código por uma ferramenta, traduzidos em arquivos [.po] e depois compilados em arquivos [.mo]. É um sistema poderoso, mas exige ferramentas específicas e uma etapa de compilação. Em vez disso, escreveremos uma pequena classe que lê dicionários JSON: são os mesmos arquivos das versões [ASP.NET Core MVC], [NestJS], e [Spring MVC] do estudo de caso, e seu formato pode ser lido e escrito sem nenhuma ferramenta especial. A biblioteca [Babel], por outro lado, continua sendo usada para formatar datas e valores (Exemplo 16).

5.1. Exemplo 22: Uma aplicação bilíngue

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. Dicionários

O arquivo [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."
  }
}

As chaves são agrupadas por tema dentro de objetos JSON aninhados: o texto de menu “Home” tem a chave completa [MENU.HOME]. Uma string de texto pode conter placeholders, escritos como [{name}], que são substituídos durante a tradução. O arquivo [i18n/en.json] tem exatamente as mesmas chaves:

{
  "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. O serviço de tradução: translation/translator.py

# translation/translator.py: o serviço de tradução
import json
import re
from pathlib import Path

from flask import g


class Translator:

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

    # {name}: um parâmetro em um texto
    PARAMETER = re.compile(r"\{(\w+)\}")

    def __init__(self, folder: Path):
        # idioma -> (chave 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))

    # o idioma suportado que corresponde a [code]: "fr" -> "fr"; "de" ou 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!", no
    # idioma da requisição atual (g.language, veja app.py)
    def translate(self, key: str, **parameters) -> str:
        # uma chave ausente exibe a própria chave: um esquecimento fica visível na tela
        text = self._dictionaries[g.language].get(key, key)
        # cada {name} é substituído pelo valor do parâmetro de mesmo nome
        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
  • linhas 11–12: os idiomas suportados e o idioma padrão — atributos de classe compartilhados por todos os objetos da classe e acessíveis sem um objeto ([Translator.LANGUAGES]);
  • linha 15: a expressão regular de um parâmetro: uma chave de abertura ([\{], precedida de uma [\] porque a chave tem um significado específico nas expressões regulares), um ou mais caracteres de palavra ([\w+]) e uma chave de fechamento. Os parênteses capturam o nome do parâmetro. [re.compile] analisa a expressão uma vez por todas;
  • linhas 17–22: o construtor lê os dicionários uma única vez, quando o serviço é criado. [json.load] converte o conteúdo de um arquivo JSON em objetos [Python] (dicionários aninhados). [with open(...) as file] abre o arquivo e garante que ele seja fechado ao final do bloco; [encoding="utf-8"] é essencial, pois a codificação padrão depende do sistema (no [Windows], nem sempre é [UTF-8]);
  • Linhas 25–27: um método de classe (decorador [@classmethod]) recebe a classe ([cls]) em vez de um objeto; ele é chamado na própria classe: [Translator.language("en")]. Retorna o idioma suportado correspondente a um código, ou o idioma padrão se o código for desconhecido ou estiver ausente;
  • linhas 31–36: a tradução de uma chave, no idioma da requisição atual, lido de [g.language] (veja o Exemplo 16). Uma chave ausente do dicionário é exibida como está: uma omissão fica imediatamente visível na tela. Os parâmetros são recebidos como parâmetros nomeados ([**parameters]); o método de expressão regular [sub] substitui cada parâmetro encontrado no texto pelo resultado de uma função — neste caso, uma função anônima ([lambda m: ...]) — que recebe a correspondência encontrada ([m]): [m.group(1)] é o nome capturado, [m.group(0)] é o texto completo [{name}], que é mantido se o parâmetro não foi fornecido;
  • Linhas 40–48: os objetos JSON aninhados são “achatados” em um único dicionário, cujas chaves são as chaves completas: [{"MENU": {"HOME": "Home"}}] torna-se [{"MENU.HOME": "Home"}]. O método é recursivo: ele chama a si mesmo para cada objeto aninhado, usando a chave atual como prefixo.

5.1.3. Formatação no idioma da requisição: translation/formats.py

# translation/formats.py: datas e valores, formatados no idioma da requisição (veja o exemplo 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


# uma data por extenso
def long_date(day: date) -> str:
    return format_date(day, format="full", locale=g.language)


# um valor em euros
def money(amount: Decimal) -> str:
    return format_currency(amount, "EUR", locale=g.language)

Os filtros do Exemplo 16, que desta vez usam [g.language]. [Babel] aceita um único idioma ([fr], [en]) bem como um idioma e um país ([fr_FR]); para [en], aplica as convenções dos EUA.

5.1.4. Configuração: app.py

# app.py: a aplicação do exemplo 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, compartilhado pelos exemplos (veja o exemplo 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
    # o serviço de tradução: os dicionários, lidos UMA ÚNICA VEZ, na inicialização
    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)

    # o idioma de cada requisição: o do cookie [language], inglês caso contrário
    @app.before_request
    def set_language():
        g.language = Translator.language(request.cookies.get(LANGUAGE_COOKIE))

    # nas views: {{ 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)
  • linhas 20–21: o serviço, criado uma única vez na inicialização. [app.root_path] é a pasta da aplicação (a de [app.py]);
  • Linhas 28–30: antes de cada ação, o idioma da requisição é definido como o do cookie [language] se ele existir e for suportado; caso contrário, assume o inglês. [request.cookies] é o dicionário de cookies enviados pelo navegador;
  • linha 33: o método [translate] do serviço é disponibilizado às views como uma função global com um nome curto, [t] (o segundo parâmetro de [add_template_global]). Um método de objeto é usado como uma função: [translator.translate] é um método associado ao objeto [translator].

5.1.5. Seleção do idioma: controllers/language.py

# controllers/language.py: a escolha do 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 a escolha em um cookie e volta para a página anterior
@language.get("/language/<code>")
def change(code):
    if code not in Translator.LANGUAGES:
        abort(404)
    response = redirect(origin_page())
    # o cookie: um ano de vida, ilegível pelo JavaScript da página (httponly),
    # nunca enviado com uma requisição POST vinda de outro site (samesite)
    response.set_cookie(LANGUAGE_COOKIE, code, max_age=365 * 24 * 3600, httponly=True,
                        samesite="Lax")
    return response


# a página de onde viemos (cabeçalho Referer), da qual mantemos apenas o caminho:
# redirecionar para um endereço completo vindo da requisição permitiria
# enviar o usuário a outro site (falha de "open redirect")
def origin_page() -> str:
    url = urlsplit(request.headers.get("Referer", ""))
    path = url.path
    # "//site.com/..." seria entendido pelo navegador como um endereço
    # de OUTRO site: também rejeitado
    if not path.startswith("/") or path.startswith("//"):
        return "/"
    return f"{path}?{url.query}" if url.query else path
  • linha 16: um código de idioma desconhecido: 404;
  • linha 18: a ação responde com um redirecionamento para a página de onde o usuário veio: o usuário volta a essa página, no novo idioma;
  • Linhas 21–22: a resposta inclui um cookie, que o navegador enviará de volta a cada requisição. [max_age] é sua duração, em segundos: um ano. [httponly=True] o torna invisível para o [JavaScript] da página; [samesite="Lax"] impede que o navegador o envie com uma requisição POST originada em outro site. Diferentemente do cookie de sessão (exemplo 20), este cookie não é assinado: não há problema se o usuário o modificar, pois o servidor só aceita os idiomas suportados;
  • linhas 29–36: a página de origem é indicada pelo cabeçalho [Referer] da requisição (a grafia incorreta, com um único [r], é a usada no padrão HTTP), que o navegador preenche com a URL da página que continha o link. Mas esse cabeçalho vem do cliente, que pode colocar qualquer coisa nele. Redirecionar às cegas para esse endereço transformaria nossa aplicação em um *open redirect*: um link malicioso com o nome do nosso domínio poderia levar o usuário a um site malicioso. Por isso, mantemos apenas o caminho e os parâmetros da URL ([urlsplit] a decompõe em seus componentes) e rejeitamos qualquer caminho que comece por [//], que o navegador interpretaria como o endereço de outro site.

5.1.6. Ações: controllers/pages.py

# controllers/pages.py: as ações não sabem nada do idioma: elas
# fornecem dados, as views os traduzem e os formatam
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")),
    ])

As ações são agnósticas quanto ao idioma: fornecem dados brutos (um nome, uma data, valores). A tradução e a formatação ficam a cargo das views.

5.1.7. Tradução nas views

<!doctype html>
{# g.language: o idioma da requisição, "fr" ou "en" #}
<html lang="{{ g.language }}">
<head>
  <meta charset="utf-8">
  {# o título é uma CHAVE, fornecida pela página (variável title_key), traduzida pelo 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>
  • Linha 3: o atributo [lang] da página indica seu idioma a navegadores, mecanismos de busca e leitores de tela;
  • linha 7: o título da página é diferente para cada página, mas é traduzido pelo template. Cada página fornece a chave de seu título em uma variável, [title_key].
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <div class="navbar-nav me-auto">
    {# t('KEY'): a tradução de uma chave, no idioma da requisição #}
    <a class="nav-link" href="/">{{ t("MENU.HOME") }}</a>
    <a class="nav-link" href="/products">{{ t("MENU.PRODUCTS") }}</a>
  </div>
  {# o idioma atual fica destacado #}
  <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>
  • linhas 4–5: os textos do menu, traduzidos;
  • linhas 9–12: um botão por idioma, que leva à ação [/language/<code>]. O idioma atual é destacado ([btn-primary], botão preenchido).
{% extends "layout.html" %}
{# uma variável definida FORA dos blocos é visível para o layout #}
{% set title_key = "HOME.TITLE" %}

{% block content %}
  <h1>{{ t("HOME.TITLE") }}</h1>
  {# um parâmetro: um parâmetro nomeado da função t #}
  <p>{{ t("HOME.HELLO", name=name) }}</p>
  {# a data, formatada primeiro e depois passada como parâmetro [date] #}
  <p>{{ t("HOME.DATE", date=today | long_date) }}</p>
{% endblock %}
  • linha 3: uma variável definida fora dos blocos de uma página que estende um template é visível para o template: é assim que a página passa a chave de seu título ao template. (Uma variável definida dentro de um bloco, por outro lado, permaneceria local a esse bloco.);
  • linha 8: um parâmetro de texto é um parâmetro nomeado da função [t];
  • Linha 10: a data, formatada no idioma da requisição e depois passada 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 %}
  • Linha 17: um parâmetro calculado. Os nomes dos produtos, porém, não são traduzidos: são dados que, em uma aplicação real, viriam de um banco de dados.

5.1.8. Execução

A página inicial, em inglês (o idioma padrão) e depois em francês, após clicar no botão “FR”:

Image

Image

A página de produtos, nos dois idiomas. Os valores seguem as convenções de cada idioma:

Image

Image

A troca de idioma, vista com o [curl]. A opção [-H] fornece o cabeçalho [Referer] que o navegador enviaria:

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

O redirecionamento leva de volta à página de origem, e o cookie é definido por um ano. Um [Referer] que aponte para outro site não redireciona para lá: apenas seu caminho é mantido.

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

A página [/trap] não existe em nosso site: o usuário receberá um erro 404, mas permanecerá em nosso site. Por fim, a página inicial, solicitada com o cookie [language=en] (opção [-b] do [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>
...

Outra maneira de selecionar o idioma seria ler o cabeçalho [Accept-Language] do navegador (Exemplo 12). Os dois costumam ser combinados: o idioma do navegador na primeira visita, seguido do idioma que o usuário selecionou. Este estudo de caso se concentra no cookie, com o inglês como padrão.