Frequently Asked Questions¶

Q: How much does it cost?

Costs depend on your chosen model. GPT-4o-mini costs ~$0.15 per million tokens, Claude 3 Haiku ~$0.80, GPT-4o ~$2.50, and Claude Sonnet 4.5 ~$3.00. A typical small-to-medium app with 500 translatable strings (~10,000 words) costs under $0.01 per language with GPT-4o-mini.

Q: Is the translation quality good?

Yes! Modern LLMs produce high-quality translations that understand context and idioms, preserve technical terminology, handle formal/informal tone appropriately, and maintain consistency across strings. For critical user-facing content, we recommend having a native speaker review the translations.

Q: Which model should I use?

Best value: gpt-4o-mini (fast, cheap, good quality). Best quality: gpt-4o or claude-sonnet-4-5-20250929. For Asian languages: gpt-4o or Claude models. Budget-conscious: gpt-4o-mini or claude-3-haiku.

Q: Can I preview translations before saving?

Yes! Use the --dry-run flag: python manage.py translate --target-lang nl --dry-run. This shows all translations without modifying files or the database.

Q: How do I update existing translations?

Use the --overwrite flag: python manage.py translate --target-lang nl --overwrite. By default, only empty entries are translated to save costs.

Q: Does it preserve Django placeholders?

Yes! TranslateBot preserves all placeholder types including named placeholders like %(name)s, positional placeholders like %s, format strings like {0} and {name}, HTML tags, and line breaks.

Q: Can I translate to multiple languages at once?

Yes! If you have LANGUAGES defined in settings, run: python manage.py translate. This translates to all configured languages. Or run multiple commands for specific languages.

Q: How do I translate database content?

Install with modeltranslation support: pip install translatebot-django[modeltranslation]. Then configure django-modeltranslation and use: python manage.py translate --target-lang nl --models.

Q: Can I provide custom context for translations?

Yes! Create a TRANSLATING.md file in your project root to provide domain-specific context, terminology guidelines, tone preferences, and brand names to keep untranslated. This context is automatically included in all translation requests to improve quality.

General¶

Why not just use ChatGPT or Claude Code?¶

They work great for one-off translations. If you have 20 strings and one language, asking an AI assistant is the fastest option.

TranslateBot is built for the ongoing case: you're actively developing, strings change every sprint, and you support multiple languages. Here's where a dedicated tool pulls ahead:

Incremental translation. TranslateBot only translates new and changed strings. AI assistants reprocess the whole file every time, which costs more and risks changing translations you've already reviewed.
Consistent terminology. A TRANSLATING.md file acts as a version-controlled glossary. AI assistants have no memory between sessions, so you'd need to paste your style guide into every prompt.
Lower cost at scale. TranslateBot batches strings into efficient API calls. Pasting an entire .po file into ChatGPT uses far more tokens than necessary.
All languages in one command. python manage.py translate hits every configured locale. With an AI assistant, you'd run separate prompts for each language.
Scriptable. TranslateBot is a CLI command you can script into your workflow. No copying, no pasting, no browser.
Placeholder safety. Format strings like %(name)s, {0}, and %s are preserved with 100% test coverage. AI assistants sometimes mangle these, and the failure mode is a production crash.

Can I use DeepL instead of an LLM?¶

Yes! TranslateBot supports DeepL as a translation provider. DeepL offers a free tier with 500,000 characters/month. Install the extra dependency and set one setting:

settings.py

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

Note that DeepL does not support custom context via TRANSLATING.md. See the DeepL integration guide for details.

How much does it cost?¶

Costs depend on your chosen provider and the amount of text. DeepL offers a free tier with 500,000 characters/month.

For LLM providers, costs depend on the model:

Model	Cost per Million Tokens
GPT-4o-mini	~$0.15
Claude 3 Haiku	~$0.80
GPT-4o	~$2.50
Claude Sonnet 4.5	~$3.00

Typical cost: A small-to-medium app with 500 translatable strings (~10,000 words) costs under $0.01 per language with GPT-4o-mini.

Is the translation quality good?¶

