Skip to main content

Python-i18n: Der vollständige Lokalisierungsleitfaden

Richten Sie python-i18n mit JSON- oder YAML-Übersetzungsdateien ein, verarbeiten Sie Platzhalter und Pluralformen und automatisieren Sie anschließend Übersetzungen mit KI.

1

python-i18n installieren

python-i18n ist eine schlanke Internationalisierungsbibliothek für Python. Sie unterstützt JSON- und YAML-Übersetzungsdateien, verschachtelte Schlüssel, Platzhalterinterpolation und Pluralbildung.

Terminal
pip install python-i18n
python-i18n unterstützt JSON standardmäßig. Installieren Sie für YAML-Übersetzungsdateien mit pip install python-i18n[YAML] die optionale YAML-Abhängigkeit, die PyYAML hinzufügt.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Übersetzungen konfigurieren

Legen Sie das Dateiformat fest, fügen Sie Pfade zu Übersetzungsdateien hinzu und konfigurieren Sie Ihre Standard- und Fallback-Locales. Importieren Sie diese Konfiguration am Einstiegspunkt Ihrer Anwendung vor sämtlichen Übersetzungsaufrufen.

i18n_config.py
import i18n

# Set the file format (json or yaml)
i18n.set("file_format", "json")

# Add the directory containing your translation files
i18n.load_path.append("translations/")

# Set the default locale
i18n.set("locale", "en")

# Set the fallback locale (used when a key is missing)
i18n.set("fallback", "en")

# Enable/disable error on missing translations
i18n.set("error_on_missing_translation", False)
load_path muss auf das Verzeichnis mit Ihren Übersetzungsdateien verweisen, nicht auf eine einzelne Datei. Wenn Übersetzungen unverarbeitete Schlüssel zurückgeben, prüfen Sie load_path und ob die Dateinamen Ihren Locale-Codes entsprechen, beispielsweise en.json und de.json.
3

Übersetzungsdateien erstellen

Erstellen Sie eine Datei pro Sprache im JSON- oder YAML-Format. Gliedern Sie Zeichenfolgen mit verschachtelten Schlüsseln nach Funktion oder Seite. Verwenden Sie Ihre Ausgangssprache, üblicherweise Englisch, als einzige maßgebliche Quelle.

translations/en.json
// translations/en.json
{
  "greeting": "Hello!",
  "welcome": "Welcome to our application",
  "nav": {
    "home": "Home",
    "about": "About",
    "settings": "Settings"
  },
  "cart": {
    "item_count": "%{count} item(s) in your cart"
  }
}

// translations/de.json
{
  "greeting": "Hallo!",
  "welcome": "Willkommen in unserer Anwendung",
  "nav": {
    "home": "Startseite",
    "about": "Über uns",
    "settings": "Einstellungen"
  },
  "cart": {
    "item_count": "%{count} Artikel in Ihrem Warenkorb"
  }
}
Benennen Sie Schlüssel nach ihrer Bedeutung und nicht nach ihrer Position: „cart.item_count“ ist besser als „homepage_cart_label“. Schlüssel sollten eine Neugestaltung der Benutzeroberfläche überdauern.
4

Übersetzungen im Code verwenden

Rufen Sie i18n.t() mit einem durch Punkte getrennten Schlüsselpfad auf, um übersetzte Zeichenfolgen abzurufen. Sie können die Locale pro Aufruf überschreiben, ohne die globale Einstellung zu ändern.

app.py
import i18n

# Simple translation
print(i18n.t("greeting"))          # "Hello!"
print(i18n.t("nav.home"))          # "Home"
print(i18n.t("nav.about"))         # "About"

# Translation with a specific locale
print(i18n.t("greeting", locale="de"))   # "Hallo!"
print(i18n.t("nav.home", locale="ja"))   # "ホーム"

# Missing key returns a placeholder
print(i18n.t("missing.key"))       # "Missing.Key"
Verschachtelte Schlüssel verwenden Punktnotation: i18n.t('nav.home'). Enthalten Ihre JSON-Schlüssel Punkte als Literalzeichen, interpretiert python-i18n sie als Verschachtelungstrenner. Vermeiden Sie Punkte in Schlüsselnamen.
5

Platzhalter und Pluralbildung

python-i18n unterstützt Platzhalterinterpolation mit der Syntax %{name} und einfache Pluralbildung mit den Unterschlüsseln zero, one und many. Übergeben Sie für beide Funktionen Schlüsselwortargumente an i18n.t().

Placeholders
# translations/en.json
# {
#   "welcome_user": "Welcome, %{name}!",
#   "order_status": "Order #%{order_id}: %{status}",
#   "file_size": "File size: %{size} %{unit}"
# }

import i18n

# Single placeholder
print(i18n.t("welcome_user", name="Alice"))
# "Welcome, Alice!"

# Multiple placeholders
print(i18n.t("order_status", order_id=12345, status="shipped"))
# "Order #12345: shipped"

