Skip to content

Architecture

How it works

django-traduire sits on top of django-modeltranslation and translation APIs:

Your Django models
       |
django-modeltranslation (creates title_fr, title_de, title_en, ...)
       |
django-traduire (reads source field, translates, writes target fields)
       |
Translation backend (DeepL / Google / OpenAI / custom)

Core flow

  1. Discover fields — queries modeltranslation.translator for registered fields on the model
  2. Read source — reads the source language column (e.g. title_fr)
  3. Check targets — skips target columns that already have content (unless overwrite=True)
  4. Batch by language — groups texts by target language for efficient API usage
  5. Translate — calls the backend's translate_batch() method
  6. Write back — sets translated values on the instance and saves with update_fields

Pluggable backends

All backends implement BaseBackend with a single required method:

def translate_batch(self, texts: list[str], source: str, target: str) -> list[str]:
    ...

This design means:

  • Batch efficiency — one API call per language, not per field
  • Easy to extend — implement one method to add a new translation service
  • Testable — swap in a fake backend for tests

Settings resolution

Setting Default Fallback
SOURCE_LANGUAGE None LANGUAGE_CODE (stripped of region)
TARGET_LANGUAGES None All LANGUAGES except source
BACKEND deepl.DeepLBackend —
AUTO_TRANSLATE False —