Skip to main content

Täydellinen Python i18n -lokalisointiopas

Ota python-i18n käyttöön JSON- tai YAML-käännöstiedostoilla, käsittele paikkamerkit ja monikkomuodot sekä automatisoi sitten käännökset tekoälyllä.

1

Asenna python-i18n

python-i18n on kevyt kansainvälistämiskirjasto Python:ille. Se tukee heti JSON- ja YAML-käännöstiedostoja, sisäkkäisiä avaimia, paikkamerkkien interpolointia ja monikkomuotoja.

Terminal
pip install python-i18n
python-i18n tukee JSON:ia oletusarvoisesti. Asenna YAML-käännöstiedostoja varten valinnainen YAML-riippuvuus komennolla pip install python-i18n[YAML], joka lisää PyYAML:in.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Määritä käännökset

Aseta tiedostomuoto, lisää käännöstiedostojen polut ja määritä oletus- ja varakieliversiot. Tuo nämä määritykset sovelluksesi aloituspisteessä ennen käännöskutsuja.

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-arvon on osoitettava käännöstiedostot sisältävään hakemistoon, ei tiettyyn tiedostoon. Jos käännökset palauttavat käsittelemättömiä avaimia, tarkista load_path-arvo ja varmista, että tiedostonimet vastaavat kieliversiokoodeja (esimerkiksi en.json, de.json).
3

Luo käännöstiedostot

Luo jokaiselle kielelle yksi JSON- tai YAML-tiedosto. Järjestä merkkijonot ominaisuuden tai sivun mukaan sisäkkäisillä avaimilla. Pidä lähdekieli, tavallisesti englanti, ainoana ensisijaisena lähteenä.

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"
  }
}
Nimeä avaimet sen mukaan, mitä ne kuvaavat, älä niiden sijainnin mukaan: 'cart.item_count' on parempi kuin 'homepage_cart_label'. Avainten tulisi kestää käyttöliittymän uudistukset.
4

Käytä käännöksiä koodissasi

Hae käännetyt merkkijonot kutsumalla i18n.t()-funktiota pisteillä erotetulla avainpolulla. Voit ohittaa kieliversion kutsukohtaisesti muuttamatta yleistä asetusta.

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"
Sisäkkäiset avaimet käyttävät pistekirjoitusta: i18n.t('nav.home'). Jos JSON-avaimesi sisältävät pisteitä merkkeinä, python-i18n tulkitsee ne sisäkkäisyyserottimiksi. Vältä pisteitä avainten nimissä.
5

Paikkamerkit ja monikkomuodot

python-i18n tukee paikkamerkkien interpolointia %{name}-syntaksilla ja yksinkertaisia monikkomuotoja 'zero'-, 'one'- ja 'many'-aliavaimilla. Välitä molempien ominaisuuksien arvot i18n.t()-funktiolle avainsana-argumentteina.

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:n monikkomuodot käyttävät kolmea luokkaa: zero, one ja many. Tämä kattaa englannin ja monet muut kielet mutta ei kaikkia CLDR-monikkosääntöjä (few, two, other). Monimutkaisia monikkomuotoja käyttävien kielten, kuten arabian, venäjän ja puolan, reunatapaukset on ehkä käsiteltävä käsin tai edistyneemmällä kirjastolla.
6

Kieliversion vaihtaminen suorituksen aikana

Vaihda aktiivinen kieliversio yleisesti funktiolla i18n.set('locale', code) tai ohita se kutsukohtaisesti locale-avainsana-argumentilla. Tunnista verkkosovelluskehyksissä käyttäjän ensisijainen kieli pyynnöstä ja aseta kieliversio ennen hahmontamista.

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', ...) muuttaa kieliversion yleisesti. Monisäikeisissä verkkopalvelimissa (gunicorn workereineen, Django) tämä voi aiheuttaa kilpailutilanteita, joissa yksi pyyntö vaihtaa kieliversiota toisen hahmontamisen aikana. Vältä tämä kutsukohtaisilla kieliversion ohituksilla tai säiekohtaisella tallennustilalla.
7

Älykäs varakieli python-i18n-locale-chain:illa

