Voltar ao blog

Como Traduzir Conteúdo de Banco de Dados Django com IA

2026-02-18 9 min de leitura
Como Traduzir Conteúdo de Banco de Dados Django com IA

Se você já trabalhou com o framework de internacionalização (i18n) integrado do Django, sabe que ele lida bem com strings estáticas. Envolver texto em gettext() ou usar a tag de template {% trans %} extrai as strings para arquivos .po, que os tradutores preenchem. O sistema é testado em batalha e funciona muito bem para código e templates.

Mas e o conteúdo armazenado no seu banco de dados?

Nomes de produtos, títulos de artigos, descrições de categorias, respostas de FAQ, conteúdo gerado pelo usuário. Nada disso está no seu código-fonte. O comando makemessages do Django nunca vai encontrá-lo, e os arquivos .po não podem ajudar aqui. Se sua aplicação serve conteúdo dinâmico para usuários em vários idiomas, você precisa de uma estratégia diferente.

Veja como fazer: use django-modeltranslation para adicionar campos traduzíveis aos seus modelos, e depois automatize a tradução com IA usando TranslateBot.

Pacotes de Tradução de Banco de Dados do Django

Vários pacotes de terceiros resolvem o problema da tradução de banco de dados, cada um com uma arquitetura diferente.

django-modeltranslation

Adiciona colunas específicas de idioma diretamente nas suas tabelas existentes. Um campo title se torna title_en, title_de, title_fr, e assim por diante. As consultas continuam rápidas porque tudo está na mesma tabela. A interface de administração mostra todos os idiomas lado a lado.

django-parler

Cria uma tabela de tradução separada para cada modelo. A tabela original permanece limpa, e as traduções são armazenadas em uma tabela relacionada unida por chave estrangeira.

django-translations

Usa uma única tabela de traduções com uma chave estrangeira genérica apontando para qualquer modelo. Todas as traduções de todos os modelos vão para uma tabela.

Campo JSON Manual

Você pode armazenar traduções em um JSONField:

class Product(models.Model):
    name_translations = models.JSONField(default=dict)
    # {"en": "Running Shoes", "de": "Laufschuhe", "fr": "Chaussures de course"}

Qual Você Deve Usar?

Para a maioria dos projetos, django-modeltranslation é a melhor escolha. É o pacote mais maduro, tem a melhor integração com o admin do Django, e mantém todos os dados na mesma tabela para consultas rápidas. A contrapartida (tabelas mais largas e uma migração por novo idioma) é gerenciável para a grande maioria das aplicações. O restante deste guia usa django-modeltranslation.

Configurando django-modeltranslation Passo a Passo

Passo 1: Instalar o Pacote

TranslateBot inclui django-modeltranslation como dependência opcional. Instale ambos de uma vez:

pip install translatebot-django[modeltranslation]

Ou se você usa uv:

uv add --dev translatebot-django[modeltranslation]

Passo 2: Configurar as Definições do Django

Duas coisas importam no settings.py: a ordem dos apps e a lista de idiomas.

# settings.py

INSTALLED_APPS = [
    'modeltranslation',          # Must be BEFORE django.contrib.admin
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    # Your apps
    'shop',
    'translatebot_django',
]

LANGUAGE_CODE = 'en'

LANGUAGES = [
    ('en', 'English'),
    ('de', 'German'),
    ('fr', 'French'),
    ('nl', 'Dutch'),
]

O app modeltranslation deve vir antes de django.contrib.admin para que possa aplicar patches nas classes admin para mostrar os campos de tradução.

Passo 3: Registrar Modelos para Tradução

Crie um arquivo translation.py em cada app que tenha modelos traduzíveis. Para um app de loja de e-commerce:

# shop/translation.py

from modeltranslation.translator import register, TranslationOptions
from .models import Product, Category


@register(Product)
class ProductTranslationOptions(TranslationOptions):
    fields = ('name', 'description', 'short_description')


@register(Category)
class CategoryTranslationOptions(TranslationOptions):
    fields = ('name', 'description')

