Translator API

django_traduire.translator

Core translation logic for django-modeltranslation fields.

translate_instance(instance, source_language=None, target_languages=None, overwrite=False)

Translate all modeltranslation fields on a model instance.

Parameters:

Name	Type	Description	Default
instance		A Django model instance with modeltranslation fields.	required
source_language		Source language code (e.g. "fr"). Defaults to TRADUIRE["SOURCE_LANGUAGE"] or LANGUAGE_CODE.	None
target_languages		List of target language codes. Defaults to TRADUIRE["TARGET_LANGUAGES"] or all other LANGUAGES.	None
overwrite		If True, overwrite existing translations. Default False.	False

Returns:

Name	Type	Description
dict		Mapping of {field_lang: translated_text} for every field that was translated.

Source code in src/django_traduire/translator.py

def translate_instance(instance, source_language=None, target_languages=None, overwrite=False):
    """Translate all modeltranslation fields on a model instance.

    Args:
        instance: A Django model instance with modeltranslation fields.
        source_language: Source language code (e.g. ``"fr"``).
            Defaults to ``TRADUIRE["SOURCE_LANGUAGE"]`` or ``LANGUAGE_CODE``.
        target_languages: List of target language codes.
            Defaults to ``TRADUIRE["TARGET_LANGUAGES"]`` or all other LANGUAGES.
        overwrite: If True, overwrite existing translations. Default False.

    Returns:
        dict: Mapping of ``{field_lang: translated_text}`` for every field that was translated.
    """
    src = source_language or get_source_language()
    targets = target_languages or get_target_languages()
    fields = get_translation_fields(instance.__class__)
    backend = get_backend()

    translated = {}
    texts_to_translate = []

    for field in fields:
        src_field = build_localized_fieldname(field, src)
        src_value = getattr(instance, src_field, None)
        if not src_value:
            continue

        for lang in targets:
            if lang == src:
                continue
            target_field = build_localized_fieldname(field, lang)
            current_value = getattr(instance, target_field, None)
            if current_value and not overwrite:
                continue
            texts_to_translate.append((field, lang, target_field, src_value))

    if not texts_to_translate:
        return translated

    # Group by target language for batch efficiency
    by_lang = {}
    for field, lang, target_field, src_value in texts_to_translate:
        by_lang.setdefault(lang, []).append((field, target_field, src_value))

    for lang, items in by_lang.items():
        texts = [src_value for _, _, src_value in items]
        try:
            results = backend.translate_batch(texts, source=src, target=lang)
        except Exception:
            logger.exception("Translation failed for %s → %s", src, lang)
            continue

        for (field, target_field, _), result in zip(items, results):
            if result:
                setattr(instance, target_field, result)
                translated[target_field] = result

    if translated:
        update_fields = list(translated.keys())
        instance.save(update_fields=update_fields)

    return translated

translate_queryset(queryset, source_language=None, target_languages=None, overwrite=False)

Translate all instances in a queryset.

Parameters:

Name	Type	Description	Default
queryset		A Django queryset.	required
source_language		Source language code.	None
target_languages		List of target language codes.	None
overwrite		If True, overwrite existing translations.	False

Returns:

Name	Type	Description
int		Number of instances translated.

Source code in src/django_traduire/translator.py

def translate_queryset(queryset, source_language=None, target_languages=None, overwrite=False):
    """Translate all instances in a queryset.

    Args:
        queryset: A Django queryset.
        source_language: Source language code.
        target_languages: List of target language codes.
        overwrite: If True, overwrite existing translations.

    Returns:
        int: Number of instances translated.
    """
    count = 0
    for instance in queryset.iterator():
        result = translate_instance(
            instance,
            source_language=source_language,
            target_languages=target_languages,
            overwrite=overwrite,
        )
        if result:
            count += 1
    return count

get_backend()

Instantiate and cache the translation backend.

Source code in src/django_traduire/translator.py

def get_backend():
    """Instantiate and cache the translation backend."""
    global _backend_instance
    if _backend_instance is None:
        path = get_setting("BACKEND")
        module_path, class_name = path.rsplit(".", 1)
        module = importlib.import_module(module_path)
        cls = getattr(module, class_name)
        options = get_setting("BACKEND_OPTIONS")
        _backend_instance = cls(**options)
    return _backend_instance

get_translation_fields(model)

Return the list of field names registered with modeltranslation for a model.

Source code in src/django_traduire/translator.py

def get_translation_fields(model):
    """Return the list of field names registered with modeltranslation for a model."""
    try:
        opts = mt_translator.get_options_for_model(model)
    except Exception:
        return []
    return list(opts.fields)