# Reusable with different values
print(i18n.t("file_size", size=2.5, unit="MB"))
# "File size: 2.5 MB"

print(i18n.t("file_size", size=800, unit="KB"))
# "File size: 800 KB"
Pluralization
# translations/en.json
# {
#   "inbox": {
#     "zero": "No messages",
#     "one": "1 message",
#     "many": "%{count} messages"
#   }
# }

import i18n

print(i18n.t("inbox", count=0))    # "No messages"
print(i18n.t("inbox", count=1))    # "1 message"
print(i18n.t("inbox", count=42))   # "42 messages"
Die Pluralbildung von python-i18n verwendet drei Kategorien: zero, one und many. Dies deckt Englisch und viele weitere Sprachen ab, unterstützt aber nicht die vollständigen CLDR-Pluralregeln mit few, two und other. Bei Sprachen wie Arabisch, Russisch oder Polnisch mit komplexen Pluralformen müssen Sie Sonderfälle möglicherweise selbst behandeln oder eine fortgeschrittenere Bibliothek verwenden.
6

Locale-Wechsel zur Laufzeit

Wechseln Sie die aktive Locale global mit i18n.set('locale', code) oder überschreiben Sie sie pro Aufruf mit dem Schlüsselwortargument locale. Erkennen Sie in Webframeworks die bevorzugte Sprache aus der Anfrage und setzen Sie die Locale vor dem Rendern.

Locale switching
import i18n

# Set locale globally
i18n.set("locale", "de")
print(i18n.t("greeting"))           # "Hallo!"

# Switch to Japanese
i18n.set("locale", "ja")
print(i18n.t("greeting"))           # "こんにちは！"

# Override per-call without changing global locale
i18n.set("locale", "en")
print(i18n.t("greeting"))           # "Hello!"
print(i18n.t("greeting", locale="de"))  # "Hallo!"
app.py
from flask import Flask, request, g
import i18n

app = Flask(__name__)

i18n.set("file_format", "json")
i18n.load_path.append("translations/")

SUPPORTED_LOCALES = ["en", "de", "ja", "es", "fr"]

@app.before_request
def set_locale():
    # Check URL parameter, cookie, then Accept-Language header
    locale = request.args.get("lang")
    if not locale:
        locale = request.cookies.get("locale")
    if not locale:
        locale = request.accept_languages.best_match(SUPPORTED_LOCALES)
    g.locale = locale or "en"
    i18n.set("locale", g.locale)

@app.route("/")
def index():
    return i18n.t("welcome")
i18n.set('locale', ...) ändert die Locale global. In mehrthreadigen Webservern wie gunicorn mit Workern oder Django kann dies zu Race Conditions führen, wenn eine Anfrage die Locale ändert, während eine andere rendert. Verwenden Sie Locale-Überschreibungen pro Aufruf oder threadlokalen Speicher.
7

Intelligenter Locale-Fallback mit python-i18n-locale-chain

Standardmäßig unterstützt python-i18n nur eine einzelne Fallback-Locale. Fehlen für eine Person mit pt-BR pt-BR-Übersetzungen, wechselt die Bibliothek direkt zum englischen Fallback und ignoriert vollständig geeignete pt-PT-Übersetzungen. python-i18n-locale-chain behebt dies mit konfigurierbaren Fallback-Ketten für 75 Locale-Varianten.

python-i18n-locale-chain ist ein kostenloses, quelloffenes Paket. Ein Funktionsaufruf aktiviert 75 integrierte Fallback-Ketten für regionale Varianten von Chinesisch, Portugiesisch, Spanisch, Französisch, Deutsch, Italienisch, Niederländisch, Englisch, Arabisch, Norwegisch und Malaiisch.
Terminal
pip install python-i18n-locale-chain
i18n_config.py
from locale_chain import configure
import i18n

i18n.set("file_format", "json")
i18n.load_path.append("translations/")

# Activate smart fallback chains (75 built-in chains)
configure()

# Now pt-BR falls back to pt-PT -> pt -> en (instead of just en)
result = i18n.t("greeting", locale="pt-BR")

# es-MX falls back to es-419 -> es -> en
result = i18n.t("greeting", locale="es-MX")

# zh-Hant-HK falls back to zh-Hant-TW -> zh-Hant -> en
result = i18n.t("greeting", locale="zh-Hant-HK")
Advanced configuration
from locale_chain import configure, reset

# Override specific chains
configure(overrides={
    "pt-BR": ["pt"],         # Skip pt-PT, go straight to pt
    "ja-JP": ["ja"],         # Add a new chain
})

# Full custom map (no defaults)
configure(
    fallbacks={"pt-BR": ["pt-PT"]},
    merge_defaults=False
)

# Use German as final fallback instead of English
configure(default_locale="de")

# Restore original i18n.t() behaviour
reset()
Die wichtigsten zu testenden Ketten: pt-BR -> pt-PT -> pt -> en (Portugiesisch), es-MX -> es-419 -> es -> en (Spanisch), zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en (traditionelles Chinesisch). Sie decken die häufigsten regionalen Fallback-Szenarien ab.
8