Inclua apenas campos que contenham texto legível por humanos. Não registre campos como slug, price ou sku.

Passo 4: Criar e Executar Migrações

python manage.py makemigrations
python manage.py migrate

Depois disso, sua tabela shop_product tem novas colunas:

Coluna Tipo
name varchar(200)
name_en varchar(200)
name_de varchar(200)
name_fr varchar(200)
name_nl varchar(200)
description text
description_en text
description_de text
description_fr text
description_nl text
short_description text
short_description_en text
short_description_de text
short_description_fr text
short_description_nl text

Cada idioma que você definiu em LANGUAGES recebe sua própria coluna para cada campo registrado.

O Problema: Campos de Tradução Vazios

Agora você tem o esquema pronto, mas cada coluna _de, _fr e _nl está vazia. Se você tem 500 produtos com 3 campos traduzíveis e 3 idiomas-alvo, são 4.500 campos vazios esperando para serem preenchidos.

Traduzir manualmente esse conteúdo não é realista. Mesmo com um serviço profissional de tradução, você precisaria exportar os dados, enviá-los, esperar pela entrega e importar os resultados de volta. Para uma equipe pequena ou desenvolvedor solo, isso geralmente significa que a funcionalidade nunca é lançada.

É aqui que o TranslateBot entra.

Automatizando Traduções com TranslateBot

O comando de gerenciamento translate do TranslateBot pode preencher todos esses campos vazios usando IA. Configure sua chave API primeiro:

# settings.py

TRANSLATEBOT_API_KEY = os.getenv("OPENAI_API_KEY")
TRANSLATEBOT_MODEL = "gpt-4o-mini"  # Fast and cost-effective

Depois traduza todos os modelos registrados para um idioma-alvo:

python manage.py translate --target-lang de --models

Esse único comando encontra cada modelo registrado com django-modeltranslation, identifica campos vazios para o idioma-alvo e os preenche com traduções geradas por IA.

Traduzir Modelos Específicos

Se você só quer traduzir produtos e não categorias:

python manage.py translate --target-lang de --models Product

Ou vários modelos específicos:

python manage.py translate --target-lang de --models Product Category

Visualizar com Dry Run

Sempre visualize antes de escrever no banco de dados:

python manage.py translate --target-lang de --models --dry-run

Isso mostra exatamente o que será traduzido sem modificar nenhum registro.

Re-traduzir Conteúdo Existente

Por padrão, TranslateBot pula campos que já têm tradução. Para sobrescrever traduções existentes (por exemplo, depois de melhorar seu modelo de IA ou adicionar contexto):

python manage.py translate --target-lang de --models --overwrite

Traduzir Todos os Idiomas de Uma Vez

Se você omitir --target-lang e tiver LANGUAGES definido nas suas configurações, TranslateBot traduz para todos os idiomas configurados:

python manage.py translate --models

Como o Pipeline de Tradução Funciona

Aqui está o que acontece quando você executa o comando de tradução.

  1. Descoberta. TranslateBot consulta o registro do django-modeltranslation para encontrar todos os modelos registrados e seus campos traduzíveis.

  2. Detecção de origem. Para cada registro, ele lê o conteúdo fonte. Verifica primeiro o campo base (por exemplo, name), depois recorre ao primeiro campo específico de idioma que esteja preenchido (por exemplo, name_en). Registros sem conteúdo fonte são pulados.

  3. Agrupamento em lotes. Os registros são agrupados em lotes e enviados ao provedor de IA. Isso mantém as chamadas de API eficientes e evita atingir limites de taxa.

  4. Tradução. Cada lote é traduzido usando o modelo de IA configurado. Você pode usar qualquer provedor LLM suportado pelo LiteLLM (OpenAI, Anthropic, Google, Azure, e muitos outros) ou DeepL.

  5. Escritas atômicas. Todas as atualizações de banco de dados para uma execução de tradução são envolvidas em uma única transação. Se algo der errado, como um erro de API ou violação de restrição do banco de dados, nenhum dado parcial é salvo. Tudo ou nada.

