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.
--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.
--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) |
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 |