Command Reference¶
Complete reference for TranslateBot's management commands.
translate¶
Synopsis¶
Options¶
--target-lang¶
Target language code for translation. Repeat it to translate to several languages in one run.
python manage.py translate --target-lang nl
python manage.py translate --target-lang nl --target-lang de
Note
Required unless LANGUAGES is defined in Django settings. When LANGUAGES is set, omitting this option translates to all configured languages, automatically excluding the source language (LANGUAGE_CODE).
--dry-run¶
Preview translations without saving changes.
Lists the strings that would be translated (for --models, the number of fields per model), without calling the translation API or modifying any files or database records. No translations are generated, so a dry run is free.
--overwrite¶
Re-translate entries that already have translations.
By default, only empty and fuzzy entries are translated. Use this flag to replace existing translations.
Warning
Existing translations will be lost. Consider using --dry-run first.
--app¶
Only translate .po files for the specified Django app(s). Can be used multiple times to include multiple apps.
# Translate only the blog app
python manage.py translate --target-lang nl --app blog
# Translate multiple apps
python manage.py translate --target-lang nl --app blog --app shop
Warning
Cannot be combined with --models. The --app flag only filters .po file translation.
--llm-model¶
Override settings.TRANSLATEBOT_MODEL for this run only. Accepts any model name supported by LiteLLM.
# Use GPT-6 Sol for one run instead of the configured default
python manage.py translate --target-lang ja --llm-model gpt-6-sol
# Use Claude Sonnet for a specific language
python manage.py translate --target-lang nl --llm-model claude-sonnet-5
Note
Only supported with the litellm provider. Passing --llm-model with TRANSLATEBOT_PROVIDER = "deepl" raises an error.
--models¶
Translate database model fields instead of PO files. To translate both, run the command twice, once with and once without --models.
# Translate all registered models
python manage.py translate --target-lang nl --models
# Translate specific models
python manage.py translate --target-lang nl --models Article Product
# Use app_label.ModelName when two apps have a model with the same name
python manage.py translate --target-lang nl --models blog.Article
Note
Only available when django-modeltranslation is installed and configured.
Usage Examples¶
Basic Translation¶
# Translate to Dutch
python manage.py translate --target-lang nl
# Translate to all configured languages
python manage.py translate
Preview Mode¶
# Preview PO file translations
python manage.py translate --target-lang fr --dry-run
# Preview model translations
python manage.py translate --target-lang fr --models --dry-run
Force Re-translation¶
# Re-translate all PO entries
python manage.py translate --target-lang de --overwrite
# Re-translate all model fields
python manage.py translate --target-lang de --models --overwrite
Model-Specific Translation¶
# Translate only Article and Product models
python manage.py translate --target-lang nl --models Article Product
# Preview before applying
python manage.py translate --target-lang nl --models Article --dry-run
App-Specific Translation¶
# Translate only the blog app's .po files
python manage.py translate --target-lang nl --app blog
# Translate multiple apps
python manage.py translate --target-lang nl --app blog --app shop
# Preview before applying
python manage.py translate --target-lang nl --app blog --dry-run
Complete Workflow¶
# Generate message files
python manage.py makemessages -l de -l fr -l nl
# Preview translations
python manage.py translate --dry-run
# Apply translations
python manage.py translate
# Compile for use
python manage.py compilemessages
Exit Codes¶
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Error (invalid options, API error, etc.) |
Errors and Retries¶
With an LLM provider, when the API rate limit is hit, TranslateBot waits and tries again, up to 5 attempts in total. It waits as long as the provider's Retry-After header asks, or otherwise 60, 120, 240 and 480 seconds (about 15 minutes in total). With DeepL, the DeepL client retries briefly on its own, and a rate limit that persists stops the run.
With an LLM provider, each request may take up to TRANSLATEBOT_TIMEOUT seconds (default 300). Timeouts, connection errors and server errors (5xx) are retried twice, after 5 and 15 seconds. If the provider is down, the run stops after a few minutes with an error, instead of hanging. If your model is just slow on large batches, raise TRANSLATEBOT_TIMEOUT.
A response that isn't valid as a whole (invalid JSON, or the wrong number of translations) is retried once. Single translations that fail validation, such as a dropped placeholder, are retried once without stopping the run. If they fail again, they're listed at the end of the run, and an entry that's still untranslated gets the translation as a fuzzy draft.
Other failures stop the run immediately with an error message: authentication errors, insufficient credits, unknown model names, and responses that are still invalid after the retry. Batches translated before the error are already saved, so rerunning the command continues where it stopped. With --overwrite, a rerun starts over (and pays again for the batches already done); a rerun without it only fills the entries that are still empty or fuzzy.
Environment Variables¶
| Variable | Description |
|---|---|
TRANSLATEBOT_API_KEY |
API key (fallback if not in settings) |
Using from Python code?
If you want to trigger translations from a Celery task, script, or other Python code, see the Python API.
check_translations¶
Verify that all .po files are fully translated with no fuzzy entries. Designed for CI pipelines, exits with code 1 on failure.
Synopsis¶
Options¶
--makemessages¶
Run makemessages -a --no-obsolete before checking translations. This ensures .po files are in sync with your source code.
Note
Requires gettext to be installed on your system.
Output¶
Every .po file found is checked (the same locations as translate, for all languages), and its absolute path is printed. On success:
/app/locale/de/LC_MESSAGES/django.po: OK
/app/locale/nl/LC_MESSAGES/django.po: OK
All translations complete.
On failure:
/app/locale/de/LC_MESSAGES/django.po: 2 untranslated, 0 fuzzy
/app/locale/nl/LC_MESSAGES/django.po: 0 untranslated, 1 fuzzy
CommandError: Translation check failed
Note
If your project has a .po file for the source language (e.g. locale/en/), it is checked too. An empty source-language msgstr counts as untranslated.
Exit Codes¶
| Code | Meaning |
|---|---|
| 0 | All translations complete |
| 1 | Missing or fuzzy translations found |
See CI Integration for usage examples in GitHub Actions and GitLab CI.
Related Commands¶
| Command | Description |
|---|---|
translate |
Translate .po files and model fields using AI |
check_translations |
Verify all translations are complete (CI check) |
makemessages |
Extract translatable strings to .po files |
compilemessages |
Compile .po files to .mo files |