Skip to content

Configuration

TranslateBot Django can be configured through Django settings, environment variables, or command-line arguments.

Django Settings

Required Settings

settings.py
# Your AI provider's API key
TRANSLATEBOT_API_KEY = "your-api-key-here"

Optional Settings

settings.py
# Translation provider: "litellm" (default) or "deepl"
TRANSLATEBOT_PROVIDER = "litellm"

# Model to use (default: gpt-4o-mini, only used with litellm provider)
TRANSLATEBOT_MODEL = "gpt-4o-mini"

# Languages for translation (makes --target-lang optional)
LANGUAGES = [
    ('en', 'English'),
    ('de', 'German'),
    ('fr', 'French'),
    ('nl', 'Dutch'),
]

# Additional locale directories to scan
LOCALE_PATHS = [
    BASE_DIR / 'locale',
]

Environment Variables

You can set the API key via environment variable instead of Django settings:

export TRANSLATEBOT_API_KEY="your-api-key-here"

The environment variable is used if TRANSLATEBOT_API_KEY is not set in Django settings.

Settings Reference

Setting Type Required Default Description
TRANSLATEBOT_API_KEY str Yes - API key for your AI or DeepL provider
TRANSLATEBOT_PROVIDER str No litellm Translation provider: litellm or deepl
TRANSLATEBOT_MODEL str No gpt-4o-mini LLM model identifier (only used with litellm provider)
LANGUAGES list No - Language codes (makes --target-lang optional)
LOCALE_PATHS list No [] Additional locale directories to scan

Example Configurations

OpenAI

settings.py
import os

TRANSLATEBOT_API_KEY = os.getenv("OPENAI_API_KEY")
TRANSLATEBOT_MODEL = "gpt-4o-mini"  # or "gpt-4o" for higher quality

Anthropic Claude

settings.py
import os

TRANSLATEBOT_API_KEY = os.getenv("ANTHROPIC_API_KEY")
TRANSLATEBOT_MODEL = "claude-sonnet-4-5-20250929"

Google Gemini

settings.py
import os

TRANSLATEBOT_API_KEY = os.getenv("GEMINI_API_KEY")
TRANSLATEBOT_MODEL = "gemini/gemini-2.5-flash"

DeepL

settings.py
import os

TRANSLATEBOT_PROVIDER = "deepl"
TRANSLATEBOT_API_KEY = os.getenv("DEEPL_API_KEY")

DeepL Free Tier

DeepL offers a free API tier with 500,000 characters per month. Sign up for a free API key.

Install Required

DeepL requires an extra dependency: pip install translatebot-django[deepl]

Azure OpenAI

settings.py
import os

TRANSLATEBOT_API_KEY = os.getenv("AZURE_API_KEY")
TRANSLATEBOT_MODEL = "azure/gpt-4o-mini"

Model Translation Configuration

If using django-modeltranslation, additional settings apply:

settings.py
INSTALLED_APPS = [
    'modeltranslation',  # Must be before django.contrib.admin
    'django.contrib.admin',
    # ...
    'translatebot_django',
]

# Languages for modeltranslation (defaults to LANGUAGES)
MODELTRANSLATION_LANGUAGES = ('en', 'de', 'fr', 'nl')

Project Context

You can provide project-specific context to improve translation quality by creating a TRANSLATING.md file in your project root:

TRANSLATING.md
# Translation Context

## About This Project
E-commerce platform for outdoor sports equipment.

## Terminology
- Keep brand names like "Nike" untranslated
- "cart" should be "Warenkorb" in German

## Tone
- Use informal "du" form in German

This context is automatically included in all translation requests when using an LLM provider.

DeepL and Context

The DeepL provider does not support TRANSLATING.md context files. If you need custom terminology or tone guidelines, use an LLM provider or configure a DeepL glossary separately.

Learn More

See Translation Context for detailed guidance on writing effective context files.

Next Steps