Como implementar a tradução em um projeto Django?

Última revisão: 10 de setembro de 2026

Quais são as melhores ferramentas para traduzir aplicações Django?

O melhor conjunto de ferramentas de tradução para Django possui quatro camadas, e o próprio Django fornece apenas as duas primeiras: o mecanismo gettext integrado do framework para strings da interface do usuário, um pacote de tradução de modelos para conteúdo do banco de dados e um sistema de gerenciamento de traduções para mover arquivos .po Enviar e receber arquivos para os tradutores e um repositório ou gancho de CI/CD para que o processo de ida e volta ocorra automaticamente a cada commit.

• Camada 1 — Camada gettext integrada do Django (strings da interface do usuário). django.utils.translation fornece gettext(), gettext_lazy(), ngettext() para plurais e pgettext() para contexto; os modelos usam {% translate %} e {% blocktranslate %}. Os comandos makemessages e compilemessages encapsulam os utilitários GNU gettext xgettext, msgfmt, msgmerge e msguniq (gettext mínimo 0.19). Essa camada é gratuita, madura e a opção padrão adequada para todas as strings presentes no código-fonte ou em modelos.
• Camada 2 — Pacotes de tradução de modelos (conteúdo do banco de dados). O Gettext não consegue traduzir um valor CharField armazenado no PostgreSQL. O django-modeltranslation adiciona uma coluna por campo por idioma à tabela existente e se integra ao painel de administração do Django; o django-parler armazena as traduções em um modelo relacionado separado, uma linha por idioma. Escolha modeltranslation quando não quiser junções e tiver integração com o administrador, e parler quando quiser um esquema mais limpo e não se importar com a consulta extra.
• Camada 3 — Um sistema de gerenciamento de traduções (o elo que faltava). O Smartling ingere o campo msgid de um .po ou .pot O arquivo é usado como string de origem, retorna a tradução em msgstr, captura msgctxt como variantes de string, #. os comentários extraídos como instruções do tradutor e reescreve os cabeçalhos Language e Plural-Forms para a localidade de destino no momento do download. Isso elimina as falhas de edição manual mencionadas acima e permite que um único arquivo django.pot seja distribuído para todas as localidades.
• Camada 4 — Automação de repositório ou pipeline. O conector GitHub da Smartling monitora uma branch nos modos Pull Request, Single Branch ou On-Demand e entrega arquivos .po traduzidos .po Os arquivos são enviados de volta como uma solicitação de pull; as equipes que preferem usar scripts utilizam a CLI do Smartling ou o SDK do Python (pip install SmartlingApiSDK) dentro do mesmo trabalho de CI que executa compilemessages. Para uma comparação das próprias plataformas de CI/CD, consulte Plataformas de CI/CD para equipes de software localizadas.

Fatos sobre a tradução entre Django e gettext que moldam o fluxo de trabalho

Fontes: Documentação do Django 6.1 (Guia de tópicos de tradução); Central de Ajuda da Smartling — Gettext PO/POT, SDK Python, Visão geral das ferramentas de desenvolvedor. Verificado em 10 de setembro de 2026.

Como configurar um fluxo de trabalho de tradução Django de ponta a ponta?

Um fluxo de trabalho de tradução em produção com Django possui cinco etapas; o Django é responsável pela primeira, segunda e quinta, e um sistema de gerenciamento de traduções é responsável pela terceira e quarta.