Oletusarvoisesti python-i18n tukee vain yhtä varakieliversiota. Kun pt-BR-käyttäjällä ei ole pt-BR-käännöksiä, kirjasto siirtyy suoraan englannin varakieleen ja ohittaa täysin käyttökelpoiset pt-PT-käännökset. python-i18n-locale-chain korjaa tämän määritettävillä varakieliketjuilla, jotka kattavat 75 kieliversiomuotoa.

python-i18n-locale-chain on maksuton avoimen lähdekoodin paketti. Yksi funktiokutsu aktivoi 75 sisäänrakennettua varakieliketjua kiinan, portugalin, espanjan, ranskan, saksan, italian, hollannin, englannin, arabian, norjan ja malaijin alueellisille muodoille.
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()
Vaikuttavimmat testattavat ketjut: pt-BR → pt-PT → pt → en (portugali), es-MX → es-419 → es → en (espanja), zh-Hant-HK → zh-Hant-TW → zh-Hant → en (perinteinen kiina). Ne kattavat tavallisimmat alueelliset varakielitilanteet.
8

Automatisoi käännökset

Kun i18n on otettu käyttöön, käännä kieliversiotiedostosi tekoälyllä. Pyydä IDE-ympäristössäsi tekoälyavustajaasi kääntämään lähdetiedostosi tai käytä i18n Agent:in CLI:tä CI/CD-putkessasi.

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
Käännä vaiheittain. Kun lisäät uusia avaimia lähdetiedostoon, käännä vain diff äläkä luo kaikkia tiedostoja uudelleen. Näin ihmisten tarkistamat käännökset säilyvät.

Automatisoi käännöslaatu

Löydä puuttuvat avaimet ja rikkoutuneet paikkamerkit i18n-validate:lla ennen julkaisua. Testaa käyttöliittymää pseudokäännöksillä i18n-pseudo:n avulla ennen oikeiden käännösten valmistumista.

Tavalliset sudenkuopat

Käännökset palauttavat käsittelemättömiä avaimia

Syitä: load_path on asettamatta tai osoittaa väärään hakemistoon, file_format ei vastaa tiedostopäätteitä tai tiedostonimet eivät vastaa kieliversiokoodeja. Varmista, että i18n.load_path sisältää oikean hakemiston ja tiedostot on nimetty oikein (esimerkiksi en.json, de.json).

YAML-tiedostot eivät lataudu

python-i18n vaatii YAML-tukeen PyYAML:in, jota ei asenneta oletuksena. Asenna se komennolla pip install python-i18n[YAML]. Ilman sitä YAML-tiedostot ohitetaan huomaamatta ja käännökset palauttavat puuttuvien avainten paikkamerkit.

Sisäkkäisten avainten haut epäonnistuvat

python-i18n käyttää sisäkkäisiin avaimiin pistekirjoitusta: i18n.t('nav.home'). Jos JSON käyttää litteitä avaimia, joiden nimessä on pisteitä (esimerkiksi yksi 'nav.home'-avain), kirjasto tulkitsee sen sisäkkäiseksi hauksi ja epäonnistuu. Käytä sen sijaan oikeita sisäkkäisiä JSON-objekteja.

Kieliversiomuutokset vuotavat pyyntöjen välillä

i18n.set('locale', ...) on yleinen toiminto. Monisäikeisillä palvelimilla yksi pyyntö voi vaihtaa kieliversiota toisen hahmontamisen aikana. Käytä yksittäisissä i18n.t()-kutsuissa locale=-avainsana-argumenttia tai aseta kieliversio middlewarella säiekohtaiseen tallennustilaan.

Suositeltu tiedostorakenne

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

Käännä myös:

Kokeile i18n Agent:ia nyt

Pudota käännöstiedostosi tähän

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

tai valitse napsauttamalla

Kohdekielet

Rekisteröitymistä ei tarvitaVälitön arvio

Varakieliketju python-i18n-locale-chain:illa

Kun alueellisesta kieliversiosta, kuten es-419:stä, puuttuu käännösavain, python-i18n siirtyy suoraan oletuskieliversioon eikä tarkista ensin pääkieliversiota 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

Katso varakielioppaastamme kaikki tuetut ohjelmistokehykset ja 75 sisäänrakennettua ketjua. Learn more →

Usein kysytyt kysymykset