Django

O pacote translate-projects-django adiciona o comando python manage.py translate: extrai seus textos, os traduz para cada idioma de settings.LANGUAGES, grava os arquivos .po e os compila.

Requisitos

• Python 3.8 ou superior e Django 3.2 ou superior.
• GNU gettext (xgettext e msgfmt), igual a qualquer tradução no Django. No Windows, use gettext para Windows.
• Um projeto e um API token do Translate Projects. Veja Primeiros passos.

Instalar gettext

# Debian / Ubuntu
sudo apt-get install gettext
# macOS
brew install gettext
# Docker
RUN apt-get update && apt-get install -y gettext

1. Instale o pacote

Terminal

pip install translate-projects-django

2. Configure settings.py

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: o idioma padrão do projeto

LANGUAGES = [
    ("es", "Español"),
    ("en", "English"),
    ("pt-br", "Português (Brasil)"),
    ("fr", "Français"),
]

LOCALE_PATHS = [BASE_DIR / "locale"]  # É usado o primeiro caminho

TRANSLATE_PROJECTS_API_KEY = os.environ.get("TRANSLATE_PROJECTS_API_KEY")

# Opcional: pastas que o makemessages ignora
TRANSLATE_PROJECTS_EXCLUDE_DIRS = ["venv/*", "node_modules/*"]

Ajuste	Obrigatório	Descrição
TRANSLATE_PROJECTS_API_KEY	Sim	Token de API do projeto. Leia-o de uma variável de ambiente.
LANGUAGE_CODE	Sim	Idioma base. Nunca é traduzido.
LANGUAGES	Sim	Idiomas de destino, com os códigos do Django (pt-br, zh-hans); são convertidos automaticamente para os da API (pt-BR, zh-Hans).
LOCALE_PATHS	Sim	Onde os arquivos .po são gravados (o primeiro caminho).
TRANSLATE_PROJECTS_EXCLUDE_DIRS	Não	É passado para makemessages --ignore.

3. Marque seus textos

Use as ferramentas padrão do Django:

views.py

from django.utils.translation import gettext as _

def home(request):
    message = _("Bienvenido a mi sitio")

templates/home.html

{% load i18n %}
<html lang="{{ LANGUAGE_CODE }}">
  <h1>{% translate "Hola mundo" %}</h1>
</html>

4. Traduza

Terminal

export TRANSLATE_PROJECTS_API_KEY=tu_token
python manage.py translate               # Todos os idiomas de LANGUAGES
python manage.py translate --locale en   # Apenas um idioma
python manage.py translate --force       # Descargar todo de nuevo

El idioma de --locale debe estar en LANGUAGES y ser distinto de LANGUAGE_CODE. Con --locale fr --force solo se vuelve a traducir ese idioma.

Arquivos que são gerados

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

El comando ejecuta makemessages para el idioma base, traduce hasta 3 idiomas en paralelo, escribe los .po (pt-br se convierte en pt_BR) y termina con compilemessages. Las traducciones que cambian un placeholder (%(name)s, %s, {name}) se descartan para que compilemessages nunca falle.

• Cada .po traducido se reconstruye desde el .po del idioma base cada vez que se traduce ese idioma, así que las ediciones a mano se pierden. Edita las traducciones en el panel y ejecuta con --force.
• Haz commit de los .po y de .translate-projects.json para que otras máquinas y tu CI salten los idiomas que ya están al día. Los .mo puedes subirlos o generarlos en el despliegue con compilemessages.
• Los textos en plural (ngettext, blocktranslate count) todavía no se traducen: quedan en el idioma base.

Cache e --force

Una segunda ejecución sin textos nuevos hace una sola petición y salta los idiomas que ya están completos (se guarda en locale/.translate-projects.json). Usa --force para descargar todo de nuevo, por ejemplo después de editar traducciones en el panel. Más detalles en Caché y errores.

Erros comuns

• TRANSLATE_PROJECTS_API_KEY is not set in settings.py: exporte a variável e leia-a em settings.py.
• Token inválido (Token no válido): copie novamente o token do projeto. Os arquivos .po existentes não são alterados.
• O idioma de origem não é o padrão: LANGUAGE_CODE deve ser o idioma padrão do projeto.
• Falta a key de IA (MISSING_API_KEY): configure o provedor, o modelo e a chave no projeto; os textos que faltam são tentados novamente na próxima execução.
• Tradução parcial, erros 5xx ou de rede: se reintenta automáticamente y los idiomas incompletos se vuelven a pedir en la siguiente ejecución.
• CommandError: Can't find msguniq o xgettext: falta GNU gettext; instálalo como se indica en Requisitos.

Grátis

🚀 Automatize suas traduções de graça

Translate Projects é gratuito. Você cria seu projeto, conecta a chave do seu provedor de IA e paga apenas a ele pelo que gastar.

• Sem planos nem cartão de crédito: Todos os recursos estão disponíveis desde o primeiro dia.
• Use sua própria IA: Claude, OpenAI, DeepSeek ou Gemini. Sua chave é armazenada criptografada.
• Rede de traduções compartilhada: Se um texto já foi traduzido, você o recebe instantaneamente sem gastar sua chave.
• Painel de administração: Revise e edite todas as suas traduções em um único lugar.

Criar conta grátis →

Suporte

Estamos aqui para ajudar você

Se você tiver alguma dúvida, precisar de ajuda ou quiser contribuir, não hesite em entrar em contato comigo. Estou à sua disposição para apoiá-lo no que precisar.

• Site: neiderruiz.com
• GitHub: @neiderruiz
• Twitter: @neiderruiz
• YouTube: Neider Ruiz

Apoie o Projeto

Se este projeto foi útil para você, convido você a me pagar um café. Seu apoio me ajuda a continuar melhorando e criando conteúdo de valor. Obrigado por estar aqui! ☕