Skip to content

Model Translation

TranslateBot Django integrates with django-modeltranslation to automatically translate database content.

Overview

django-modeltranslation adds language-specific fields to your models. For example, a title field becomes title_en, title_de, title_nl, etc. TranslateBot can automatically populate these translated fields.

Installation

1. Install with modeltranslation support

pip install translatebot-django[modeltranslation]

poetry add translatebot-django[modeltranslation]

uv add translatebot-django[modeltranslation]

2. Configure Django

settings.py
INSTALLED_APPS = [
    'modeltranslation',  # Must be before django.contrib.admin
    'django.contrib.admin',
    # ...
    'translatebot_django',
]

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

3. Register Models for Translation

Create a translation.py file in your app:

myapp/translation.py
from modeltranslation.translator import register, TranslationOptions
from .models import Article, Product

@register(Article)
class ArticleTranslationOptions(TranslationOptions):
    fields = ('title', 'content', 'description')

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

4. Run Migrations

python manage.py makemigrations
python manage.py migrate

This creates the language-specific database columns.

Usage

Translate All Models

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

Translate Specific Models

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

Preview Mode

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

Re-translate Existing Content

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

How It Works

  1. Discovers all models registered with django-modeltranslation
  2. Finds fields that need translation (empty target language fields)
  3. Reads content from the source language field
  4. Translates using the configured AI model
  5. Updates the database using efficient bulk operations
  6. Commits changes atomically (all or nothing)

Example

Model Definition

models.py
from django.db import models

class Article(models.Model):
    title = models.CharField(max_length=200)
    content = models.TextField()
    published = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.title

Translation Registration

translation.py
from modeltranslation.translator import register, TranslationOptions
from .models import Article

@register(Article)
class ArticleTranslationOptions(TranslationOptions):
    fields = ('title', 'content')

Database Schema

After migrations, your database has:

Column Type
title CharField
title_en CharField
title_de CharField
title_nl CharField
content TextField
content_en TextField
content_de TextField
content_nl TextField

Translation Command

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

Output: 

Translating Article model fields to German (de)...
Found 25 articles with untranslated fields
Translating batch 1/3...
Translating batch 2/3...
Translating batch 3/3...
Successfully translated 25 articles

Source Language Detection

TranslateBot intelligently detects the source content:

  1. Checks the base field first (title)
  2. Falls back to the first populated language field (title_en, etc.)
  3. Skips records with no source content

This ensures translations work even when content was entered through language-specific fields.

Combining with PO Translation

You can translate both PO files and model fields in separate commands:

# Translate PO files
python manage.py translate --target-lang nl

# Translate model fields
python manage.py translate --target-lang nl --models

Or translate everything at once by running both:

python manage.py translate --target-lang nl && \
python manage.py translate --target-lang nl --models

Best Practices

Use Dry Run

Always preview with --dry-run before modifying your database.

Backup Your Database

Create a database backup before bulk translations.

Translate in Batches

For large datasets, consider translating specific models at a time.

Atomic Transactions

All translations are applied in a single transaction. If any error occurs, no changes are saved.

Next Steps