Skip to main content

Python i18n: celovit vodnik za lokalizacijo

Nastavite python-i18n s prevodnimi datotekami JSON ali YAML, obravnavajte označbe mest in množinske oblike ter nato avtomatizirajte prevajanje z umetno inteligenco.

1

Namestite python-i18n

python-i18n je lahka knjižnica za internacionalizacijo Pythona. Že takoj podpira prevodne datoteke JSON in YAML, ugnezdene ključe, vstavljanje označb mest ter množinske oblike.

Terminal
pip install python-i18n
python-i18n privzeto podpira JSON. Za prevodne datoteke YAML namestite izbirno odvisnost YAML z ukazom pip install python-i18n[YAML], ki doda PyYAML.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Konfigurirajte prevode

Nastavite obliko datotek, dodajte poti do prevodnih datotek ter konfigurirajte privzete in nadomestne področne nastavitve. To konfiguracijo uvozite na vstopni točki aplikacije pred vsemi klici prevodov.

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 mora kazati na imenik s prevodnimi datotekami in ne na posamezno datoteko. Če se namesto prevodov vračajo neobdelani ključi, preverite, ali je load_path pravilen in ali se imena datotek ujemajo s kodami področnih nastavitev (npr. en.json, de.json).
3

Ustvarite prevodne datoteke

Za vsak jezik ustvarite po eno datoteko v obliki JSON ali YAML. Nize razvrstite po funkcijah ali straneh z ugnezdenimi ključi. Izvorni jezik (običajno angleščina) naj ostane edini zanesljivi vir.

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"
  }
}
Ključe poimenujte glede na to, kaj opisujejo, in ne glede na to, kje se pojavijo: 'cart.item_count' je boljši od 'homepage_cart_label'. Ključi naj ostanejo uporabni tudi po prenovi uporabniškega vmesnika.
4

Uporabite prevode v kodi

Pokličite i18n.t() s potjo ključa, ločeno s pikami, da poiščete prevedene nize. Področne nastavitve lahko preglasite za posamezen klic, ne da bi spremenili splošno nastavitev.

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"
Ugnezdeni ključi uporabljajo zapis s pikami: i18n.t('nav.home'). Če ključi JSON vsebujejo dobesedne pike, jih bo python-i18n obravnaval kot ločila med ravnmi gnezdenja. V imenih ključev se izogibajte pikam.
5

Označbe mest in množinske oblike

python-i18n podpira vstavljanje označb mest s skladnjo %{name} in osnovne množinske oblike s podključi 'zero', 'one' in 'many'. Za obe funkciji posredujte imenovane argumente funkciji 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"
Množinske oblike v python-i18n uporabljajo tri kategorije: zero, one in many. To zadošča za angleščino in številne druge jezike, vendar ne podpira vseh množinskih pravil CLDR (few, two, other). Pri jezikih, kot so arabščina, ruščina ali poljščina, ki imajo zapletene množinske oblike, boste robne primere morda morali obravnavati ročno ali uporabiti naprednejšo knjižnico.
6

Preklapljanje področnih nastavitev med izvajanjem

Dejavne področne nastavitve splošno preklopite z i18n.set('locale', code), za posamezen klic pa jih preglasite z imenovanim argumentom locale. V spletnih ogrodjih iz zahteve zaznajte uporabnikov prednostni jezik in pred izrisom nastavite področne nastavitve.

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', ...) spremeni področne nastavitve za celotno aplikacijo. V večnitnih spletnih strežnikih (gunicorn z delovnimi procesi, Django) lahko to povzroči tekmovalna stanja, pri katerih ena zahteva spremeni področne nastavitve, medtem ko se druga še izrisuje. Temu se izognite s preglasitvami področnih nastavitev pri posameznih klicih ali z nitno lokalno shrambo.
7

Pametno nadomeščanje področnih nastavitev s python-i18n-locale-chain

python-i18n privzeto podpira le ene nadomestne področne nastavitve. Če za uporabnika pt-BR ni prevodov pt-BR, knjižnica preskoči naravnost na nadomestno angleščino in prezre povsem ustrezne prevode pt-PT. python-i18n-locale-chain to odpravi z nastavljivimi nadomestnimi verigami, ki zajemajo 75 različic področnih nastavitev.

