translatebot-django
⚡ Translate Django .po files and model fields with AI. Repeatable, consistent, and pennies per language.
Documentation: https://translatebot.dev/docs/
The Problem
Translating a Django app sounds simple until it isn't:
- Manual workflow doesn't scale. Copy strings to Google Translate, paste back, fix placeholders, repeat for every language. It works for 20 strings. It falls apart at 200.
- AI assistants work once, but not repeatedly. You can ask ChatGPT or Claude Code to translate a
.pofile, and it'll do a decent job. Once. Next sprint, when 15 new strings appear, you're prompting from scratch, re-translating the whole file, and hoping it stays consistent. - SaaS translation platforms are expensive overkill. Paid localization services charge per-word subscriptions and come with portals, review workflows, and team features you don't need for a solo project or small team.
Why TranslateBot
TranslateBot is a dedicated tool that sits between "do it by hand" and "pay for a platform":
- Incremental. Only translates new and changed strings. Add 10 strings in a sprint, pay for 10 strings, not the whole file.
- Consistent. A
TRANSLATING.mdfile in your repo acts as a version-controlled glossary: terminology, tone, brand rules. Every translation run uses it. - Cost-efficient. Batches strings into optimized API requests. A typical app costs under $0.01 per language with GPT-4o-mini.
- Scales to many languages. One command translates all your configured languages. Adding a new locale is a one-liner.
- Automatable. A CLI command you can script or hook into your workflow. No browser, no portal.
- Placeholder-safe. Keeps
%(name)s,{0},%s, and HTML tags intact: the model is instructed to preserve them, and with DeepL placeholders are swapped for protected tokens and HTML goes through DeepL's tag handling.compilemessagescatches a placeholder mismatch inpython-formatstrings. - Grammar-aware. With LLM providers, every plural form of the target language gets its own translation (Polish, Russian, Arabic, …), and
pgettextcontexts keep "May" the month apart from "May" the verb.
Installation
For PO file translation, TranslateBot is a development tool; install it as a dev dependency:
uv add --dev translatebot-django
For model translation at runtime, install it as a regular dependency instead (see Python API docs):
uv add translatebot-django
Optional extras: translatebot-django[deepl] for the DeepL provider, and translatebot-django[modeltranslation] for model field translation.
Supported versions
Each Django series is tested against the Python versions Django itself supports:
| Django | Python |
|---|---|
| 4.2 | 3.10, 3.11, 3.12 |
| 5.0 | 3.10, 3.11, 3.12 |
| 5.1 | 3.10, 3.11, 3.12, 3.13 |
| 5.2 | 3.10, 3.11, 3.12, 3.13, 3.14 |
| 6.0 | 3.12, 3.13, 3.14 |
| 6.1 | 3.12, 3.13, 3.14 |
Quick Start
# settings.py
import os
INSTALLED_APPS = [
# ...
"translatebot_django",
]
LANGUAGES = [("en", "English"), ("nl", "Dutch"), ("de", "German")]
TRANSLATEBOT_API_KEY = os.getenv("TRANSLATEBOT_API_KEY")
# The default; any LiteLLM model works, e.g. "claude-sonnet-5"
TRANSLATEBOT_MODEL = "gpt-4o-mini"
The API key must belong to the provider of TRANSLATEBOT_MODEL. To use DeepL instead, set TRANSLATEBOT_PROVIDER = "deepl", put your DeepL key in TRANSLATEBOT_API_KEY, and leave out TRANSLATEBOT_MODEL.
# Extract strings into .po files
python manage.py makemessages -l nl -l de
# Preview what would be translated (no API calls, but the key must be set)
python manage.py translate --dry-run
# Translate to all configured languages
python manage.py translate
# Compile for use
python manage.py compilemessages
Features
- Multiple AI Providers: OpenAI, Anthropic, Google Gemini, Azure, many more, and DeepL
- Smart Translation: Preserves placeholders (
%(name)s,{0},%s) and HTML tags - Model Field Translation: Supports django-modeltranslation
- CI Check:
python manage.py check_translationsfails the build when strings are untranslated or fuzzy (CI docs) - Python API:
from translatebot_django import translatefor Celery tasks and scripts (Python API docs) - Flexible Configuration: Django settings, environment variables, or CLI arguments
- Well Tested: 100% code coverage
When to Use TranslateBot
For a one-off translation of 20 strings, ChatGPT works fine. TranslateBot is for ongoing projects with multiple languages where translations need to stay in sync as your code changes.
Use TranslateBot when:
- You're actively developing and strings change every sprint
- You support 3+ languages and want them all updated at once
- You want consistent terminology across translation runs
- You want translations done in seconds, not hours of manual work
Documentation
For full documentation, visit translatebot.dev/docs/
- Installation
- Configuration
- PO File Translation
- Translation Context (
TRANSLATING.md) - Model Translation
- Command Reference
- Python API
- CI Integration
- Supported AI Models
- DeepL
- FAQ
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
# Setup
git clone https://github.com/gettranslatebot/translatebot-django.git
cd translatebot-django
uv sync --extra dev
# Run tests
uv run pytest
License
This project is licensed under the Mozilla Public License 2.0 - see the LICENSE file for details.
Credits
Made with ❤️ for the Django community
1 maintainer
Metadata
1 maintainer
Release files for translatebot-django 1.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| translatebot_django-1.5.0.tar.gz | 101.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| translatebot_django-1.5.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 152.2 kB
Release files / translatebot_django-1.5.0.tar.gz
| Download URL | translatebot_django-1.5.0.tar.gz |
|---|---|
| Size | 101.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4682095c14bdf7d2e479c2e6fb96da2f5db0ea957220fa86ea10b2ca25ee6d73
|
|
BLAKE2b-256 checksum How to use checksums |
5918adae339a6ee814cc3a0d73f1b0a4c3c5906b60495e06d79e2cc24a750aed
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / translatebot_django-1.5.0-py3-none-any.whl
| Download URL | translatebot_django-1.5.0-py3-none-any.whl |
|---|---|
| Size | 51.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dd704f3d081bb63391fe926f16276478cde1c5a07af165086669d07250f06b1c
|
|
BLAKE2b-256 checksum How to use checksums |
b7cb4881f0d09f3d6572fa249c99fef40f168e741cef5184254f3b18471f12a6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency log
