Skip to main content

Python i18n: den kompletta lokaliseringsguiden

Konfigurera python-i18n med JSON- eller YAML-översättningsfiler, hantera platshållare och pluralformer och automatisera sedan översättningar med AI.

1

Installera python-i18n

python-i18n är ett lättviktigt internationaliseringsbibliotek för Python. Det har inbyggt stöd för JSON- och YAML-översättningsfiler, nästlade nycklar, platshållarinterpolering och pluralformer.

Terminal
pip install python-i18n
python-i18n stöder JSON som standard. Installera det valfria YAML-beroendet med pip install python-i18n[YAML] för YAML-översättningsfiler. Då läggs PyYAML till.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Konfigurera översättningar

Ange filformatet, lägg till sökvägar till översättningsfiler och konfigurera standard- och reservspråkvarianter. Importera konfigurationen vid applikationens startpunkt före alla översättningsanrop.

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åste peka på katalogen som innehåller översättningsfilerna, inte på en enskild fil. Om översättningarna returnerar obearbetade nycklar ska du kontrollera att load_path är korrekt och att filnamnen matchar dina språkkoder (till exempel en.json, de.json).
3

Skapa översättningsfiler

Skapa en fil per språk i antingen JSON- eller YAML-format. Använd nästlade nycklar för att organisera strängar efter funktion eller sida. Låt källspråket (vanligtvis engelska) vara den enda auktoritativa källan.

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"
  }
}
Namnge nycklar efter vad de beskriver, inte var de visas: 'cart.item_count' är bättre än 'homepage_cart_label'. Nycklarna ska fungera även efter att gränssnittet har gjorts om.
4

Använd översättningar i koden

Anropa i18n.t() med en punktavgränsad nyckelsökväg för att slå upp översatta strängar. Du kan åsidosätta språkvarianten för ett enskilt anrop utan att ändra den globala inställningen.

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ästlade nycklar använder punktnotation: i18n.t('nav.home'). Om dina JSON-nycklar innehåller bokstavliga punkter tolkar python-i18n dem som avgränsare för nästling. Undvik punkter i nyckelnamn.
5

Platshållare och pluralformer

python-i18n stöder platshållarinterpolering med syntaxen %{name} och grundläggande pluralhantering med undernycklarna 'zero', 'one' och 'many'. Skicka nyckelordsargument till i18n.t() för båda funktionerna.

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"
Pluralhanteringen i python-i18n använder tre kategorier: zero, one och many. Detta täcker engelska och många andra språk, men stöder inte alla CLDR-pluralregler (few, two, other). För språk som arabiska, ryska eller polska med komplexa pluralformer kan du behöva hantera specialfall manuellt eller använda ett mer avancerat bibliotek.
6

Byt språkvariant vid körning

Byt den aktiva språkvarianten globalt med i18n.set('locale', code) eller åsidosätt den för ett enskilt anrop med nyckelordsargumentet locale. Identifiera användarens föredragna språk från begäran i webbramverk och ställ in språkvarianten före renderingen.

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', ...) ändrar språkvarianten globalt. I flertrådade webbservrar (gunicorn med workers, Django) kan det orsaka konkurrenstillstånd där en begäran ändrar språkvarianten medan en annan håller på att renderas. Använd åsidosättningar per anrop eller trådlokal lagring för att undvika detta.
7

Smart språkreserv med python-i18n-locale-chain

Som standard stöder python-i18n bara en enda reservspråkvariant. När en användare med pt-BR saknar pt-BR-översättningar går biblioteket direkt till den engelska reserven och ignorerar fullt användbara pt-PT-översättningar. python-i18n-locale-chain åtgärdar detta med konfigurerbara reservkedjor som täcker 75 språkvarianter.

python-i18n-locale-chain är ett kostnadsfritt paket med öppen källkod. Ett enda funktionsanrop aktiverar 75 inbyggda reservkedjor för regionala varianter av kinesiska, portugisiska, spanska, franska, tyska, italienska, nederländska, engelska, arabiska, norska och malajiska.
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 viktigaste kedjorna att testa är pt-BR -> pt-PT -> pt -> en (portugisiska), es-MX -> es-419 -> es -> en (spanska) och zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en (traditionell kinesiska). De täcker de vanligaste regionala reservscenarierna.
8

Automatisera översättningar

När i18n-konfigurationen är klar kan du översätta språkfilerna med AI. Be din AI-assistent att översätta källfilen direkt i utvecklingsmiljön eller använd i18n Agent CLI i ditt CI/CD-flöde.

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
Översätt stegvis. När du lägger till nya nycklar i källfilen översätter du bara skillnaden i stället för att generera om alla filer. Då bevaras översättningar som har granskats av människor.

Automatisera översättningskvaliteten

Upptäck saknade nycklar och trasiga platshållare med i18n-validate innan de når produktion. Testa gränssnittet med pseudoöversättningar via i18n-pseudo innan de riktiga översättningarna är klara.

Vanliga fallgropar

Översättningarna returnerar obearbetade nycklar

Orsaker: load_path är inte inställd eller pekar på fel katalog, file_format matchar inte filändelserna eller filnamnen matchar inte språkkoderna. Kontrollera att i18n.load_path innehåller rätt katalog och att filerna har rätt namn (till exempel en.json, de.json).

YAML-filer läses inte in

python-i18n kräver PyYAML för YAML-stöd, men det installeras inte som standard. Installera det med pip install python-i18n[YAML]. Utan det ignoreras YAML-filer tyst och översättningarna returnerar platshållare för saknade nycklar.

Uppslagningar av nästlade nycklar misslyckas

python-i18n använder punktnotation för nästlade nycklar: i18n.t('nav.home'). Om din JSON använder platta nycklar med punkter i namnet (till exempel 'nav.home' som en enda nyckel) tolkar biblioteket det som en nästlad uppslagning och misslyckas. Använd riktiga nästlade JSON-objekt i stället.

Ändringar av språkvariant läcker mellan begäranden

i18n.set('locale', ...) är en global åtgärd. I flertrådade servrar kan en begäran ändra språkvarianten medan en annan renderas. Använd nyckelordsargumentet locale= för enskilda i18n.t()-anrop eller ställ in språkvarianten i trådlokal lagring med ett mellanprogram.

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

Översätt även:

Prova i18n Agent nu

Släpp din översättningsfil här

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

eller klicka för att välja en fil

Målspråk

Ingen registrering krävsPrisuppskattning direkt

Språkreserv med python-i18n-locale-chain

När en översättningsnyckel saknas i en regional språkvariant som es-419 går python-i18n direkt till standardspråkvarianten i stället för att först kontrollera den överordnade språkvarianten 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'],
'}')

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

I vår guide till språkreserver finns en fullständig lista över ramverk som stöds och 75 inbyggda kedjor. Learn more →

Vanliga frågor