Django i18n: Der vollständige Leitfaden zur Automatisierung der .po-Dateiübersetzung

Wenn Sie jemals eine Django-App in mehr als einer Sprache ausgeliefert haben, kennen Sie den Ablauf. Sie umschließen Ihre Strings mit gettext(), führen makemessages aus, öffnen eine .po-Datei mit Hunderten von Einträgen und beginnen, Zeile für Zeile zu übersetzen. Für zwei Sprachen und fünfzig Strings ist das erträglich. Für sechs Sprachen und fünfhundert Strings ist es ein ganzer Arbeitstag, den Sie nie zurückbekommen.

Dieser Leitfaden behandelt Djangos Internationalisierungs-Pipeline (i18n) von Anfang bis Ende, erklärt, wo sie zusammenbricht, und zeigt, wie Sie den schmerzhaften Teil mit KI-gestützter Übersetzung automatisieren können.

Der Standard-Django-i18n-Workflow

Djangos eingebautes i18n-System ist gut durchdacht. Die Kernschleife sieht so aus:

Schritt 1: Strings für die Übersetzung markieren in Ihrem Python-Code und Ihren Templates:

from django.utils.translation import gettext as _

def dashboard(request):
    welcome = _("Welcome back, %(name)s!") % {"name": request.user.first_name}
    return render(request, "dashboard.html", {"welcome": welcome})

{% load i18n %}
<h1>{% trans "Account Settings" %}</h1>
<p>{% blocktrans %}You have {{ count }} unread messages.{% endblocktrans %}</p>

Schritt 2: Strings extrahieren in .po-Dateien:

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

Dies durchsucht Ihre gesamte Codebasis und generiert eine .po-Datei pro Sprache, die jeden übersetzbaren String enthält:

#: myapp/views.py:4
msgid "Welcome back, %(name)s!"
msgstr ""

#: templates/dashboard.html:2
msgid "Account Settings"
msgstr ""

Schritt 3: Jeden leeren msgstr von Hand übersetzen.

Schritt 4: Die fertigen .po-Dateien in binäre .mo-Dateien kompilieren:

python manage.py compilemessages

Die Schritte 1, 2 und 4 gehen schnell. Schritt 3 ist der Punkt, an dem der Prozess scheitert.

Warum manuelle Übersetzung nicht skaliert

Eine typische Django-Anwendung hat zwischen 200 und 2.000 übersetzbare Strings. Multiplizieren Sie das mit der Anzahl der Zielsprachen, und Sie haben einen erheblichen Zeitaufwand vor sich.

Das ist keine theoretische Beschwerde. In einem bekannten Thread im Django Forum berichtete ein Entwickler, dass er über 8 Stunden pro .po-Datei für manuelle Übersetzungen benötigte. Ein Django-Core-Contributor beschrieb, dass er über 10 Stunden brauchte, um von der Community eingereichte Übersetzungen in ein einziges Release zu integrieren, hauptsächlich für Review, Formatierungskorrekturen und die Reparatur defekter Platzhalter.

Die Probleme potenzieren sich mit der Zeit:

• Platzhalter gehen kaputt. Kopieren Sie einen String wie Welcome, %(name)s! in Google Translate, und Sie erhalten oft Willkommen, %(Name)s! oder Bienvenue, %(nom)s! zurück. Diese subtile Verfälschung verursacht Laufzeitfehler.
• Konsistenz driftet ab. Ohne Glossar wird "dashboard" in einer Datei als "Instrumententafel" und in einer anderen als "Dashboard" übersetzt. Drei Monate später erinnert sich niemand, welche Variante beabsichtigt war.
• Sprints fügen Strings hinzu. Jeder Feature-Branch fügt neue übersetzbare Strings hinzu. Selbst wenn Sie letztes Quartal für einen vollständigen Übersetzungsdurchlauf bezahlt haben, haben Sie jetzt 40 unübersetzte Einträge in Ihren .po-Dateien verstreut.
• KI-Assistenten helfen einmal. Sie können eine .po-Datei in ChatGPT oder Claude einfügen und brauchbare Ergebnisse erhalten. Aber im nächsten Sprint, wenn 15 neue Strings auftauchen, prompten Sie von vorn, übersetzen die ganze Datei neu und hoffen, dass es mit dem bereits Vorhandenen konsistent bleibt.

Die Grundursache ist, dass Übersetzung als einmaliges Ereignis behandelt wird statt als inkrementeller, wiederholbarer Prozess.

Übersetzung mit KI automatisieren

Die Idee ist einfach: Statt dass ein Mensch jede .po-Datei öffnet und msgstr-Werte ausfüllt, liest ein Tool die Datei, sendet unübersetzte Strings an ein KI-Modell oder eine Übersetzungs-API, schreibt die Ergebnisse zurück und bewahrt alles andere (Kommentare, Dateistruktur, Platzhalter, Pluralformen).

TranslateBot Django ist ein Open-Source-Paket, das genau das tut. Es integriert sich in Djangos Management-Command-System und passt daher in den Workflow, den Sie bereits haben.

