Command Reference¶
Complete reference for TranslateBot's management commands.
translate¶
Synopsis¶
Options¶
--target-lang¶
Target language code for translation.
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.
Shows what would be translated and the resulting translations, but doesn't modify any files or database records.
--overwrite¶
Re-translate entries that already have translations.
By default, only empty 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-4o for one run instead of the configured default
python manage.py translate --target-lang ja --llm-model gpt-4o
# Use Claude Sonnet for a specific language
python manage.py translate --target-lang nl --llm-model claude-3-5-sonnet-20241022
Note
Only supported with the litellm provider. Passing --llm-model with TRANSLATEBOT_PROVIDER = "deepl" raises an error.
--models¶
Translate database model fields instead of (or in addition to) PO files.
# 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
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.) |
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¶
On success:
On failure:
locale/de/LC_MESSAGES/django.po: 2 untranslated, 0 fuzzy
locale/nl/LC_MESSAGES/django.po: 0 untranslated, 1 fuzzy
CommandError: Translation check failed
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 |