Skip to content

5. Internacionalização

Uma aplicação internacionalizada exibe seus textos no idioma do usuário. O estudo de caso é em francês e inglês. O princípio é simples: os templates contêm textos marcados como “a traduzir” e um dicionário para cada idioma associa cada texto à sua tradução. O idioma selecionado é armazenado em um cookie.

O [Django] usa o [gettext] para isso, o sistema de tradução do projeto GNU, que o [Python] também reconhece (o módulo [gettext] da biblioteca padrão) e que está presente em muitos softwares de código aberto. Com o [gettext], a chave de um texto é o próprio texto, escrito no idioma original: um template escrito com [{% translate "Home" %}], e o dicionário francês associa “Home” a “Accueil”. Uma página continua, assim, legível e funcional mesmo sem dicionário: o texto é exibido no idioma original. Isso difere das versões em [Symfony], [Laravel], [Flask], [Spring MVC], [ASP.NET Core MVC] e [NestJS] do estudo de caso, que usavam chaves abstratas ([MENU.HOME]). Os dicionários são arquivos de texto no formato [.po] (Portable Object), que ferramentas podem extrair do código e que programas de tradução podem editar; o [Django] lê sua versão compilada, os arquivos [.mo] (Machine Object). [gettext] também sabe flexionar um texto no plural conforme as regras de cada idioma. [Django] é ele próprio traduzido dessa maneira: é graças a seus dicionários que ele consegue exibir suas mensagens de erro em francês (desde o exemplo 08, elas estão em inglês, o idioma padrão). A formatação de datas e valores continua a mesma do exemplo 16.

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

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. A configuração: config/settings.py

# config/settings.py: a configuração do exemplo 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"

# o idioma padrão e os idiomas tratados pela aplicação
LANGUAGE_CODE = "en"
LANGUAGES = [
    ("fr", "Français"),
    ("en", "English"),
]
# as pastas dos DICIONÁRIOS da aplicação (arquivos .po, compilados em .mo)
LOCALE_PATHS = [BASE_DIR / "locale"]
# o cookie que memoriza o idioma escolhido (é também o nome padrão)
LANGUAGE_COOKIE_NAME = "django_language"

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

MIDDLEWARE = [
    # LocaleMiddleware: o idioma de cada requisição, lido no cookie de idioma,
    # na falta dele no cabeçalho Accept-Language do navegador e, por fim, em 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",
                # a variável LANGUAGE_CODE: o idioma da requisição
                "django.template.context_processors.i18n",
            ],
        },
    },
]

STATIC_URL = "static/"
STATICFILES_DIRS = [
    BASE_DIR / "static",
    BASE_DIR.parent / "common" / "static",
]
  • Linha 14: o idioma padrão da aplicação, usado para as requisições que não especificam um idioma (exemplo 08). É também o idioma dos textos dos templates; portanto, o inglês não requer dicionário;
  • Linhas 15–18: os idiomas aceitos pela aplicação;
  • Linha 20: [LOCALE_PATHS], as pastas em que o [Django] procura os dicionários da aplicação, além das pastas [locale] de cada aplicação (inclusive as do próprio [Django] ). Cada dicionário fica em uma pasta [<language>/LC_MESSAGES], com o nome [django.po] (e [django.mo]): essa é a organização exigida pelo [gettext];
  • linha 22: o nome do cookie que armazena o idioma selecionado. [django_language] é o valor padrão; nós o incluímos aqui para que fique visível;
  • linhas 29–33: o middleware [LocaleMiddleware] do [Django] substitui nosso middleware [SetLanguage] do exemplo 16. Para cada requisição, ele seleciona o idioma dentre os especificados na configuração [LANGUAGES]: o idioma indicado no cookie de idioma, se houver; caso contrário, o idioma preferido do navegador, com base no cabeçalho [Accept-Language] (exemplo 12); caso contrário, [LANGUAGE_CODE]. Ele o ativa ([translation.activate], exemplo 16) e o armazena em [request.LANGUAGE_CODE]. Por fim, adiciona à resposta o cabeçalho [Content-Language] (o idioma da página), junto com o cabeçalho [Vary: Accept-Language], que avisa aos caches que a resposta depende desse cabeçalho;
  • linha 43: o processador de contexto [i18n] adiciona aos templates as variáveis [LANGUAGE_CODE] (o idioma da requisição), [LANGUAGES] e [LANGUAGE_BIDI] (verdadeira para um idioma escrito da direita para a esquerda).

