Cómo traducir contenido de base de datos en Django con IA

Si has trabajado con el framework de internacionalización (i18n) integrado en Django, sabes que maneja bien las cadenas estáticas. Envolver texto en gettext() o usar la etiqueta de plantilla {% trans %} extrae las cadenas a archivos .po, que los traductores completan. El sistema está probado en batalla y funciona muy bien para código y plantillas.

Pero, ¿qué pasa con el contenido almacenado en tu base de datos?

Nombres de productos, títulos de artículos, descripciones de categorías, respuestas de FAQ, contenido generado por usuarios. Nada de esto vive en tu código fuente. El comando makemessages de Django nunca lo encontrará, y los archivos .po no pueden ayudarte aquí. Si tu aplicación sirve contenido dinámico a usuarios en múltiples idiomas, necesitas una estrategia diferente.

Así es como hacerlo: usa django-modeltranslation para agregar campos traducibles a tus modelos, luego automatiza la traducción con IA usando TranslateBot.

Paquetes de Traducción de Base de Datos en Django

Varios paquetes de terceros resuelven el problema de la traducción de base de datos, cada uno con una arquitectura diferente.

django-modeltranslation

Agrega columnas específicas de idioma directamente a tus tablas existentes. Un campo title se convierte en title_en, title_de, title_fr, y así sucesivamente. Las consultas siguen siendo rápidas porque todo está en la misma tabla. La interfaz de administración muestra todos los idiomas uno al lado del otro.

Ventajas: Sin JOINs, consultas rápidas, acceso transparente mediante descriptores de campo, ecosistema maduro
Desventajas: Cambios de esquema por cada nuevo idioma, tablas más anchas

django-parler

Crea una tabla de traducción separada para cada modelo. La tabla original se mantiene limpia, y las traducciones se almacenan en una tabla relacionada unida mediante clave foránea.

Ventajas: Esquema limpio, fácil agregar idiomas sin migraciones
Desventajas: Requiere JOINs para contenido traducido, patrones de consulta ligeramente más complejos

django-translations

Usa una tabla de traducciones única con una clave foránea genérica que apunta a cualquier modelo. Todas las traducciones de todos los modelos van a una sola tabla.

Ventajas: Cambios de esquema mínimos, funciona con cualquier modelo
Desventajas: Las consultas con clave foránea genérica pueden ser lentas, API menos transparente

Campo JSON Manual

Puedes almacenar traducciones en un JSONField:

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

Ventajas: Sin dependencias extra, flexible
Desventajas: Sin integración con el ORM, sin soporte de admin, todo manual

¿Cuál Deberías Usar?

Para la mayoría de los proyectos, django-modeltranslation es la mejor opción. Es el paquete más maduro, tiene la mejor integración con el admin de Django, y mantiene todos los datos en la misma tabla para consultas rápidas. La contrapartida (tablas más anchas y una migración por cada nuevo idioma) es manejable para la gran mayoría de las aplicaciones. El resto de esta guía usa django-modeltranslation.

Configurando django-modeltranslation Paso a Paso

Paso 1: Instalar el Paquete

TranslateBot incluye django-modeltranslation como dependencia opcional. Instala ambos de una vez:

pip install translatebot-django[modeltranslation]

O si usas uv:

uv add --dev translatebot-django[modeltranslation]

Paso 2: Configurar los Ajustes de Django

Dos cosas importan en settings.py: el orden de las apps y la 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'),
]

La app modeltranslation debe ir antes de django.contrib.admin para que pueda parchear las clases de admin y mostrar los campos de traducción.

Paso 3: Registrar Modelos para Traducción

Crea un archivo translation.py en cada app que tenga modelos traducibles. Para una app de tienda de comercio electrónico:

# 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')

Solo incluye campos que contengan texto legible por humanos. No registres campos como slug, price o sku.

Paso 4: Crear y Ejecutar Migraciones

python manage.py makemigrations
python manage.py migrate

Después de esto, tu tabla shop_product tiene nuevas columnas:

Columna	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 definiste en LANGUAGES obtiene su propia columna para cada campo registrado.

El Problema: Campos de Traducción Vacíos

Ahora tienes el esquema en su lugar, pero cada columna _de, _fr y _nl está vacía. Si tienes 500 productos con 3 campos traducibles y 3 idiomas objetivo, son 4.500 campos vacíos esperando ser llenados.

Traducir manualmente ese contenido no es realista. Incluso con un servicio de traducción profesional, necesitarías exportar los datos, enviarlos, esperar la entrega e importar los resultados de vuelta. Para un equipo pequeño o un desarrollador solitario, esto generalmente significa que la funcionalidad nunca se lanza.

Aquí es donde entra TranslateBot.

Automatizando Traducciones con TranslateBot

El comando de gestión translate de TranslateBot puede llenar todos esos campos vacíos usando IA. Primero configura tu clave API:

# settings.py

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

