Skip to content

Settings

All settings are namespaced under the TRADUIRE dictionary in your Django settings. An unknown key raises ConfigurationError the first time it is read, rather than being ignored.

Reference

TRADUIRE = {
    # Dotted path to the translation backend class.
    "BACKEND": "django_traduire.backends.google_free.GoogleFreeBackend",
    # Source language code. Defaults to LANGUAGE_CODE.
    "SOURCE_LANGUAGE": "fr",
    # List of target language codes. Defaults to all LANGUAGES except source.
    "TARGET_LANGUAGES": None,
    # Auto-translate on model save. Default False.
    "AUTO_TRANSLATE": False,
    # How rich-text fields are recognised: "auto", "always" or "never".
    "HTML_MODE": "auto",
    # Fields to treat as rich text, per model label.
    "HTML_FIELDS": {"blog.Article": ["body"]},
    # Translate alt, title, placeholder and aria-label too.
    "TRANSLATE_ATTRIBUTES": True,
    # Characters per provider request. None = the backend's own budget.
    "MAX_CHARS": None,
    # What to do when a translation is longer than its column:
    # "truncate", "skip" or "error".
    "ON_TOO_LONG": "truncate",
    # Log a provider failure and carry on (True), or raise BackendError (False).
    "FAIL_SILENTLY": True,
    # Keyword arguments passed to the backend constructor.
    "BACKEND_OPTIONS": {},
}

BACKEND

Dotted Python path to a class that extends django_traduire.backends.base.BaseBackend.

Built-in backends:

  • django_traduire.backends.google_free.GoogleFreeBackend (default, no key)
  • django_traduire.backends.deepl.DeepLBackend
  • django_traduire.backends.google.GoogleBackend
  • django_traduire.backends.openai.OpenAIBackend

SOURCE_LANGUAGE

The language code of your content. If None, defaults to settings.LANGUAGE_CODE (with any region suffix stripped: "en-us" becomes "en").

TARGET_LANGUAGES

A list of language codes to translate into. If None, uses all codes from settings.LANGUAGES except the source.

AUTO_TRANSLATE

When True, connects a post_save signal to every modeltranslation-registered model, filling the empty columns after each save. Off by default; a provider failure is logged and never breaks the save. See Auto-translate.

HTML_MODE

  • "auto" (default) — a field is rich text if it is listed in HTML_FIELDS, if its field class says so, or if its value carries markup.
  • "always" — every field is treated as rich text.
  • "never" — no field is; markup is translated as plain text.

See Rich text.

HTML_FIELDS

A dict mapping "app_label.ModelName" to a list of field names to treat as rich text, whatever the field class or the content looks like.

TRANSLATE_ATTRIBUTES

True (default) also translates the attributes a reader sees: title, alt, placeholder, aria-label, aria-description, <option label>, <th abbr> and <table summary>. Only the value is rewritten; href, src, class, id and everything else are never touched. Set it to False to leave every attribute alone. See Rich text.

MAX_CHARS

Characters allowed in one provider request, overriding the backend's own budget. Lower it when a provider throttles you. See Long texts.

ON_TOO_LONG

What happens when a translation is longer than the target column's max_length — a translation into German routinely is:

  • "truncate" (default) — cut on a word boundary, log a warning
  • "skip" — leave the column empty, log a warning
  • "error" — raise TraduireError

FAIL_SILENTLY

True (default) logs a provider failure on the django_traduire logger and leaves the columns as they were, so a batch run finishes. False raises BackendError, which is what you want in a test or a one-off script.

BACKEND_OPTIONS

A dictionary of keyword arguments passed to the backend's __init__. Each backend has its own options — see Backends.