Schritt-für-Schritt-Einrichtung

1. Paket installieren

pip install translatebot-django

Oder, wenn Sie uv verwenden (empfohlen):

uv add --dev translatebot-django

Die Installation als Dev-Dependency ist beabsichtigt. Sie brauchen TranslateBot nur beim Generieren von Übersetzungen, nicht zur Laufzeit in der Produktion.

2. Zu INSTALLED_APPS hinzufügen

# settings.py
INSTALLED_APPS = [
    # ...
    "translatebot_django",
]

3. Ihren KI-Anbieter konfigurieren

# settings.py
import os

TRANSLATEBOT_API_KEY = os.getenv("OPENAI_API_KEY")
TRANSLATEBOT_MODEL = "gpt-4o-mini"

TranslateBot verwendet unter der Haube LiteLLM, was bedeutet, dass Sie durch Ändern eines einzigen Strings zu einem von über 100 Modellen wechseln können:

Für DeepL installieren Sie das Extra: pip install translatebot-django[deepl]. Das kostenlose Kontingent von DeepL gibt Ihnen 500.000 Zeichen pro Monat gratis, was für die meisten kleinen bis mittleren Projekte ausreicht.

4. Ihre Sprachen definieren

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

5. Die Übersetzung ausführen

python manage.py translate

Das war's. TranslateBot durchsucht Ihr Projekt nach .po-Dateien, identifiziert unübersetzte Einträge, sendet sie in optimierten Batches an das konfigurierte KI-Modell und schreibt die Ergebnisse zurück. Bestehende Übersetzungen bleiben unberührt.

Um eine einzelne Sprache zu übersetzen:

python manage.py translate --target-lang nl

Die Ausgabe sieht so aus:

Translating to Dutch (nl)...
Found 42 strings to translate
Translating batch 1/2...
Translating batch 2/2...
Successfully translated 42 strings

6. Wie gewohnt kompilieren

python manage.py compilemessages

Ihr vollständiger Workflow ist jetzt:

python manage.py makemessages -l de -l fr -l nl -l ja
python manage.py translate
python manage.py compilemessages

Drei Befehle. Jede Sprache. Jeder Sprint.

Inkrementell by Design

Das wichtigste Feature für einen wiederholbaren Workflow ist inkrementelle Übersetzung. TranslateBot übersetzt nur Einträge, bei denen msgstr leer ist. Wenn Sie 500 Strings haben und 15 in diesem Sprint neu sind, werden nur diese 15 an die API gesendet.

Das ist aus praktischen Gründen wichtig:

1. Kosten. Sie zahlen nur für neue Strings, nicht für die gesamte Datei.
2. Geschwindigkeit. Die Übersetzung von 15 Strings dauert Sekunden, nicht Minuten.
3. Stabilität. Übersetzungen, die Sie bereits geprüft und freigegeben haben, werden nie überschrieben (es sei denn, Sie übergeben explizit --overwrite).

Platzhalter-Sicherheit

Django verwendet mehrere Platzhalter-Formate: %(name)s, %s, %d, {0}, {name} und Inline-HTML-Tags wie <strong> oder <a href="...">. Wenn eines davon bei der Übersetzung beschädigt wird, erhalten Sie Laufzeitfehler oder defektes Markup.

TranslateBot weist das KI-Modell an, alle Platzhalter-Formate zu bewahren, und validiert die Ausgabe. Ein String wie:

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

Wird ins Niederländische übersetzt als:

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

Jeder Platzhalter überlebt intakt.

Qualitätskontrolle mit TRANSLATING.md

KI-Modelle übersetzen besser, wenn sie den Kontext verstehen. TranslateBot sucht in Ihrem Projektstammverzeichnis nach einer TRANSLATING.md-Datei und fügt deren Inhalt in jede Übersetzungsanfrage ein.

# Translation Context

## About This Project
A B2B project management tool for construction companies.

## Terminology
- "project" means a construction project, not a software project
- "plan" means a building plan/blueprint, not a subscription plan
- Keep "Gantt chart" as-is in all languages

## Tone
- German: use formal "Sie" form (business context)
- French: use formal "vous" form
- Dutch: use informal "je" form

## Do Not Translate
- Brand name: "BuildFlow"
- Feature names: "SmartSchedule", "CostTracker"

Diese Datei wird zusammen mit Ihrem Code versioniert, sodass Ihr gesamtes Team denselben Übersetzungskontext teilt. Sie können auch pro App TRANSLATING.md-Dateien für Apps mit spezialisierter Terminologie anlegen. Ein Modul für Patientenakten und ein Abrechnungsmodul können jeweils ein eigenes Glossar haben.

Vorschau vor dem Commit

Das --dry-run-Flag zeigt genau, was übersetzt werden würde, ohne API-Aufrufe zu machen oder Dateien zu ändern:

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

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