5.1.2. O dicionário: locale/fr/LC_MESSAGES/django.po

# locale/fr/LC_MESSAGES/django.po: o dicionário francês do exemplo 22.
# msgid: o texto original, tal como está escrito nos templates (em inglês);
# msgstr: sua tradução. Este arquivo é compilado em django.mo (o arquivo que
# o Django lê) pelo 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."

Um arquivo [.po] é uma sequência de entradas, separadas por linhas em branco:

  • linhas 1–4: um comentário;
  • linhas 5–11: a entrada de cabeçalho: uma string vazia ([msgid ""]), cuja “tradução” ([msgstr]) contém as informações do dicionário: o idioma, o conjunto de caracteres e a regra de plural do idioma ([Plural-Forms]: em francês, duas formas, a segunda para qualquer número maior que 1);
  • linhas 13–15: uma entrada padrão: [msgid] é o texto de origem, como escrito no template; [msgstr] é sua tradução. A linha [#:] indica onde o texto foi encontrado (um template e uma linha): é um comentário para o tradutor;
  • linhas 25–28: um texto que contém uma variável. No dicionário, uma variável é escrita como [%(name)s] (a sintaxe das strings de formato do [Python], exemplo 10); a linha [#, python-format] sinaliza isso para as ferramentas. A tradução pode reposicionar a variável ou alterar a pontuação ao redor dela (em francês, o ponto de exclamação é precedido por um espaço);
  • linhas 47–52: uma forma plural: [msgid] é a forma singular, [msgid_plural] é a forma plural, e cada forma da tradução é numerada ([msgstr[0]], [msgstr[1]]), na ordem especificada pela regra [Plural-Forms]. Em francês, 0 e 1 são singular, ao passo que em inglês 0 é plural (“0 products”): o [gettext] sabe disso graças a essa regra. É um avanço em relação ao “product(s)” usado nas versões anteriores do estudo de caso.

Esse arquivo não é escrito à mão. O comando:

python manage.py makemessages -l fr

examina os templates do projeto e o código [Python], extrai todos os textos marcados como “a traduzir” e cria ou atualiza o arquivo [locale/fr/LC_MESSAGES/django.po]: os textos novos são adicionados a ele com uma tradução vazia, e as traduções existentes são preservadas. Resta apenas escrever as traduções, em um editor de texto ou em um software especializado ([Poedit], por exemplo). O comando:

python manage.py compilemessages

compila então cada arquivo [.po] em um arquivo [.mo] — um arquivo binário de leitura rápida — que é o utilizado pelo [Django]. É preciso reiniciar o servidor após uma compilação: os dicionários são carregados uma única vez. Esses dois comandos usam os programas do [gettext] ([xgettext], [msgfmt]...), que precisam estar instalados (no [Linux], o pacote [gettext]; no [Windows], por exemplo, os binários distribuídos no site mlocati.github.io). Como o arquivo [django.mo] é fornecido com o exemplo, não é necessário instalar esses pacotes para executá-lo.

5.1.3. Seleção do idioma: rotas e views

# config/urls.py: a tabela de roteamento 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: uma rota descrita por uma expressão regular; um idioma diferente
    # de fr ou en não corresponde à rota (404)
    re_path(r"^language/(?P<code>fr|en)$", views.change_language, name="language"),
]
  • Linha 12: [re_path] descreve uma rota por meio de uma expressão regular, em vez da sintaxe de [path] (exemplo 02). [^] e [$] marcam o início e o fim do caminho; [(?P<code>fr|en)] é um grupo nomeado: o texto que ele reconhece — [fr] ou [en] (a barra vertical significa “ou”) — é passado à view no parâmetro [code]. Outro idioma não corresponde a nenhuma rota: [/language/de] retorna um erro 404.
# pages/views.py: as views não sabem nada sobre o idioma: elas fornecem
# os dados, os templates os traduzem e formatam

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: memoriza a escolha no cookie de idioma e depois volta à
# página anterior
@require_GET
def change_language(request, code):
    response = redirect(origin_page(request))
    # 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 Lax)
    response.set_cookie(settings.LANGUAGE_COOKIE_NAME, code, max_age=365 * 24 * 3600,
                        httponly=True, samesite="Lax")
    return response


# a página de origem (cabeçalho Referer), se ela pertencer a ESTE site: redirecionar
# para qualquer endereço vindo da requisição permitiria enviar
# o usuário a outro site (falha de "open redirect")
def origin_page(request):
    referer = request.headers.get("Referer", "")
    # url_has_allowed_host_and_scheme: verdadeiro para um endereço relativo ou um endereço
    # absoluto cujo host é o da requisição
    if url_has_allowed_host_and_scheme(referer, allowed_hosts={request.get_host()}):
        return referer
    return "/"
  • Linhas 14–25: as views da página inicial e de produtos não conhecem o idioma; elas fornecem dados brutos (um nome, uma data, valores em centavos). A tradução e a formatação ficam a cargo dos templates. A classe [Product] tem um nome e um preço em centavos; a biblioteca [formats] é a do exemplo 16: seu filtro [long_date] escreve uma data no formato “completo” do idioma ativo (“Wednesday, September 23, 2026”, “mercredi 23 septembre 2026”), e seu filtro [money] exibe um valor monetário.
  • linhas 30–37: a view de troca de idioma responde redirecionando o usuário de volta à página de onde veio; o usuário retorna à sua página de origem no novo idioma;
  • linhas 35–36: a resposta inclui um cookie, que o navegador reenviará a cada requisição. [set_cookie] recebe seu nome, valor e opções: [max_age], sua duração de vida 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. Ele é adicionado à resposta como um cabeçalho [Set-Cookie];
  • linhas 43–49: a página de origem é indicada pelo cabeçalho [Referer] da requisição (a grafia incorreta, com um único [r], é a do 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 enviar o usuário a um site malicioso. A função [url_has_allowed_host_and_scheme] do [Django] ([django.utils.http]) verifica se um endereço é relativo ou se aponta para uma das máquinas permitidas (neste caso, a da requisição: [request.get_host()]); caso contrário, o usuário é redirecionado para a página inicial.

O [Django] também fornece uma view pronta para trocar o idioma, [django.views.i18n.set_language], que executa a mesma tarefa por meio de um formulário (POST); escrevemos a nossa para demonstrá-lo e para permitir a troca de idioma por um simples link.

5.1.4. Tradução nos templates

<!doctype html>
{% load static %}
{# LANGUAGE_CODE: o idioma da requisição, "fr" ou "en" #}
<html lang="{{ LANGUAGE_CODE }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {# o título: o bloco [title] da página, já traduzido #}
  <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>
  • linha 4: o atributo [lang] da página indica seu idioma aos navegadores, aos mecanismos de busca e aos leitores de tela; [LANGUAGE_CODE] é o idioma da requisição, fornecido pelo processador de contexto [i18n];
  • Linha 9: o título da página é fornecido pela própria página, já traduzido (bloco [title]).
{# i18n: a biblioteca das tags de tradução #}
{% load i18n %}
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <div class="navbar-nav me-auto">
    {# translate: a tradução de um texto, no idioma da requisição #}
    <a class="nav-link" href="{% url 'home' %}">{% translate "Home" %}</a>
    <a class="nav-link" href="{% url 'products' %}">{% translate "Products" %}</a>
  </div>
  {# get_available_languages: os idiomas da configuração LANGUAGES, pares (código, nome) #}
  {% get_available_languages as languages %}
  <div class="btn-group btn-group-sm">
    {% for code, name in languages %}
      {# o idioma atual é destacado #}
      <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>
  • linha 2: as tags de tradução estão na biblioteca [i18n], que cada template deve carregar (exemplo 16);
  • linhas 6–7: a tag [{% translate %}] retorna a tradução de um texto para o idioma da requisição (ou o próprio texto, se não houver tradução);
  • linhas 10–17: a tag [{% get_available_languages %}] armazena em uma variável os idiomas da configuração [LANGUAGES] — pares (código, nome) —, que o laço então percorre ([for code, name in languages]). Um botão por idioma, que leva à view [/language/<code>]. O idioma atual é destacado ([btn-primary], botão preenchido).
{% extends "layout.html" %}
{% load i18n formats %}

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

{% block content %}
  <h1>{% translate "Welcome" %}</h1>
  {# blocktranslate: um texto que contém variáveis {{ name }} #}
  <p>{% blocktranslate %}Hello {{ name }}!{% endblocktranslate %}</p>
  {# with: a data, formatada primeiro (filtro long_date, veja o exemplo 16), depois inserida no texto #}
  <p>{% blocktranslate with date=today|long_date %}Today is {{ date }}.{% endblocktranslate %}</p>
{% endblock %}
  • linha 4: o bloco [title], traduzido, para o template pai;
  • linha 9: a tag [{% blocktranslate %}] traduz textos que contêm variáveis: [{{ name }}] torna-se [%(name)s] no dicionário. Aqui só são permitidas variáveis simples (sem filtros nem pontos);
  • linha 11: uma variável calculada só pode, portanto, ser incluída no texto por meio de [with]: a data, formatada no idioma da requisição pelo filtro [long_date], é armazenada na variável [date] no 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>
          {# o filtro money do exemplo 16: o formato depende do idioma #}
          <td class="text-end">{{ product.price_cents|money }}</td>
        </tr>
      {% endfor %}
    </tbody>
  </table>
  {# o plural: count escolhe a forma de acordo com o número n; plural separa as formas #}
  <p>{% blocktranslate count n=products|length %}{{ n }} product in the catalogue.{% plural %}{{ n }} products in the catalogue.{% endblocktranslate %}</p>
{% endblock %}
  • linha 15: o filtro [money], cujo resultado depende do idioma;
  • linha 21: o plural. [count n=products|length] retorna o número que determina a forma ([length], exemplo 14); a tag [{% plural %}] separa a forma singular da forma plural, escritas no idioma de origem. 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.

Fora dos templates, a tradução é feita pelas funções do módulo [django.utils.translation]: [gettext("Home")] (frequentemente importada com o nome curto [_]: [_("Home")]), [ngettext] para o plural e [gettext_lazy], uma tradução “preguiçosa” (lazy), realizada somente quando o texto é usado: é a que se deve usar para textos definidos quando um módulo é carregado (o rótulo de um campo de formulário, por exemplo), quando o idioma da requisição ainda não é conhecido. O estudo de caso a utiliza.

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

O redirecionamento leva de volta à página de origem, e o cookie é configurado para durar um ano. A própria resposta continua em inglês ([Content-Language: en]): o idioma só foi selecionado quando a requisição chegou, antes de o cookie existir. Um [Referer] que aponta para outro site não permite o redirecionamento para lá:

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

O usuário volta à página inicial e permanece em nosso site. Por fim, a página inicial, solicitada com o cookie [django_language=fr] (opção [-b] do [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>
...

O cookie não é assinado: ele é transmitido em texto simples e o usuário pode modificá-lo. Isso não é um problema: ele não contém nenhuma informação confidencial, e o [LocaleMiddleware] só aceita os idiomas especificados na configuração [LANGUAGES]. O exemplo seguinte ilustra o nível de confiança que se pode depositar em um cookie. Sem cookie, o [LocaleMiddleware] lê o cabeçalho [Accept-Language] do navegador: [curl -H "Accept-Language: fr-FR,fr;q=0.9" http://localhost:8000/] renderiza a página em francês. Os dois mecanismos se combinam, assim, naturalmente: o idioma do navegador na primeira visita e, depois, o idioma escolhido pelo usuário. Uma terceira abordagem, comum, coloca o idioma na URL ([/fr/products]): a função [i18n_patterns] do [Django] prefixa então as rotas com o idioma, e o [LocaleMiddleware] o lê a partir do caminho. Este estudo de caso se concentra no cookie.