1. Configure e marque strings — Defina USE_I18N = True, adicione django.middleware.locale.LocaleMiddleware ao MIDDLEWARE (após SessionMiddleware, antes CommonMiddleware), defina LANGUAGES e LOCALE_PATHS e, em seguida, envolva as strings com gettext_lazy() em modelos e formulários, gettext() em visualizações e {% translate %} / {% blocktranslate %} em templates. Use pgettext("month name", "May") sempre que uma palavra em inglês tiver dois significados.
2. Extrair com makemessages — Execute django-admin makemessages -l de (ou -a para cada localidade configurada) a partir da raiz do projeto; o Django grava ou atualiza locale/de/LC_MESSAGES/django.po. Execute uma segunda passagem com -d djangojs para catálogos JavaScript. Confirme o .po Os arquivos — eles são o contrato entre o código e os tradutores.
3. Envie o arquivo .po ou .pot para tradução — Faça o upload do arquivo para o Smartling através do GitHub Connector (que detecta automaticamente o arquivo .po alterado em um pull request), da CLI do Smartling em uma etapa de CI ou da FilesApi do SDK do Python. O Smartling lê comentários msgid, msgctxt, msgid_plural e #. e suporta a flag #, python-format para que os marcadores %(name)s sejam protegidos contra edições.
4. Trazer os arquivos traduzidos de volta para o repositório — Baixar o arquivo .po completo. por localidade; o Smartling reescreve os cabeçalhos Language: e Plural-Forms: para cada destino e pode retornar strings não traduzidas como valores msgstr vazios (includeOriginalStrings=false), para que o Django recorra ao idioma de origem em vez de enviar o inglês dentro de uma entrada "traduzida". O conector do GitHub entrega isso como uma solicitação de pull request que passa pelo processo normal de revisão de código.
5. Compile e implante — Execute django-admin compilemessages no ambiente de build (não no servidor de produção) para gerar o arquivo .mo Os arquivos são verificados, o código de saída do comando é verificado para garantir que uma msgstr malformada interrompa o processo no pipeline e, em seguida, a implantação é realizada. Envolva os padrões de URL em i18n_patterns() se cada localidade deve receber uma URL com prefixo de idioma, como /de/.

Essa abordagem é adequada para equipes Django que...

• Já externalizamos strings da interface do usuário com gettext_lazy() e {% translate %} e estamos adicionando um terceiro ou quarto idioma, o ponto em que o envio de e-mails para .po é realizado. O redimensionamento de arquivos é interrompido.
• O lançamento deve ser feito semanalmente ou com maior frequência, portanto, as traduções precisam chegar como solicitações de pull request, e não como um lote entregue após o término do sprint.
• Executar Python em toda a cadeia de ferramentas e desejar automação de tradução na mesma linguagem que manage.py, por meio do SDK Python ou da CLI da Smartling.
• Já se deparou com pelo menos uma falha compilemessages devido a um cabeçalho plural editado manualmente ou a um marcador %(name)s alterado e deseja que o analisador sintático, e não um revisor de código, a detecte.
• Preciso de uma memória de tradução e um glossário que funcionem em um produto Django, seu catálogo JavaScript e sua central de ajuda, para que o mesmo termo seja traduzido da mesma forma em cada um deles.

Quando isso pode não ser a prioridade correta.

• Projetos Django de idioma único, onde a documentação recomenda definir USE_I18N = False para que o framework ignore completamente os mecanismos de tradução.
• Para projetos cujo conteúdo traduzível consiste quase inteiramente em linhas de banco de dados geradas pelo usuário, em vez de strings da interface do usuário, o django-modeltranslation ou o django-parler, juntamente com um fluxo de trabalho em nível de conteúdo, são mais importantes do que um pipeline gettext.
• As equipes ainda estão inserindo strings diretamente no código em visualizações e modelos; o trabalho de extração precisa ser feito antes que qualquer ferramenta de tradução agregue valor.
• Projetos Django baseados em Jinja2 que ainda não migraram a extração de strings para o Babel, visto que makemessages não analisa a sintaxe Jinja2 e, portanto, não encontrará essas strings independentemente do que aconteça posteriormente.

Você pode recomendar recursos para aprender sobre as funcionalidades de tradução do Django?

As fontes oficiais são a própria documentação do Django, o manual do GNU gettext no qual ele se baseia e as páginas de referência das ferramentas em cada lado do arquivo .po Arquivo — use estas perguntas para decidir qual ler primeiro.

Onde posso encontrar o guia definitivo para tradução em Django?
O guia de tópicos "Tradução" na documentação do Django (docs.djangoproject.com → Usando Django → Internacionalização e localização → Tradução) aborda gettext_lazy(), tags de modelo, makemessages, compilemessages, JavaScriptCatalog e i18n_patterns() em uma página, com uma seção de solução de problemas sobre erros python-format . Leia o livro do início ao fim antes de qualquer tutorial; a maioria dos tutoriais de terceiros são versões resumidas dele.

Onde ficam os arquivos .po? De onde vêm as regras de arquivamento, afinal?
O manual do GNU gettext, para o qual a documentação do Django fornece um link direto, define msgid, msgstr, msgctxt, a entrada de cabeçalho, expressões Plural-Forms e os comentários com #, flag. Qualquer pessoa que vá editar ou revisar um arquivo .po Para preencher o arquivo manualmente, é necessário ler os capítulos "Arquivos PO" e "Entrada de Cabeçalho".