python-i18n-locale-chain je brezplačen odprtokodni paket. En klic funkcije omogoči 75 vgrajenih nadomestnih verig za regionalne različice kitajščine, portugalščine, španščine, francoščine, nemščine, italijanščine, nizozemščine, angleščine, arabščine, norveščine in malajščine.
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()
Najpomembnejše verige za preizkus: pt-BR -> pt-PT -> pt -> en (portugalščina), es-MX -> es-419 -> es -> en (španščina), zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en (tradicionalna kitajščina). Te zajemajo najpogostejše primere regionalnega nadomeščanja.
8

Avtomatizirajte prevajanje

Ko je nastavitev i18n dokončana, prevedite datoteke področnih nastavitev z umetno inteligenco. V svojem razvojnem okolju prosite pomočnika z umetno inteligenco, naj prevede izvorno datoteko, ali pa v cevovodu CI/CD uporabite vmesnik ukazne vrstice i18n Agent.

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
Prevajajte postopoma. Ko v izvorno datoteko dodate nove ključe, prevedite le razlike, namesto da znova ustvarite vse datoteke. Tako ohranite vse prevode, ki jih je pregledal človek.

Avtomatizirajte zagotavljanje kakovosti prevodov

Z orodjem i18n-validate odkrijte manjkajoče ključe in poškodovane označbe mest, preden dosežejo uporabnike. Preden so pravi prevodi pripravljeni, uporabniški vmesnik preizkusite s psevdoprevodi z orodjem i18n-pseudo.

Pogoste težave

Prevodi vračajo neobdelane ključe

Vzroki: load_path ni nastavljen ali kaže na napačen imenik, file_format se ne ujema s končnicami datotek ali pa se imena datotek ne ujemajo s kodami področnih nastavitev. Preverite, ali i18n.load_path vsebuje pravilen imenik in ali so datoteke pravilno poimenovane (npr. en.json, de.json).

Datoteke YAML se ne naložijo

python-i18n za podporo oblike YAML zahteva PyYAML, ki pa privzeto ni nameščen. Namestite ga z ukazom pip install python-i18n[YAML]. Brez njega se datoteke YAML tiho prezrejo, namesto prevodov pa se vrnejo označbe manjkajočih ključev.

Iskanje ugnezdenih ključev ne uspe

python-i18n za ugnezdene ključe uporablja zapis s pikami: i18n.t('nav.home'). Če JSON uporablja ploske ključe s pikami v imenu (npr. 'nav.home' kot en sam ključ), knjižnica to razume kot ugnezdeno iskanje, zato iskanje ne uspe. Namesto tega uporabite dejansko ugnezdene predmete JSON.

Spremembe področnih nastavitev se prenašajo med zahtevami

i18n.set('locale', ...) je splošna operacija. V večnitnih strežnikih lahko ena zahteva spremeni področne nastavitve, medtem ko se druga izrisuje. Pri posameznih klicih i18n.t() uporabite imenovani argument locale= ali pa z vmesno programsko opremo nastavite področne nastavitve v nitno lokalni shrambi.

Priporočena struktura datotek

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

Prevedite tudi:

Preizkusite i18n Agent zdaj

Spustite prevajalsko datoteko sem

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

ali kliknite za izbiro

Ciljni jeziki

Registracija ni potrebnaTakojšnja ocena

Nadomeščanje področnih nastavitev s python-i18n-locale-chain

Ko v regionalnih področnih nastavitvah, kot je es-419, manjka prevodni ključ, python-i18n preskoči naravnost na privzete področne nastavitve, namesto da bi najprej preveril nadrejene področne nastavitve 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'],
'}')

# Uporaba: t('greeting', locale='es') — uporabi nadomestne vrednosti po verigi

Celoten seznam podprtih ogrodij in 75 vgrajenih verig najdete v našem vodniku za nadomeščanje področnih nastavitev. Learn more →

Pogosta vprašanja