Quick Start

This guide assumes you already have django-modeltranslation set up with translated models.

1. Configure the backend

# settings.py
TRADUIRE = {
    "SOURCE_LANGUAGE": "fr",  # your content language
}

That is enough to start: the default backend is the free Google endpoint, which needs no API key. To use a contractual provider instead:

TRADUIRE = {
    "BACKEND": "django_traduire.backends.deepl.DeepLBackend",
    "SOURCE_LANGUAGE": "fr",
    "BACKEND_OPTIONS": {
        "auth_key": "your-deepl-api-key",
    },
}

If SOURCE_LANGUAGE is omitted, it defaults to your LANGUAGE_CODE.

2. Translate a single instance

from django_traduire import translate_instance

article = Article.objects.get(pk=1)
translate_instance(article)

This reads title_fr, body_fr, etc. and populates title_de, title_en, title_it — only for empty columns.

A field of any length is handled: it is split into requests the provider accepts and glued back (Long texts). A rich-text field keeps its headings, lists and emphasis (Rich text).

3. Batch translate with the management command

# Translate everything
python manage.py traduire

# Translate one model
python manage.py traduire myapp.Article

# One field only, and never more than 100 rows
python manage.py traduire myapp.Article --fields body --limit 100

# Preview without changes
python manage.py traduire --dry-run

4. Add admin actions (optional)

from django_traduire.admin import TraduireMixin
from modeltranslation.admin import TranslationAdmin


@admin.register(Article)
class ArticleAdmin(TraduireMixin, TranslationAdmin):
    pass

Select articles in the admin, then use the "Translate empty fields" action.

5. Enable auto-translate (optional)

TRADUIRE = {
    ...
    "AUTO_TRANSLATE": True,
}

Now every save() fills the empty translation columns automatically. It is convenient for a small site; for long articles or many languages, call translate_instance() from a background task instead — a request that waits on a translation API is a request the user watches spin.