Django i18n: O Guia Completo para Automatizar a Tradução de Arquivos .po

Se você já publicou um aplicativo Django em mais de um idioma, conhece o processo. Você envolve suas strings em gettext(), executa makemessages, abre um arquivo .po com centenas de entradas e começa a traduzir linha por linha. Para dois idiomas e cinquenta strings, é tolerável. Para seis idiomas e quinhentas strings, é um dia inteiro de trabalho que você nunca vai recuperar.

Este guia cobre o pipeline de internacionalização (i18n) do Django do início ao fim, explica onde ele falha e mostra como automatizar a parte dolorosa com tradução assistida por IA.

O fluxo de trabalho padrão do Django i18n

O sistema i18n embutido do Django é bem projetado. O ciclo principal se parece com isto:

Passo 1: Marque as strings para tradução no seu código Python e templates:

from django.utils.translation import gettext as _

def dashboard(request):
    welcome = _("Welcome back, %(name)s!") % {"name": request.user.first_name}
    return render(request, "dashboard.html", {"welcome": welcome})

{% load i18n %}
<h1>{% trans "Account Settings" %}</h1>
<p>{% blocktrans %}You have {{ count }} unread messages.{% endblocktrans %}</p>

Passo 2: Extraia as strings para arquivos .po:

python manage.py makemessages -l de -l fr -l nl

Isso escaneia toda a sua base de código e gera um arquivo .po por idioma, contendo cada string traduzível:

#: myapp/views.py:4
msgid "Welcome back, %(name)s!"
msgstr ""

#: templates/dashboard.html:2
msgid "Account Settings"
msgstr ""

Passo 3: Traduza cada msgstr vazio manualmente.

Passo 4: Compile os arquivos .po finalizados em arquivos binários .mo:

python manage.py compilemessages

Os passos 1, 2 e 4 são rápidos. O passo 3 é onde o processo desmorona.

Por que a tradução manual não escala

Uma aplicação Django típica tem entre 200 e 2.000 strings traduzíveis. Multiplique isso pelo número de idiomas alvo e você está diante de um compromisso de tempo sério.

Isso não é uma reclamação teórica. Em um tópico bem conhecido do Django Forum, um desenvolvedor relatou gastar mais de 8 horas por arquivo .po fazendo traduções manuais. Um contribuidor principal do Django descreveu gastar mais de 10 horas para incorporar traduções enviadas pela comunidade em um único lançamento, principalmente em revisão, correções de formatação e correção de placeholders quebrados.

Os problemas se acumulam com o tempo:

• Placeholders quebram. Copie uma string como Welcome, %(name)s! no Google Translate e você frequentemente receberá Willkommen, %(Name)s! ou Bienvenue, %(nom)s!. Essa corrupção sutil causa falhas em tempo de execução.
• A consistência diverge. Sem um glossário, "dashboard" é traduzido como "Instrumententafel" em um arquivo e "Dashboard" em outro. Três meses depois, ninguém lembra qual foi intencional.
• Sprints adicionam strings. Cada branch de funcionalidade adiciona novas strings traduzíveis. Mesmo se você pagou por uma tradução completa no trimestre passado, agora tem 40 entradas não traduzidas espalhadas pelos seus arquivos .po.
• Assistentes de IA ajudam uma vez. Você pode colar um arquivo .po no ChatGPT ou Claude e obter resultados decentes. Mas no próximo sprint, quando 15 novas strings aparecem, você está fazendo prompts do zero, retraduzindo o arquivo inteiro e esperando que fique consistente com o que já existia.

A causa raiz é que a tradução é tratada como um evento único em vez de um processo incremental e repetível.

Automatizando a tradução com IA

A ideia é direta: em vez de um humano abrir cada arquivo .po e preencher os valores de msgstr, uma ferramenta lê o arquivo, envia as strings não traduzidas para um modelo de IA ou API de tradução, escreve os resultados de volta e preserva todo o resto (comentários, estrutura do arquivo, placeholders, formas plurais).

TranslateBot Django é um pacote open source que faz exatamente isso. Ele se integra ao sistema de comandos de gerenciamento do Django, então se encaixa no fluxo de trabalho que você já tem.

Configuração passo a passo

1. Instale o pacote

pip install translatebot-django

Ou, se você usa uv (recomendado):

uv add --dev translatebot-django