Luego traduce todos los modelos registrados a un idioma objetivo:

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

Ese único comando encuentra cada modelo registrado con django-modeltranslation, identifica los campos vacíos para el idioma objetivo y los llena con traducciones generadas por IA.

Traducir Modelos Específicos

Si solo quieres traducir productos y no categorías:

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

O múltiples modelos específicos:

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

Vista Previa con Dry Run

Siempre previsualiza antes de escribir en la base de datos:

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

Esto te muestra exactamente qué se traducirá sin modificar ningún registro.

Re-traducir Contenido Existente

Por defecto, TranslateBot omite los campos que ya tienen traducción. Para sobrescribir traducciones existentes (por ejemplo, después de mejorar tu modelo de IA o agregar contexto):

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

Traducir Todos los Idiomas a la Vez

Si omites --target-lang y tienes LANGUAGES definido en tus ajustes, TranslateBot traduce a todos los idiomas configurados:

python manage.py translate --models

Cómo Funciona el Pipeline de Traducción

Esto es lo que sucede cuando ejecutas el comando de traducción.

Descubrimiento. TranslateBot consulta el registro de django-modeltranslation para encontrar todos los modelos registrados y sus campos traducibles.
Detección de origen. Para cada registro, lee el contenido fuente. Primero verifica el campo base (por ejemplo, name), luego recurre al primer campo específico de idioma que esté poblado (por ejemplo, name_en). Los registros sin contenido fuente se omiten.
Agrupación por lotes. Los registros se agrupan en lotes y se envían al proveedor de IA. Esto mantiene las llamadas a la API eficientes y evita alcanzar los límites de tasa.
Traducción. Cada lote se traduce usando el modelo de IA configurado. Puedes usar cualquier proveedor de LLM soportado por LiteLLM (OpenAI, Anthropic, Google, Azure, y muchos otros) o DeepL.
Escrituras atómicas. Todas las actualizaciones de base de datos de una ejecución de traducción se envuelven en una única transacción. Si algo sale mal, como un error de API o una violación de restricción de base de datos, no se guardan datos parciales. Todo o nada.

Ejemplo de Flujo de Trabajo Completo

Aquí hay un ejemplo completo desde la definición del modelo hasta el contenido traducido, usando un modelo Product de comercio electrónico.

Definir el 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 Traducción

# shop/translation.py

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


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

Ejecutar Migraciones

python manage.py makemigrations shop
python manage.py migrate

Agregar Contexto de Traducción (Opcional)

Crea un archivo TRANSLATING.md en la raíz de tu proyecto para darle contexto a la IA sobre el dominio de tu producto:

# 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

Traducir

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

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

Salida:

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 en el Admin

Abre el admin de Django y ve a cualquier producto. Verás los campos de traducción poblados:

Name [de]: Ultraleichte Trail-Laufschuhe
Description [de]: Diese leichten Trail-Laufschuhe bieten hervorragenden Grip...
Short description [de]: Leicht, schnell und griffig auf jedem Untergrund.

Repite para cada idioma objetivo:

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

O traduce todos los idiomas a la vez:

python manage.py translate --models Product

Mejores Prácticas

Haz una copia de seguridad de tu base de datos antes de ejecutar traducciones masivas en producción. TranslateBot usa transacciones atómicas, por lo que una ejecución fallida no dejará datos parciales. Pero tener una copia de seguridad te da una forma de revertir si la calidad de la traducción no es la esperada.

# PostgreSQL example
pg_dump mydb > backup_before_translation.sql

Usa dry run primero. Siempre ejecuta con --dry-run antes de aplicar traducciones a un nuevo modelo o idioma. Revisa la salida para asegurarte de que el contenido fuente se detecta correctamente y las traducciones lucen razonables.

Traduce un modelo a la vez para bases de datos grandes. Esto facilita revisar los resultados y re-ejecutar modelos específicos si es necesario.

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

Agrega contexto de traducción. Un archivo TRANSLATING.md con terminología específica del dominio y directrices de tono mejora significativamente la calidad de la traducción. Esto es especialmente importante para campos especializados como medicina, derecho o productos técnicos.

Mantén tu idioma fuente poblado. TranslateBot lee del campo base o del campo del idioma fuente. Asegúrate de que tu flujo de trabajo de entrada de datos siempre pueble el idioma fuente. Campos fuente vacíos significan traducciones vacías.

Combina con traducción de archivos PO para cobertura completa. Traduce tanto las cadenas de tu código como el contenido de la base de datos:

# 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

De esta manera, cada cadena que ven tus usuarios, ya sea que provenga de una plantilla o de la base de datos, está traducida.

Próximos Pasos

Lee la referencia completa de comandos para todas las opciones disponibles
Configura la integración CI para verificar automáticamente las traducciones faltantes
Explora los modelos de IA soportados para encontrar el mejor equilibrio entre calidad y costo para tu proyecto