Skip to main content

Python i18n: Den komplette lokaliseringsguiden

Sett opp python-i18n med JSON- eller YAML-oversettelsesfiler, håndter plassholdere og flertallsformer, og automatiser deretter oversettelser med AI.

1

Installer python-i18n

python-i18n er et lettvektsbibliotek for internasjonalisering i Python. Det støtter JSON- og YAML-oversettelsesfiler, nøstede nøkler, plassholderinterpolasjon og flertallsformer som standard.

Terminal
pip install python-i18n
python-i18n støtter JSON som standard. For YAML-oversettelsesfiler installerer du den valgfrie YAML-avhengigheten med pip install python-i18n[YAML], som legger til PyYAML.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Konfigurer oversettelser

Angi filformatet, legg til stier til oversettelsesfilene, og konfigurer standard- og reservelokalitetene dine. Importer denne konfigurasjonen ved applikasjonens inngangspunkt før eventuelle oversettelseskall.

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 må peke til mappen som inneholder oversettelsesfilene dine, ikke til en bestemt fil. Hvis oversettelser returnerer rå nøkler, sjekk at load_path er riktig, og at filnavnene samsvarer med lokalitetskodene dine (f.eks. en.json, de.json).
3

Opprett oversettelsesfiler

Opprett én fil per språk, enten i JSON- eller YAML-format. Bruk nøstede nøkler for å organisere strenger etter funksjon eller side. Behold kildespråket ditt (vanligvis engelsk) som den eneste autoritative kilden.

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"
  }
}
Navngi nøkler etter hva de beskriver, ikke hvor de dukker opp: 'cart.item_count' er bedre enn 'homepage_cart_label'. Nøkler bør overleve redesign av brukergrensesnittet.
4

Bruk oversettelser i koden din

Kall i18n.t() med en punktseparert nøkkelsti for å slå opp oversatte strenger. Du kan overstyre lokaliteten per kall uten å endre den globale innstillingen.

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"
Nøstede nøkler bruker punktnotasjon: i18n.t('nav.home'). Hvis JSON-nøklene dine inneholder bokstavelige punktum, vil python-i18n tolke dem som nøstingsseparatorer. Unngå punktum i nøkkelnavn.
5

Plassholdere og flertallsformer

python-i18n støtter plassholderinterpolasjon med %{name}-syntaksen og enkle flertallsformer ved hjelp av undernøklene 'zero', 'one' og 'many'. Send nøkkelordargumenter til i18n.t() for begge funksjonene.

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"
Flertallshåndteringen i python-i18n bruker tre kategorier: zero, one og many. Dette dekker engelsk og mange andre språk, men støtter ikke de fullstendige CLDR-flertallsreglene (few, two, other). For språk som arabisk, russisk eller polsk med komplekse flertallsformer må du kanskje håndtere spesialtilfeller manuelt eller bruke et mer avansert bibliotek.
6

Bytte av lokalitet ved kjøretid

Bytt den aktive lokaliteten globalt med i18n.set('locale', code), eller overstyr den per kall med nøkkelordargumentet locale. I webrammeverk finner du brukerens foretrukne språk fra forespørselen og setter lokaliteten før gjengivelse.

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', ...) endrer lokaliteten globalt. I flertrådede webtjenere (gunicorn med arbeidsprosesser, Django) kan dette føre til kappløpstilstander der én forespørsel endrer lokaliteten mens en annen er i ferd med å gjengis. Bruk lokalitetsoverstyring per kall eller trådlokal lagring for å unngå dette.
7

Smart lokalitetsreserve med python-i18n-locale-chain

Som standard støtter python-i18n bare én enkelt reservelokalitet. Når en pt-BR-bruker ikke har pt-BR-oversettelser, hopper biblioteket rett til den engelske reserven, og ignorerer fullt brukbare pt-PT-oversettelser. python-i18n-locale-chain løser dette med konfigurerbare reservekjeder som dekker 75 lokalitetsvarianter.

python-i18n-locale-chain er en gratis, åpen kildekode-pakke. Ett funksjonskall aktiverer 75 innebygde reservekjeder for regionale varianter av kinesisk, portugisisk, spansk, fransk, tysk, italiensk, nederlandsk, engelsk, arabisk, norsk og malayisk.
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 mest virkningsfulle kjedene å teste: pt-BR -> pt-PT -> pt -> en (portugisisk), es-MX -> es-419 -> es -> en (spansk), zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en (tradisjonell kinesisk). Disse dekker de vanligste regionale reservescenarioene.
8

Automatiser oversettelser

Når i18n-oppsettet ditt er fullført, kan du oversette lokalitetsfilene dine med AI. I IDE-en din kan du be AI-assistenten din om å oversette kildefilen din, eller bruke i18n Agent-CLI-en i CI/CD-pipelinen din.

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
Oversett trinnvis. Når du legger til nye nøkler i kildefilen din, bør du bare oversette differansen i stedet for å regenerere alle filene. Dette bevarer eventuelle menneskelig gjennomgåtte oversettelser.

Automatiser oversettelseskvalitet

Fang opp manglende nøkler og ødelagte plassholdere før de sendes ut, med i18n-validate. Test brukergrensesnittet ditt med pseudo-oversettelser ved hjelp av i18n-pseudo før de ekte oversettelsene er klare.

Vanlige fallgruver

Oversettelser returnerer rå nøkler

Årsaker: load_path er ikke angitt eller peker til feil mappe, file_format samsvarer ikke med filendelsene dine, eller filnavnene samsvarer ikke med lokalitetskodene. Kontroller at i18n.load_path inneholder riktig mappe, og at filene er navngitt riktig (f.eks. en.json, de.json).

YAML-filer lastes ikke inn

python-i18n krever PyYAML for YAML-støtte, men det er ikke installert som standard. Installer med pip install python-i18n[YAML]. Uten det blir YAML-filer ignorert uten varsel, og oversettelser returnerer plassholdere for manglende nøkler.

Oppslag på nøstede nøkler feiler

python-i18n bruker punktnotasjon for nøstede nøkler: i18n.t('nav.home'). Hvis JSON-en din bruker flate nøkler med punktum i navnet (f.eks. 'nav.home' som én enkelt nøkkel), tolker biblioteket det som et nøstet oppslag, og oppslaget mislykkes. Bruk faktiske nøstede JSON-objekter i stedet.

Lokalitetsendringer lekker mellom forespørsler

i18n.set('locale', ...) er en global operasjon. I flertrådede tjenere kan én forespørsel endre lokaliteten mens en annen gjengis. Bruk nøkkelordargumentet locale= på enkeltkall til i18n.t(), eller sett lokaliteten i trådlokal lagring med en mellomvare.

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

Oversett også:

Prøv i18n Agent nå

Slipp oversettelsesfilen din her

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

eller klikk for å bla gjennom

Målspråk

Ingen registrering krevesUmiddelbart estimat

Lokalitetsreserve med python-i18n-locale-chain

Når en oversettelsesnøkkel mangler i en regional lokalitet som es-419, hopper python-i18n rett til standardlokaliteten i stedet for å sjekke overordnet lokalitet es først.

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

Se vår guide for lokalitetsreserve for den fullstendige listen over støttede rammeverk og 75 innebygde kjeder. Learn more →

Ofte stilte spørsmål