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.

General¶

How much does it cost?¶

Costs depend on your chosen model and the amount of text:

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 use a custom prompt?¶

Currently, the prompt is built-in to ensure reliable placeholder preservation. This prevents common issues like:

Lost placeholders
Broken HTML
Format string errors

If you have a specific use case that requires custom prompts, please open an issue to discuss.

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.