← Blog

Como traduzir um projeto Django: makemessages, arquivos .po e tradução automática

Traduza os arquivos .po do seu projeto Django para inglês, português e francês com python manage.py translate: extrai, traduz, escreve e compila. Com a saída real.

· 2 min de leitura

Traduzir um projeto Django costuma ser assim: makemessages, abrir cada .po, copiar os msgid para um tradutor ou para o ChatGPT, colar os msgstr um a um, torcer para não quebrar nenhum %(name)s e executar compilemessages. E repetir isso com cada texto novo.

Neste guia fazemos tudo com um único comando, python manage.py translate, usando o pacote translate-projects-django. Tudo o que você vê abaixo (terminal e arquivos .po) é a saída real de uma execução em um projeto de teste.

O que você precisa

  • Python 3.8 ou superior e Django 3.2 ou superior.
  • GNU gettext (xgettext e msgfmt), como para qualquer tradução no Django: sudo apt-get install gettext ou brew install gettext.
  • Uma conta gratuita no Translate Projects com um projeto e seu API token (Primeiros passos).
  • A API key do seu provedor de IA (Claude, OpenAI, DeepSeek ou Gemini). Não há planos nem cartão: você paga apenas pelos tokens que usar no seu provedor.

1. Instale o pacote

pip install translate-projects-django

2. Configure o settings.py

import os

INSTALLED_APPS = [
    # ...
    "translate_projects_django",
]

MIDDLEWARE = [
    # ...
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.middleware.locale.LocaleMiddleware",
    "django.middleware.common.CommonMiddleware",
    # ...
]

USE_I18N = True
LANGUAGE_CODE = "es"  # idioma base
LANGUAGES = [
    ("es", "Español"),
    ("en", "English"),
    ("pt-br", "Português (Brasil)"),
    ("fr", "Français"),
]
LOCALE_PATHS = [BASE_DIR / "locale"]
TRANSLATE_PROJECTS_API_KEY = os.environ.get("TRANSLATE_PROJECTS_API_KEY")

Os códigos do Django (pt-br, zh-hans) são convertidos automaticamente para os da API. LANGUAGE_CODE é o seu idioma base e nunca é traduzido.

3. Marque seus textos como sempre

Nada do que você já faz no Django muda: gettext no Python e {% translate %} nos templates.

# views.py (ejemplo)
from django.utils.translation import gettext as _

def home(request):
    message = _("Cerrar sesión")
{# templates/home.html (ejemplo) #}
{% load i18n %}
<h1>{% translate "Bienvenido a tu panel" %}</h1>
<p>{% blocktranslate %}Hola {{ name }}, tienes mensajes nuevos{% endblocktranslate %}</p>

4. Traduza

export TRANSLATE_PROJECTS_API_KEY=tu_token
python manage.py translate

Saída real (6 textos para inglês, português e francês):

[05:19:47 PM] 🎯 Start Generate Translations
              📂 6 texts found in es
[05:19:48 PM] ✅ Sources unchanged, upload skipped
📝 Translating (en)    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
📝 Translating (pt-br) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
📝 Translating (fr)    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
[05:19:50 PM] ⏱ extract 0.0s · upload 0.4s · compile 0.0s · total 2.5s · 7 HTTP requests
                 en: 6 filled, 0 missing, 0 rejected · translate 1.4s · download 0.4s ·
              write 0.0s
                 pt-br: 6 filled, 0 missing, 0 rejected · translate 1.6s · download 0.1s ·
                 fr: 6 filled, 0 missing, 0 rejected · translate 1.8s · download 0.3s ·
              🎉 Translations completed ✅

Dois segundos e meio no total. O comando executa makemessages, traduz até 3 idiomas em paralelo, escreve os .po e termina com compilemessages. Veja como ficou o francês:

# locale/fr/LC_MESSAGES/django.po
#: demo/templates/demo.html:2
msgid "Bienvenido a tu panel"
msgstr "Bienvenue sur votre tableau de bord"

#: demo/templates/demo.html:3
#, python-format
msgid "Hola %(name)s, tienes mensajes nuevos"
msgstr "Bonjour %(name)s, vous avez de nouveaux messages"

#: demo/templates/demo.html:4
msgid "<b>Guardar</b> cambios"
msgstr "<b>Enregistrer</b> les modifications"

#: demo/templates/demo.html:5
#, python-format
msgid "100 %% gratis"
msgstr "100 %% gratuit"

#: demo/views.py:3
msgid "Cerrar sesión"
msgstr "Se déconnecter"

#: demo/views.py:3
msgid "Configuración de la cuenta"
msgstr "Paramètres du compte"

Arquivos que são gerados

locale/
├── en/LC_MESSAGES/django.po    ← y su django.mo
├── pt_BR/LC_MESSAGES/django.po
├── fr/LC_MESSAGES/django.po
└── .translate-projects.json    ← caché

Faça commit dos .po e do .translate-projects.json para que outras máquinas e seu CI pulem os idiomas que já estão atualizados.

Comandos úteis

python manage.py translate --locale en   # solo un idioma
python manage.py translate --force       # descarga todo otra vez
  • Uma segunda execução sem textos novos faz uma única requisição e pula os idiomas completos: o que já está traduzido não gasta tokens.
  • Não edite os .po manualmente: eles são reconstruídos a cada execução. Edite a tradução no painel e execute com --force.
  • Limitação atual: os plurais (ngettext, blocktranslate count) ainda não são traduzidos e permanecem no idioma base.

Erros comuns

  • TRANSLATE_PROJECTS_API_KEY não está definida em settings.py: exporte a variável e leia-a em settings.py.
  • O idioma de origem não é o padrão: LANGUAGE_CODE deve ser o idioma padrão do projeto.
  • MISSING_API_KEY: configure o provedor, o modelo e a key de IA no projeto.
  • CommandError: Can't find msguniq ou xgettext: está faltando o GNU gettext.

O guia completo está em doc.translateprojects.dev. Crie seu projeto grátis e traduza seu projeto Django hoje.