Exemplo Completo de Fluxo de Trabalho

Aqui está um exemplo completo da definição do modelo ao conteúdo traduzido, usando um modelo Product de e-commerce.

Definir o Modelo

# shop/models.py

from django.db import models


class Product(models.Model):
    name = models.CharField(max_length=200)
    description = models.TextField()
    short_description = models.CharField(max_length=500, blank=True)
    price = models.DecimalField(max_digits=10, decimal_places=2)
    sku = models.CharField(max_length=50, unique=True)
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.name

Registrar para Tradução

# shop/translation.py

from modeltranslation.translator import register, TranslationOptions
from .models import Product


@register(Product)
class ProductTranslationOptions(TranslationOptions):
    fields = ('name', 'description', 'short_description')

Executar Migrações

python manage.py makemigrations shop
python manage.py migrate

Adicionar Contexto de Tradução (Opcional)

Crie um arquivo TRANSLATING.md na raiz do seu projeto para dar contexto à IA sobre o domínio do seu produto:

# Translation Context

## About This Project
E-commerce store for outdoor sports equipment.

## Terminology
- "trail runners" refers to trail running shoes, not people
- Keep brand names (Nike, Salomon, Arc'teryx) untranslated
- "Gore-Tex" is a brand name, do not translate

## Tone
- Use informal "du" form in German
- Product descriptions should sound enthusiastic but not exaggerated

Traduzir

# Preview first
python manage.py translate --target-lang de --models Product --dry-run

# Apply translations
python manage.py translate --target-lang de --models Product

Saída:

Translating Product model fields to German (de)...
Found 142 products with untranslated fields
Translating batch 1/15...
Translating batch 2/15...
...
Translating batch 15/15...
Successfully translated 142 products

Verificar no Admin

Abra o admin do Django e vá para qualquer produto. Você verá os campos de tradução preenchidos:

Repita para cada idioma-alvo:

python manage.py translate --target-lang fr --models Product
python manage.py translate --target-lang nl --models Product

Ou traduza todos os idiomas de uma vez:

python manage.py translate --models Product

Boas Práticas

Faça backup do seu banco de dados antes de executar traduções em massa na produção. TranslateBot usa transações atômicas, então uma execução falhada não deixará dados parciais. Mas ter um backup dá a você uma forma de reverter se a qualidade da tradução não for a esperada.

# PostgreSQL example
pg_dump mydb > backup_before_translation.sql

Use dry run primeiro. Sempre execute com --dry-run antes de aplicar traduções a um novo modelo ou idioma. Revise a saída para garantir que o conteúdo fonte é detectado corretamente e as traduções parecem razoáveis.

Traduza um modelo de cada vez para bancos de dados grandes. Isso facilita a revisão dos resultados e a re-execução de modelos específicos se necessário.

python manage.py translate --target-lang de --models Product
python manage.py translate --target-lang de --models Category
python manage.py translate --target-lang de --models Article

Adicione contexto de tradução. Um arquivo TRANSLATING.md com terminologia específica do domínio e diretrizes de tom melhora significativamente a qualidade da tradução. Isso é especialmente importante para campos especializados como medicina, direito ou produtos técnicos.

Mantenha seu idioma fonte preenchido. TranslateBot lê do campo base ou do campo do idioma fonte. Certifique-se de que seu fluxo de trabalho de entrada de dados sempre preencha o idioma fonte. Campos fonte vazios significam traduções vazias.

Combine com tradução de arquivos PO para cobertura completa. Traduza tanto as strings do seu código quanto o conteúdo do banco de dados:

# Static strings in code and templates
python manage.py makemessages -l de -l fr -l nl
python manage.py translate
python manage.py compilemessages

# Dynamic content in the database
python manage.py translate --models

Dessa forma, cada string que seus usuários veem, seja ela vinda de um template ou do banco de dados, está traduzida.

Próximos Passos

Pare de editar arquivos .po manualmente

TranslateBot automatiza traduções Django com IA. Um comando, todos os seus idiomas, centavos por tradução.

Começar Leia a Documentação