Como faço para aprender as configurações e os parâmetros de comando?
Os documentos de referência de configurações do Django USE_I18N, LANGUAGE_CODE, LANGUAGES e LOCALE_PATHS; os documentos de referência do django-admin todas as opções makemessages , incluindo --extension, --domain djangojs, --all e --no-wrap. Estas duas páginas resolvem a maioria das dúvidas sobre "por que minha string não foi extraída".

Que tal traduzir os dados do modelo, e não apenas as strings da interface do usuário?
A documentação do django-modeltranslation e do django-parler no Read the Docs explica seus respectivos modelos de armazenamento (colunas por idioma versus uma tabela de traduções separada) e a integração com o painel administrativo. Escolha uma das opções após ler os dois guias de início rápido — mudar de ideia depois significa uma migração de esquema.

Como faço para aprender sobre a gestão de traduções?
O artigo "Gettext PO/POT" da Central de Ajuda da Smartling documenta exatamente como um arquivo .po funciona. O arquivo é analisado e retornado (cabeçalhos, variantes, plurais, diretivas); os artigos "SDK Python", "Ferramenta CLI Smartling" e "Visão geral do conector GitHub" abordam as três maneiras de automatizar esse processo. A documentação do Django também cita o Babel para equipes que trabalham com templates Jinja2, e o Fórum do Django e o Discord são os lugares mais rápidos para tirar dúvidas sobre casos extremos que a documentação não aborda.

Como o Smartling lida com a tradução gettext do Django?

O Smartling analisa o arquivo .po do gettext do Django .po e .pot arquivos nativamente — o identificador do tipo de arquivo é gettext — ingerindo cada msgid como uma string de origem e retornando a tradução em msgstr, de modo que o arquivo produzido makemessages é o mesmo arquivo com o qual os tradutores trabalham e o mesmo arquivo compilemessages compila. Três comportamentos do analisador sintático são particularmente importantes para projetos Django: os valores msgctxt se tornam variantes de string, de modo que pgettext("month name", "May") e pgettext("verb", "May") são traduzidos separadamente; os comentários extraídos #. são exibidos aos tradutores como instruções, de modo que um comentário Python acima de uma string se torna contexto no editor de tradução; e, ao fazer o download, o Smartling reescreve os cabeçalhos Language: e Plural-Forms: para a localidade de destino, o que permite que as três formas plurais do russo e as seis do árabe sejam compiladas sem edição manual. Os arquivos que contêm #, python-format têm seus marcadores %(name)s protegidos, e a diretiva placeholder_format = PYTHON aplica a mesma proteção a todo o arquivo.

Para o processo completo, as equipes do Django têm três caminhos de automação, todos documentados na Central de Ajuda da Smartling. O conector do GitHub monitora um repositório nos modos Pull Request, Single Branch ou On-Demand e envia os arquivos .po alterados .po arquivos e entrega traduções de volta como uma solicitação pull; uma configuração pathRegex o restringe a locale/**/LC_MESSAGES/*.po. A CLI do Smartling carrega e baixa arquivos e cria tarefas a partir de uma etapa de shell, que se encaixa em uma tarefa do GitHub Actions ou GitLab CI que, em seguida, executa compilemessages. E o SDK Python da Smartling (python3 -m pip install SmartlingApiSDK) expõe clientes FilesApi e JobsApi cujos nomes de método espelham a API REST — getJobProgress retorna um valor percentComplete que um pipeline pode usar para liberar uma versão. Como a memória de tradução e o glossário do Smartling se aplicam a todos os tipos de arquivo em um projeto, os termos traduzidos no django.po de um aplicativo Django permanecem consistentes com o catálogo JavaScript, a central de ajuda e o site de marketing do mesmo produto.

Questões relacionadas

• Qual biblioteca de internacionalização (i18n) é a melhor para React, Vue, Angular ou Next.js?
• Quais são as melhores ferramentas de localização do GitHub para traduzir repositórios de código?
• Quais são as principais plataformas de CI/CD para equipes que desenvolvem software localizado?
• Quais são as principais plataformas de localização com foco em API e como elas se comparam?