Das ist nützlich vor einem großen Übersetzungslauf oder wenn ein neues Teammitglied verstehen möchte, was der Befehl tut, bevor es API-Kosten eingeht.

CI/CD-Integration

Dass Übersetzungen veralten, ist ohne Durchsetzung unvermeidlich. TranslateBot enthält einen check_translations-Management-Befehl, der für CI-Pipelines konzipiert ist:

# .github/workflows/ci.yml
jobs:
  translations:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v4
        with:
          enable-cache: true
      - run: uv python install
      - run: uv sync --frozen
      - name: Install gettext
        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends gettext
      - name: Check translations
        run: uv run python manage.py check_translations --makemessages

Das --makemessages-Flag führt zuerst makemessages -a --no-obsolete aus und stellt sicher, dass die .po-Dateien den aktuellen Quellcode widerspiegeln, bevor geprüft wird. Wenn Einträge unübersetzt oder fuzzy sind, beendet sich der Befehl mit Code 1 und lässt den Build fehlschlagen:

locale/de/LC_MESSAGES/django.po: 2 untranslated, 0 fuzzy
locale/nl/LC_MESSAGES/django.po: 0 untranslated, 1 fuzzy
CommandError: Translation check failed

Der typische Entwickler-Workflow wird zu:

1. Neue übersetzbare Strings in einem Feature-Branch hinzufügen.
2. CI schlägt fehl, weil diese Strings unübersetzt sind.
3. python manage.py translate lokal ausführen.
4. Die aktualisierten .po-Dateien committen.
5. CI ist erfolgreich.

Übersetzungen geraten nie stillschweigend aus dem Takt.

Datenbankinhalte übersetzen

Wenn Ihre Anwendung übersetzbare Inhalte in der Datenbank speichert (Produktnamen, Blog-Post-Titel, Kategorie-Labels), integriert sich TranslateBot auch mit django-modeltranslation:

pip install translatebot-django[modeltranslation]

# Translate all registered model fields
python manage.py translate --target-lang de --models

# Translate specific models only
python manage.py translate --target-lang de --models Product Category

Dieselbe inkrementelle Logik gilt: Nur Felder, bei denen der Zielsprachenwert leer ist, werden übersetzt.

Kostenvergleich

Eine der häufigsten Fragen ist, ob KI-Übersetzung im Vergleich zu Alternativen kosteneffizient ist. Hier ein grober Vergleich für ein Projekt mit 500 übersetzbaren Strings in 5 Sprachen:

Die Zahlen verschieben sich je nach String-Anzahl und Zielsprachen, aber der Größenordnungsunterschied bleibt konstant. Für die laufende Pflege (Übersetzung der 20-50 neuen Strings, die jeden Sprint hinzukommen) sind die KI-Kosten im Wesentlichen null.

Best Practices

Beginnen Sie mit --dry-run. Bevor Sie Ihren ersten echten Übersetzungslauf starten, sehen Sie sich an, was passieren wird. Das schafft Vertrauen und deckt Konfigurationsprobleme frühzeitig auf.

Committen Sie .po-Dateien vor dem Übersetzen. Wenn etwas schiefgeht, bringt Sie git checkout sofort in einen sauberen Zustand zurück.

Schreiben Sie vom ersten Tag an eine TRANSLATING.md. Selbst eine kurze Datei mit Ihrer Projektbeschreibung und einigen Terminologieregeln verbessert die Übersetzungsqualität messbar.

Fügen Sie check_translations zu CI hinzu. Dieser einzige Schritt verhindert den häufigsten i18n-Fehlermodus: Strings, die für die Übersetzung markiert, aber nie tatsächlich übersetzt wurden.

Verwenden Sie gpt-4o-mini oder DeepL für Kosteneffizienz. Heben Sie sich Premium-Modelle wie GPT-4o oder Claude für Projekte auf, bei denen Präzision zählt, etwa Marketing-Texte, juristische Texte oder domänenspezifische Terminologie.

Überprüfen Sie kritische Strings. KI-Übersetzungen sind für die meisten UI-Texte gut genug, aber lassen Sie alles, was rechtlich bindend, sicherheitskritisch oder kundenorientiert in einem Hochrisiko-Kontext ist, von einem Muttersprachler überprüfen.

Von Stunden zu Sekunden

Djangos i18n-Framework ist hervorragend beim Extrahieren und Kompilieren von Übersetzungen. Die Lücke war immer der Übersetzungsschritt selbst, die mühsame, fehleranfällige Arbeit des Ausfüllens Hunderter msgstr-Werte in mehreren Sprachen.

TranslateBot schließt diese Lücke. Installieren Sie es, richten Sie es auf einen KI-Anbieter und führen Sie einen Befehl aus. Neue Strings werden übersetzt. Bestehende Strings bleiben unberührt. Platzhalter bleiben intakt. CI fängt alles ab, was durchrutscht.

Ihre .po-Dateien hören auf, eine Last zu sein, und werden einfach ein weiterer Teil des Builds.

pip install translatebot-django

Starten Sie auf translatebot.dev.