Übersetzungen automatisieren

Wenn Ihre i18n-Einrichtung abgeschlossen ist, übersetzen Sie Ihre Locale-Dateien mit KI. Bitten Sie Ihren KI-Assistenten in Ihrer IDE, Ihre Ausgangsdatei zu übersetzen, oder verwenden Sie die CLI von i18n Agent in Ihrer CI/CD-Pipeline.

Terminal
# In your IDE, ask your AI assistant:
> Translate translations/en.json to German, Japanese, and Spanish

translations/de.json created (1.2s)
translations/ja.json created (1.5s)
translations/es.json created (1.1s)

# Or use the CLI in CI/CD:
npx i18n-agent translate translations/en.json --lang de,ja,es
Übersetzen Sie schrittweise. Wenn Sie Ihrer Ausgangsdatei neue Schlüssel hinzufügen, übersetzen Sie nur die Änderungen, statt sämtliche Dateien neu zu erzeugen. So bleiben von Menschen geprüfte Übersetzungen erhalten.

Übersetzungsqualität automatisieren

Erkennen Sie mit i18n-validate fehlende Schlüssel und beschädigte Platzhalter vor der Veröffentlichung. Testen Sie Ihre Benutzeroberfläche mit i18n-pseudo und Pseudoübersetzungen, bevor echte Übersetzungen vorliegen.

Häufige Fallstricke

Übersetzungen geben unverarbeitete Schlüssel zurück

Mögliche Ursachen: load_path ist nicht gesetzt oder verweist auf das falsche Verzeichnis, file_format entspricht nicht Ihren Dateierweiterungen oder Dateinamen entsprechen nicht den Locale-Codes. Prüfen Sie, ob i18n.load_path das richtige Verzeichnis enthält und Dateien korrekt benannt sind, beispielsweise en.json und de.json.

YAML-Dateien werden nicht geladen

python-i18n benötigt PyYAML für die YAML-Unterstützung, doch es wird nicht standardmäßig installiert. Installieren Sie es mit pip install python-i18n[YAML]. Andernfalls werden YAML-Dateien unbemerkt ignoriert und Übersetzungen geben Platzhalter für fehlende Schlüssel zurück.

Abfragen verschachtelter Schlüssel schlagen fehl

python-i18n verwendet Punktnotation für verschachtelte Schlüssel: i18n.t('nav.home'). Wenn Ihr JSON flache Schlüssel mit Punkten im Namen enthält, etwa nav.home als einzelnen Schlüssel, interpretiert die Bibliothek dies als verschachtelte Abfrage und scheitert. Verwenden Sie stattdessen tatsächlich verschachtelte JSON-Objekte.

Locale-Änderungen treten zwischen Anfragen über

i18n.set('locale', ...) ist ein globaler Vorgang. Auf mehrthreadigen Servern kann eine Anfrage die Locale ändern, während eine andere rendert. Verwenden Sie das Schlüsselwortargument locale= bei einzelnen i18n.t()-Aufrufen oder setzen Sie die Locale mit Middleware in threadlokalem Speicher.

Empfohlene Dateistruktur

Project Structure
my-python-app/
├── translations/
│   ├── en.json           # Source language (JSON)
│   ├── de.json           # German
│   ├── ja.json           # Japanese
│   ├── es.json           # Spanish
│   └── pt-BR.json        # Brazilian Portuguese
├── app.py                # Application entry point
├── i18n_config.py        # i18n setup and configuration
├── requirements.txt      # pip dependencies
└── pyproject.toml        # Project metadata

# Or with YAML files:
my-python-app/
├── translations/
│   ├── en.yml
│   ├── de.yml
│   └── ja.yml
├── app.py
└── ...

Auch übersetzen:

i18n Agent jetzt testen

Legen Sie Ihre Übersetzungsdatei hier ab

JSON, YAML, PO, XML, CSV, Markdown, Properties

oder zum Auswählen klicken

Zielsprachen

Keine Registrierung erforderlichSofortiges Angebot

Locale-Fallback mit python-i18n-locale-chain

Fehlt ein Übersetzungsschlüssel in einer regionalen Locale wie es-419, wechselt python-i18n direkt zur Standard-Locale, statt zuerst die übergeordnete Locale es zu prüfen.

Terminal
pip install python-i18n-locale-chain
Configuration
from i18n_locale_chain import configure_chain

configure_chain('{'
    'es': ['en', 'ru'],
    'pt-BR': ['pt', 'en'],
    'zh-Hant-HK': ['zh-Hant', 'zh', 'en'],
'}')

# Usage: t('greeting', locale='es') — falls back through chain

In unserem Leitfaden zu Locale-Fallbacks finden Sie die vollständige Liste unterstützter Frameworks und 75 integrierter Ketten. Learn more →

Häufig gestellte Fragen