Skip to content

PO File Translation

TranslateBot Django automatically translates your Django .po (gettext) files, which are the standard way Django handles internationalization.

How It Works

  1. Scans your project for .po files (django.po and djangojs.po) in:
    • LOCALE_PATHS directories
    • App-specific locale/ directories
    • Default locale/ directory
  2. Identifies untranslated entries (empty msgstr)
  3. Sends messages to the AI model with instructions to preserve formatting
  4. Updates the .po file with translations
  5. Skips obsolete entries and third-party packages automatically

Basic Usage

Translate to a Specific Language

python manage.py translate --target-lang nl

Translate to All Languages

If you have LANGUAGES defined in settings:

python manage.py translate

This translates to all languages except English (the source).

Preview Mode

See what would be translated without making API calls or changes:

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

Dry Run Output

ℹī¸  Found 15 untranslated entries
🔍 Dry run mode: skipping LLM translation

✓ Would translate 'Welcome to our site'
✓ Would translate 'Hello, %(name)s!'
...

Dry run complete: 15 entries would be translated

Dry run mode skips the LLM API entirely, so there are no costs. It shows you exactly which strings need translation before you commit.

Re-translate Existing Entries

By default, only empty entries are translated. To re-translate everything:

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

Warning

This will replace all existing translations. Consider using --dry-run first.

Plural Forms

TranslateBot handles Django's plural forms (msgid_plural / msgstr[n]) automatically. For languages with multiple plural forms (e.g., Polish has 3), all variants are translated in a single pass.

Already-translated plural entries are skipped, just like regular entries.

Placeholder Preservation

TranslateBot preserves all Django placeholders:

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

Example

Source: 

Welcome to %(site_name)s! You have <strong>%(count)d</strong> new messages.

Translated (Dutch): 

Welkom bij %(site_name)s! Je hebt <strong>%(count)d</strong> nieuwe berichten.

Intelligent Batching

TranslateBot groups strings into batches based on the AI model's token limits. This:

  • Maximizes efficiency by reducing API calls
  • Handles large projects with thousands of strings
  • Automatically adjusts batch size based on content length

Workflow Example

# 1. Mark strings in your code
from django.utils.translation import gettext as _
message = _("Welcome to %(site_name)s!")

# 2. Generate .po files
python manage.py makemessages -l de -l fr -l nl

# 3. Preview translations
python manage.py translate --dry-run

# 4. Apply translations
python manage.py translate

# 5. Compile for use
python manage.py compilemessages

Best Practices

Use Dry Run First

Always preview translations with --dry-run before applying them to catch any issues.

Commit Before Translating

Commit your .po files to version control before running translations, so you can easily revert if needed.

Provide Context

Create a TRANSLATING.md file in your project root to provide domain-specific context, terminology guidelines, and tone preferences. See Translation Context for details.

Review Translations

While AI translations are generally good, consider having a native speaker review critical user-facing text.

Next Steps