Python API¶

TranslateBot exposes a public Python API so you can trigger translations from anywhere in your code - Celery tasks, custom management commands, scripts, Django views, or any other Python context.

`translate()`¶

from translatebot_django import translate

The translate() function provides the same functionality as the translate management command with a clean keyword-argument interface.

Parameters¶

Parameter	Type	Default	Description
`target_langs`	`str` or `list[str]`	`None`	Language code(s) to translate to (e.g. `"nl"` or `["nl", "de"]`). When omitted, translates to all languages in `settings.LANGUAGES`.
`dry_run`	`bool`	`False`	Preview what would be translated without saving changes.
`overwrite`	`bool`	`False`	Re-translate entries that already have translations.
`apps`	`str` or `list[str]`	`None`	Restrict PO file translation to specific app(s). Cannot be combined with `models`.
`models`	`bool` or `list[str]`	`None`	`None`: translate PO files only. `True`: translate all registered model fields. List of names: translate specific models.
`model`	`str`	`None`	LLM model name to use for this call, overriding `settings.TRANSLATEBOT_MODEL` (e.g. `"gpt-4o"` or `"claude-3-5-sonnet-20241022"`). Not supported with the DeepL provider — passing it with DeepL raises `CommandError`.

Return value¶

translate() returns a TranslateResult dataclass with statistics about what was translated:

from translatebot_django import TranslateResult

Attribute	Type	Description
`strings_found`	`int`	Number of translatable strings found in PO files.
`strings_translated`	`int`	Number of PO strings that were translated (or would be in dry-run mode).
`po_files`	`int`	Number of PO files processed.
`model_fields_found`	`int`	Number of translatable model fields found.
`model_fields_translated`	`int`	Number of model fields that were translated (or would be in dry-run mode).
`target_langs`	`list[str]`	Language codes that were translated to.
`dry_run`	`bool`	Whether the translation was a dry run.

Exceptions¶

Raises django.core.management.base.CommandError on configuration or translation errors (missing API key, unknown language, API failures, etc.).

Examples¶

Basic usage¶

from translatebot_django import translate

# Translate PO files to all configured languages
result = translate()
print(f"Translated {result.strings_translated} of {result.strings_found} strings")

# Translate to specific languages
result = translate(target_langs=["nl", "de", "fr"])

# Translate a single language
result = translate(target_langs="nl")

Model translation¶

# Translate all registered django-modeltranslation fields
result = translate(models=True)
print(f"Translated {result.model_fields_translated} model fields")

# Translate specific models only
translate(target_langs="fr", models=["Article", "Product"])

Preview and overwrite¶

# Preview what would be translated
result = translate(dry_run=True)
print(f"Would translate {result.strings_found} strings across {result.po_files} files")

# Re-translate everything (overwrite existing translations)
translate(target_langs="de", overwrite=True)

App-specific translation¶

# Translate PO files for a specific app
translate(target_langs="nl", apps="blog")

# Translate multiple apps
translate(target_langs="nl", apps=["blog", "shop"])

Override the LLM model per call¶

Use a different model for specific calls without mutating Django settings:

# Use a higher-quality model for a specific hard language
translate(target_langs="ja", model="gpt-4o")

# Use the default (cheap) model for everything else
translate(target_langs=["nl", "de", "fr"])

This is useful for A/B testing translation quality across models, or routing languages with subtle grammar (e.g. Japanese, Finnish) to stronger models while keeping the default cheap for straightforward pairs.

Not supported with DeepL

Passing model= with the DeepL provider raises CommandError — DeepL has no model concept.

Celery task¶

from celery import shared_task
from translatebot_django import translate

@shared_task
def translate_nightly():
    """Run translations as a background task."""
    translate()

Schedule it with Celery Beat:

# settings.py
CELERY_BEAT_SCHEDULE = {
    "nightly-translations": {
        "task": "myapp.tasks.translate_nightly",
        "schedule": crontab(hour=2, minute=0),  # Run at 2 AM
    },
}

Django Q / Huey / APScheduler¶

The function works with any task runner:

Django QHuey

from django_q.tasks import schedule

schedule(
    "translatebot_django.translate",
    schedule_type="D",  # Daily
)

from huey import crontab
from huey.contrib.djhuey import periodic_task
from translatebot_django import translate

@periodic_task(crontab(hour=2, minute=0))
def translate_nightly():
    translate()

Cron job¶

If you prefer cron over a task queue, the management command is the simplest option:

# crontab -e
0 2 * * * cd /path/to/project && python manage.py translate

Error handling¶

from django.core.management.base import CommandError
from translatebot_django import translate

try:
    translate(target_langs="nl")
except CommandError as e:
    logger.error("Translation failed: %s", e)