Instalá-lo como dependência de desenvolvimento é intencional. Você só precisa do TranslateBot ao gerar traduções, não em tempo de execução na produção.

2. Adicione ao INSTALLED_APPS

# settings.py
INSTALLED_APPS = [
    # ...
    "translatebot_django",
]

3. Configure seu provedor de IA

# settings.py
import os

TRANSLATEBOT_API_KEY = os.getenv("OPENAI_API_KEY")
TRANSLATEBOT_MODEL = "gpt-4o-mini"

O TranslateBot usa LiteLLM internamente, o que significa que você pode trocar para qualquer um dos mais de 100 modelos alterando uma única string:

Para DeepL, instale o extra: pip install translatebot-django[deepl]. O nível gratuito do DeepL oferece 500.000 caracteres por mês sem custo, o que é suficiente para a maioria dos projetos pequenos a médios.

4. Defina seus idiomas

# settings.py
LANGUAGES = [
    ("en", "English"),
    ("de", "German"),
    ("fr", "French"),
    ("nl", "Dutch"),
    ("ja", "Japanese"),
]

5. Execute a tradução

python manage.py translate

É isso. O TranslateBot escaneia seu projeto em busca de arquivos .po, identifica entradas não traduzidas, envia-as ao modelo de IA configurado em lotes otimizados e escreve os resultados de volta. Traduções existentes permanecem intactas.

Para traduzir um único idioma:

python manage.py translate --target-lang nl

A saída se parece com isto:

Translating to Dutch (nl)...
Found 42 strings to translate
Translating batch 1/2...
Translating batch 2/2...
Successfully translated 42 strings

6. Compile como de costume

python manage.py compilemessages

Seu fluxo de trabalho completo agora é:

python manage.py makemessages -l de -l fr -l nl -l ja
python manage.py translate
python manage.py compilemessages

Três comandos. Todos os idiomas. Cada sprint.

Incremental por design

A funcionalidade mais importante para um fluxo de trabalho repetível é a tradução incremental. O TranslateBot só traduz entradas onde msgstr está vazio. Se você tem 500 strings e 15 são novas neste sprint, apenas essas 15 são enviadas à API.

Isso importa por razões práticas:

1. Custo. Você paga apenas pelas novas strings, não pelo arquivo inteiro.
2. Velocidade. Traduzir 15 strings leva segundos, não minutos.
3. Estabilidade. Traduções que você já revisou e aprovou nunca são sobrescritas (a menos que você passe explicitamente --overwrite).

Segurança de placeholders

O Django usa vários formatos de placeholder: %(name)s, %s, %d, {0}, {name}, e tags HTML inline como <strong> ou <a href="...">. Se qualquer um deles for corrompido na tradução, você terá erros em tempo de execução ou markup quebrado.

O TranslateBot instrui o modelo de IA a preservar todos os formatos de placeholder e valida a saída. Uma string como:

Welcome to %(site_name)s! You have <strong>%(count)d</strong> new messages.

É traduzida para holandês como:

Welkom bij %(site_name)s! Je hebt <strong>%(count)d</strong> nieuwe berichten.

Cada placeholder sobrevive intacto.

Controlando a qualidade com TRANSLATING.md

Modelos de IA traduzem melhor quando entendem o contexto. O TranslateBot procura um arquivo TRANSLATING.md na raiz do seu projeto e inclui seu conteúdo em cada solicitação de tradução.

# Translation Context

## About This Project
A B2B project management tool for construction companies.

## Terminology
- "project" means a construction project, not a software project
- "plan" means a building plan/blueprint, not a subscription plan
- Keep "Gantt chart" as-is in all languages

## Tone
- German: use formal "Sie" form (business context)
- French: use formal "vous" form
- Dutch: use informal "je" form

## Do Not Translate
- Brand name: "BuildFlow"
- Feature names: "SmartSchedule", "CostTracker"

Este arquivo é versionado junto com seu código, então toda a sua equipe compartilha o mesmo contexto de tradução. Você também pode colocar arquivos TRANSLATING.md por aplicativo para apps com terminologia especializada. Um módulo de registros médicos e um módulo de faturamento podem ter cada um seu próprio glossário.

Pré-visualizar antes de commitar

A flag --dry-run mostra exatamente o que seria traduzido sem fazer chamadas à API ou modificar arquivos:

python manage.py translate --target-lang fr --dry-run

Found 15 untranslated entries
Dry run mode: skipping LLM translation