Yes! Modern LLMs produce high-quality translations that:

Understand context and idioms
Preserve technical terminology
Handle formal/informal tone appropriately
Maintain consistency across strings

For critical user-facing content, we recommend having a native speaker review the translations.

Which model should I use?¶

Best value: gpt-4o-mini (fast, cheap, good quality)
Best quality: gpt-4o or claude-sonnet-4-5-20250929
Asian languages: gpt-4o or Claude models
Budget-conscious: gpt-4o-mini or claude-3-haiku

See Supported AI Models for detailed comparisons.

Usage¶

Can I preview translations before saving?¶

Yes! Use the --dry-run flag:

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

This shows which strings would be translated without making API calls or modifying files.

How do I update existing translations?¶

Use the --overwrite flag:

python manage.py translate --target-lang nl --overwrite

By default, only empty entries are translated to save costs.

Does it preserve Django placeholders?¶

Yes! TranslateBot preserves all placeholder types:

Type	Example	Preserved
Named	`%(name)s`, `%(count)d`	Yes
Positional	`%s`, `%d`	Yes
Format strings	`{0}`, `{name}`	Yes
HTML tags	`<strong>`, `<a href>`	Yes
Line breaks	`\n`	Yes

Can I translate to multiple languages at once?¶

Yes! If you have LANGUAGES defined in settings:

# Translates to all configured languages
python manage.py translate

Or run multiple commands:

python manage.py translate --target-lang de
python manage.py translate --target-lang fr
python manage.py translate --target-lang nl

How do I translate database content?¶

Install with modeltranslation support and use the --models flag:

# Install
pip install translatebot-django[modeltranslation]

# Configure django-modeltranslation
# Then translate
python manage.py translate --target-lang nl --models

See Model Translation for full setup instructions.

Configuration¶

Can I use my own API key from environment variables?¶

Yes! TranslateBot checks both Django settings and environment variables:

export TRANSLATEBOT_API_KEY="your-api-key"
python manage.py translate --target-lang nl

Can I provide custom context for translations?¶

Yes! Create a TRANSLATING.md file in your project root to provide:

Domain context: "This is a medical application"
Terminology: "cart" → "Warenkorb" (not "Karren") in German
Tone preferences: Use informal "du" form in German
Brand names: Keep "Nike", "Adidas" untranslated

TRANSLATING.md

# Translation Context

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

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

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

This context is automatically included in all translation requests. See Translation Context for detailed examples.

Can I use a custom prompt?¶

The core prompt is built-in to ensure reliable placeholder preservation (preventing lost placeholders, broken HTML, and format string errors).

However, you can customize translations by creating a TRANSLATING.md file with project-specific context, terminology, and style guidelines. This context is added to every translation request. See Translation Context for details.

Does it work with my Django version?¶

TranslateBot supports:

Python: 3.10, 3.11, 3.12, 3.13, 3.14
Django: 4.2, 5.0, 5.1, 5.2, 6.0

Troubleshooting¶

I'm getting authentication errors¶

Check your API key is set correctly:

# settings.py
TRANSLATEBOT_API_KEY = os.getenv("OPENAI_API_KEY")

Verify the environment variable is set:
```
echo $OPENAI_API_KEY
```
Make sure you're using the right key for your model (OpenAI key for GPT, Anthropic key for Claude, etc.)

Translations are empty or incomplete¶

Run with --dry-run to see what's being detected
Check that your .po files exist and have msgid entries
Ensure makemessages was run first

Some strings weren't translated¶

By default, only empty entries are translated. If you want to re-translate:

python manage.py translate --target-lang nl --overwrite

The command is slow¶

Translation speed depends on:

Number of strings
AI model (GPT-4o-mini is fastest)
API rate limits

TranslateBot batches requests efficiently, but large projects may take several minutes.

Contributing¶

How can I contribute?¶

We welcome contributions! See our Contributing Guide:

Fork the repository
Create a feature branch
Make your changes
Run tests: uv run pytest
Submit a pull request

Where do I report bugs?¶

Open an issue on GitHub Issues.