Skip to main content

Python i18n: de complete lokalisatiehandleiding

Stel python-i18n in met JSON- of YAML-vertaalbestanden, verwerk placeholders en meervoudsvormen en automatiseer daarna vertalingen met AI.

1

python-i18n installeren

python-i18n is een compacte internationaliseringsbibliotheek voor Python. De bibliotheek ondersteunt standaard JSON- en YAML-vertaalbestanden, geneste sleutels, interpolatie van placeholders en meervoudsvormen.

Terminal
pip install python-i18n
python-i18n ondersteunt standaard JSON. Installeer voor YAML-vertaalbestanden de optionele YAML-afhankelijkheid met pip install python-i18n[YAML]. Hiermee wordt PyYAML toegevoegd.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Vertalingen configureren

Stel de bestandsindeling in, voeg paden naar vertaalbestanden toe en configureer je standaard- en fallbacklocales. Importeer deze configuratie bij het toegangspunt van je applicatie voordat je vertaalfuncties aanroept.

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 moet verwijzen naar de map met je vertaalbestanden en niet naar één specifiek bestand. Controleer wanneer vertalingen onbewerkte sleutels opleveren of load_path klopt en of de bestandsnamen overeenkomen met je localecodes, bijvoorbeeld en.json en de.json.
3

Vertaalbestanden maken

Maak voor elke taal één bestand in JSON- of YAML-indeling. Gebruik geneste sleutels om teksten per functie of pagina te ordenen. Houd je brontaal, meestal Engels, aan als enige gezaghebbende bron.

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"
  }
}
Benoem sleutels op basis van wat ze beschrijven en niet van waar ze staan: 'cart.item_count' is beter dan 'homepage_cart_label'. Sleutels moeten een nieuw ontwerp van de gebruikersinterface overleven.
4

Vertalingen in je code gebruiken

Roep i18n.t() aan met een door punten gescheiden sleutelpad om een vertaalde tekst op te zoeken. Je kunt de locale per aanroep overschrijven zonder de algemene instelling te wijzigen.

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"
Geneste sleutels gebruiken puntnotatie: i18n.t('nav.home'). Wanneer je JSON-sleutels letterlijke punten bevatten, interpreteert python-i18n deze als scheidingstekens voor nesten. Gebruik daarom geen punten in sleutelnamen.
5

Placeholders en meervoudsvormen

python-i18n ondersteunt interpolatie van placeholders met de syntaxis %{name} en eenvoudige meervoudsvormen met de subsleutels 'zero', 'one' en 'many'. Geef voor beide functies benoemde argumenten door aan 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"
De meervoudsverwerking van python-i18n gebruikt drie categorieën: zero, one en many. Dit volstaat voor Engels en veel andere talen maar ondersteunt niet alle CLDR-categorieën, zoals few, two en other. Voor talen met complexe meervoudsvormen, zoals Arabisch, Russisch of Pools, moet je uitzonderingen mogelijk handmatig verwerken of een uitgebreidere bibliotheek gebruiken.
6

Tijdens runtime van locale wisselen

Wissel de actieve locale voor de hele applicatie met i18n.set('locale', code) of overschrijf deze per aanroep met het argument locale. Detecteer in webframeworks de voorkeurstaal van de gebruiker via het verzoek en stel de locale in voordat je de pagina rendert.

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', ...) wijzigt de locale voor de hele applicatie. Op webservers met meerdere threads, zoals gunicorn met workers en Django, kan dit raceconditions veroorzaken waarbij het ene verzoek de locale wijzigt terwijl het andere wordt gerenderd. Gebruik locale-overschrijvingen per aanroep of thread-local storage om dit te voorkomen.
7

Slimme locale-fallback met python-i18n-locale-chain

Standaard ondersteunt python-i18n maar één fallbacklocale. Wanneer een pt-BR-gebruiker geen pt-BR-vertalingen heeft, springt de bibliotheek meteen naar de Engelse fallback en worden prima pt-PT-vertalingen genegeerd. python-i18n-locale-chain lost dit op met configureerbare fallbackketens voor 75 localevarianten.

python-i18n-locale-chain is een gratis opensourcepakket. Eén functieaanroep activeert 75 ingebouwde fallbackketens voor regionale varianten van het Chinees, Portugees, Spaans, Frans, Duits, Italiaans, Nederlands, Engels, Arabisch, Noors en Maleis.
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()
De belangrijkste ketens om te testen zijn pt-BR -> pt-PT -> pt -> en (Portugees), es-MX -> es-419 -> es -> en (Spaans) en zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en (traditioneel Chinees). Deze dekken de meest voorkomende regionale fallbackscenario's.
8

Vertalingen automatiseren

Wanneer je i18n-configuratie gereed is, vertaal je localebestanden met AI. Vraag je AI-assistent in je ontwikkelomgeving om het bronbestand te vertalen of gebruik de CLI van i18n Agent in je 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
Vertaal stapsgewijs. Wanneer je nieuwe sleutels aan het bronbestand toevoegt, vertaal je alleen het verschil in plaats van alle bestanden opnieuw te genereren. Zo blijven door mensen beoordeelde vertalingen behouden.

Vertaalkwaliteit automatisch bewaken

Vind ontbrekende sleutels en beschadigde placeholders vóór de release met i18n-validate. Test je gebruikersinterface met pseudovertalingen via i18n-pseudo voordat de echte vertalingen beschikbaar zijn.

Veelvoorkomende valkuilen

Vertalingen leveren onbewerkte sleutels op

Mogelijke oorzaken: load_path is niet ingesteld of verwijst naar de verkeerde map, file_format komt niet overeen met je bestandsextensies of bestandsnamen komen niet overeen met localecodes. Controleer of i18n.load_path de juiste map bevat en of de bestanden correct zijn genoemd, bijvoorbeeld en.json en de.json.

YAML-bestanden worden niet geladen

python-i18n vereist PyYAML voor YAML-ondersteuning maar installeert dit niet standaard. Installeer het met pip install python-i18n[YAML]. Zonder PyYAML worden YAML-bestanden stilzwijgend genegeerd en leveren vertalingen placeholders voor ontbrekende sleutels op.

Opzoeken van geneste sleutels mislukt

python-i18n gebruikt puntnotatie voor geneste sleutels: i18n.t('nav.home'). Wanneer je JSON platte sleutels bevat met punten in de naam, bijvoorbeeld 'nav.home' als één sleutel, interpreteert de bibliotheek dit als een geneste opzoekactie en mislukt deze. Gebruik in plaats daarvan echte geneste JSON-objecten.

Localewijzigingen lekken tussen verzoeken

i18n.set('locale', ...) is een algemene bewerking. Op servers met meerdere threads kan één verzoek de locale wijzigen terwijl een ander verzoek wordt gerenderd. Gebruik het argument locale= bij afzonderlijke aanroepen van i18n.t() of stel de locale via middleware in thread-local storage in.

Aanbevolen bestandsstructuur

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
└── ...

Vertaal ook:

Probeer i18n Agent nu

Zet je vertaalbestand hier neer

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

of klik om een bestand te selecteren

Doeltalen

Geen registratie nodigDirecte prijsindicatie

Locale-fallback met python-i18n-locale-chain

Wanneer een vertaalsleutel ontbreekt in een regionale locale zoals es-419, springt python-i18n meteen naar de standaardlocale in plaats van eerst de bovenliggende locale es te controleren.

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

Bekijk onze handleiding voor locale-fallback voor de volledige lijst met ondersteunde frameworks en 75 ingebouwde ketens. Learn more →

Veelgestelde vragen