Would translate 'Welcome to our site'
Would translate 'Hello, %(name)s!'
...

Dry run complete: 15 entries would be translated

Isso é útil antes de uma grande execução de tradução ou quando um novo membro da equipe quer entender o que o comando faz antes de se comprometer com custos de API.

Integração CI/CD

Traduções ficarem desatualizadas é inevitável sem enforcement. O TranslateBot inclui um comando de gerenciamento check_translations projetado para pipelines de CI:

# .github/workflows/ci.yml
jobs:
  translations:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v4
        with:
          enable-cache: true
      - run: uv python install
      - run: uv sync --frozen
      - name: Install gettext
        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends gettext
      - name: Check translations
        run: uv run python manage.py check_translations --makemessages

A flag --makemessages executa primeiro makemessages -a --no-obsolete, garantindo que os arquivos .po reflitam o código-fonte atual antes de verificar. Se alguma entrada estiver sem tradução ou fuzzy, o comando sai com código 1 e falha o build:

locale/de/LC_MESSAGES/django.po: 2 untranslated, 0 fuzzy
locale/nl/LC_MESSAGES/django.po: 0 untranslated, 1 fuzzy
CommandError: Translation check failed

O fluxo de trabalho típico do desenvolvedor se torna:

1. Adicionar novas strings traduzíveis em uma branch de funcionalidade.
2. CI falha porque essas strings estão sem tradução.
3. Executar python manage.py translate localmente.
4. Commitar os arquivos .po atualizados.
5. CI passa.

Traduções nunca ficam silenciosamente fora de sincronia.

Traduzindo conteúdo do banco de dados

Se sua aplicação armazena conteúdo traduzível no banco de dados (nomes de produtos, títulos de posts de blog, rótulos de categorias), o TranslateBot também se integra com django-modeltranslation:

pip install translatebot-django[modeltranslation]

# Translate all registered model fields
python manage.py translate --target-lang de --models

# Translate specific models only
python manage.py translate --target-lang de --models Product Category

A mesma lógica incremental se aplica: apenas campos onde o valor do idioma alvo está vazio são traduzidos.

Comparação de custos

Uma das perguntas mais comuns é se a tradução por IA é econômica em comparação com as alternativas. Aqui está uma comparação aproximada para um projeto com 500 strings traduzíveis em 5 idiomas:

Os números variam dependendo da contagem de strings e idiomas alvo, mas a diferença de ordem de magnitude é consistente. Para manutenção contínua (traduzir as 20-50 novas strings adicionadas a cada sprint), o custo da IA é essencialmente zero.

Melhores práticas

Comece com --dry-run. Antes da sua primeira execução de tradução real, pré-visualize o que vai acontecer. Isso gera confiança e captura problemas de configuração cedo.

Commite os arquivos .po antes de traduzir. Se algo der errado, git checkout te leva de volta a um estado limpo instantaneamente.

Escreva um TRANSLATING.md desde o primeiro dia. Mesmo um arquivo breve com a descrição do seu projeto e algumas regras de terminologia melhora mensuravelmente a qualidade da tradução.

Adicione check_translations ao CI. Este único passo previne o modo de falha i18n mais comum: strings que foram marcadas para tradução mas nunca foram realmente traduzidas.

Use gpt-4o-mini ou DeepL para eficiência de custo. Reserve modelos premium como GPT-4o ou Claude para projetos onde a precisão importa, como texto de marketing, texto jurídico ou terminologia específica de domínio.

Revise strings críticas. Traduções por IA são boas o suficiente para a maioria dos textos de UI, mas tenha um falante nativo revisando qualquer coisa juridicamente vinculante, crítica para segurança ou voltada ao cliente em contexto de alto risco.

De horas a segundos

O framework i18n do Django é excelente para extrair e compilar traduções. A lacuna sempre foi o passo de tradução em si, o trabalho tedioso e propenso a erros de preencher centenas de valores msgstr em múltiplos idiomas.

O TranslateBot fecha essa lacuna. Instale-o, aponte para um provedor de IA e execute um comando. Novas strings são traduzidas. Strings existentes permanecem intactas. Placeholders permanecem intactos. CI captura qualquer coisa que passe despercebida.

Seus arquivos .po deixam de ser uma tarefa árdua e passam a ser apenas mais uma parte do build.

pip install translatebot-django

Comece em translatebot.dev.