Skip to main content

Python i18n: Den komplette lokaliseringsguide

Konfigurer python-i18n med JSON- eller YAML-oversættelsesfiler, håndter pladsholdere og flertalsformer og automatiser derefter oversættelser med AI.

1

Installer python-i18n

python-i18n er et let internationaliseringsbibliotek til Python. Det understøtter JSON- og YAML-oversættelsesfiler, indlejrede nøgler, interpolation af pladsholdere og flertalsformer som standard.

Terminal
pip install python-i18n
python-i18n understøtter JSON som standard. Til YAML-oversættelsesfiler skal du installere den valgfrie YAML-afhængighed med pip install python-i18n[YAML], som tilføjer PyYAML.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Konfigurer oversættelser

Angiv filformatet, tilføj stier til oversættelsesfiler og konfigurer dit standard- og fallbacksprog. Importer denne konfiguration ved din applikations indgangspunkt før alle oversættelseskald.

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 skal pege på mappen med dine oversættelsesfiler, ikke på en bestemt fil. Hvis oversættelser returnerer de rå nøgler, skal du kontrollere, at din load_path er korrekt og at filnavnene matcher dine sprogkoder (f.eks. en.json, de.json).
3

Opret oversættelsesfiler

Opret én fil pr. sprog i enten JSON- eller YAML-format. Brug indlejrede nøgler til at organisere strenge efter funktion eller side. Bevar dit kildesprog (normalt engelsk) som den eneste autoritative kilde.

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"
  }
}
Navngiv nøgler efter det, de beskriver, ikke efter hvor de vises: 'cart.item_count' er bedre end 'homepage_cart_label'. Nøgler bør kunne overleve ændringer af brugergrænsefladens design.
4

Brug oversættelser i din kode

Kald i18n.t() med en punktsepareret nøglesti for at slå oversatte strenge op. Du kan tilsidesætte sproget for hvert kald uden at ændre den globale indstilling.

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"
Indlejrede nøgler bruger punktnotation: i18n.t('nav.home'). Hvis dine JSON-nøgler indeholder bogstavelige punktummer, fortolker python-i18n dem som separatorer mellem niveauer. Undgå punktummer i nøglenavne.
5

Pladsholdere og flertalsformer

python-i18n understøtter interpolation af pladsholdere med syntaksen %{name} og grundlæggende flertalsformer med undernøglerne 'zero', 'one' og 'many'. Overfør nøgleordsargumenter til i18n.t() for begge funktioner.

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"
python-i18n's flertalssystem bruger tre kategorier: zero, one og many. Det dækker engelsk og mange andre sprog, men understøtter ikke alle CLDR-regler for flertal (few, two, other). Til sprog som arabisk, russisk eller polsk med komplekse flertalsformer kan du være nødt til at håndtere særtilfælde manuelt eller bruge et mere avanceret bibliotek.
6

Skift sprog under kørsel

Skift det aktive sprog globalt med i18n.set('locale', code) eller tilsidesæt det for hvert kald med nøgleordsargumentet locale. I webframeworks skal du registrere brugerens foretrukne sprog ud fra requestet og angive sproget før rendering.

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', ...) ændrer sproget globalt. På webservere med flere tråde (gunicorn med workers, Django) kan det skabe race conditions, hvor ét request ændrer sproget, mens et andet er midt i rendering. Brug tilsidesættelse af sproget for hvert kald eller trådlokal lagring for at undgå dette.
7

Smart sprogfallback med python-i18n-locale-chain

Som standard understøtter python-i18n kun ét fallbacksprog. Når en pt-BR-bruger ikke har nogen pt-BR-oversættelser, går biblioteket direkte til det engelske fallback og ignorerer velfungerende pt-PT-oversættelser. python-i18n-locale-chain løser dette med konfigurerbare fallbackkæder, der dækker 75 sprogvarianter.

python-i18n-locale-chain er en gratis open source-pakke. Ét funktionskald aktiverer 75 indbyggede fallbackkæder for regionale varianter af kinesisk, portugisisk, spansk, fransk, tysk, italiensk, nederlandsk, engelsk, arabisk, norsk og malajisk.
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 vigtigste kæder at teste: pt-BR -> pt-PT -> pt -> en (portugisisk), es-MX -> es-419 -> es -> en (spansk), zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en (traditionelt kinesisk). De dækker de mest almindelige regionale fallbackscenarier.
8

Automatiser oversættelser

Når din i18n-opsætning er færdig, kan du oversætte dine sprogfiler med AI. Bed din AI-assistent i dit IDE om at oversætte kildefilen eller brug i18n Agent CLI i din 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
Oversæt trinvist. Når du føjer nye nøgler til kildefilen, skal du kun oversætte ændringerne i stedet for at generere alle filer igen. Det bevarer oversættelser, som mennesker har gennemgået.

Automatiser oversættelseskvaliteten

Find manglende nøgler og ugyldige pladsholdere med i18n-validate, før de når produktion. Test din brugergrænseflade med pseudooversættelser ved hjælp af i18n-pseudo, før de rigtige oversættelser er klar.

Almindelige faldgruber

Oversættelser returnerer rå nøgler

Årsager: load_path er ikke angivet eller peger på den forkerte mappe, file_format matcher ikke dine filendelser eller filnavnene matcher ikke sprogkoderne. Kontrollér, at i18n.load_path indeholder den korrekte mappe og at filerne er navngivet korrekt (f.eks. en.json, de.json).

YAML-filer indlæses ikke

python-i18n kræver PyYAML til YAML-understøttelse, men det installeres ikke som standard. Installer det med pip install python-i18n[YAML]. Uden det ignoreres YAML-filer uden fejlmeddelelse og oversættelser returnerer pladsholdere for manglende nøgler.

Opslag af indlejrede nøgler mislykkes

python-i18n bruger punktnotation til indlejrede nøgler: i18n.t('nav.home'). Hvis din JSON bruger flade nøgler med punktummer i navnet (f.eks. 'nav.home' som én nøgle), fortolker biblioteket det som et indlejret opslag, som derefter mislykkes. Brug i stedet rigtigt indlejrede JSON-objekter.

Sprogændringer lækker mellem requests

i18n.set('locale', ...) er en global handling. På servere med flere tråde kan ét request ændre sproget, mens et andet renderes. Brug nøgleordsargumentet locale= ved individuelle i18n.t()-kald eller angiv sproget i trådlokal lagring med middleware.

Anbefalet filstruktur

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

Oversæt også:

Prøv i18n Agent nu

Slip din oversættelsesfil her

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

eller klik for at vælge en fil

Målsprog

Kræver ingen tilmeldingEstimat med det samme

Sprogfallback med python-i18n-locale-chain

Når en oversættelsesnøgle mangler i et regionalt sprog som es-419, går python-i18n direkte til standardsproget i stedet for først at kontrollere det overordnede sprog es.

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'],
'}')

# Brug: t('greeting', locale='es') — bruger kæden som fallback

Se vores guide til sprogfallback for at få hele listen over understøttede frameworks og 75 indbyggede kæder. Learn more →

Ofte stillede spørgsmål