Skip to content

Quick Start

This guide will walk you through translating your Django application in 5 minutes.

1. Configure API Key

Add your AI provider's API key to your settings:

settings.py
import os

TRANSLATEBOT_API_KEY = os.getenv("OPENAI_API_KEY")  # or ANTHROPIC_API_KEY, etc.
TRANSLATEBOT_MODEL = "gpt-6-luna"  # on Python 3.10, use "gpt-4o-mini"

gpt-6-luna is the default. On Python 3.10, set a different model such as gpt-4o-mini, because the litellm versions that run there don't support gpt-6-luna properly. Other popular models: claude-sonnet-5, gpt-6-sol, gemini/gemini-3.5-flash-lite. See Supported AI Models.

Environment Variables

Store your API key in an environment variable rather than hardcoding it in settings.

2. Configure Languages

Define the languages your app supports:

settings.py
LANGUAGES = [
    ("en", "English"),
    ("de", "German"),
    ("fr", "French"),
    ("nl", "Dutch"),
]

3. Create Translatable Strings

Mark strings for translation in your code:

views.py
from django.utils.translation import gettext as _


def my_view(request):
    message = _("Welcome to our website!")
    greeting = _("Hello, %(name)s!") % {"name": request.user.username}
    return render(request, "template.html", {"message": message})

4. Generate .po Files

Create message files for each language:

python manage.py makemessages -l de
python manage.py makemessages -l fr
python manage.py makemessages -l nl

Or all at once:

python manage.py makemessages -l de -l fr -l nl

5. Translate Automatically

Now the magic happens! Run the translate command:

# Translate to all configured languages
python manage.py translate

# Or translate to a specific language
python manage.py translate --target-lang nl

Output

ℹī¸  Found 42 untranslated entries
🔄 Translating with gpt-6-luna...
  💾 Saved batch 1/2
  💾 Saved batch 2/2

Processing: /app/locale/nl/LC_MESSAGES/django.po
✓ Translated 'Welcome to our website!'
✓ Translated 'Hello, %(name)s!'
...
✨ Successfully updated /app/locale/nl/LC_MESSAGES/django.po

============================================================
✨ Successfully translated 42 entries across 1 file(s)

6. Compile Messages

Compile the translations so Django can use them:

python manage.py compilemessages

Done!

Your app is now translated! Switch the language in your browser or use Django's language middleware to see the translations in action.

Preview First (Optional)

Want to see what will be translated before committing? Use dry-run mode:

python manage.py translate --target-lang nl --dry-run

This lists the strings that would be translated, without calling the API or changing any files.

Next Steps