Skip to main content

Täielik Python i18n-i lokaliseerimise juhend

Seadista python-i18n JSON- või YAML-tõlkefailidega, töötle kohatäitjaid ja mitmusevorme ning automatiseeri seejärel tõlked tehisintellektiga.

1

Paigalda python-i18n

python-i18n on kerge Python'i internatsionaliseerimisteek. See toetab kohe JSON- ja YAML-tõlkefaile, pesastatud võtmeid, kohatäitjate interpoleerimist ning mitmusevorme.

Terminal
pip install python-i18n
python-i18n toetab vaikimisi JSON-i. YAML-tõlkefailide jaoks paigalda valikuline YAML-sõltuvus käsuga pip install python-i18n[YAML], mis lisab PyYAML-i.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Seadista tõlked

Määra failivorming, lisa tõlkefailide teed ning seadista vaike- ja varulokaadid. Impordi see seadistus rakenduse sisenemispunktis enne tõlkekutseid.

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 peab osutama tõlkefaile sisaldavale kataloogile, mitte kindlale failile. Kui tõlked tagastavad töötlemata võtmeid, kontrolli load_pathi ja veendu, et failinimed vastaksid lokaadikoodidele (nt en.json, de.json).
3

Loo tõlkefailid

Loo iga keele jaoks üks JSON- või YAML-fail. Korrasta stringid funktsiooni või lehe järgi pesastatud võtmetega. Hoia lähtekeel, tavaliselt inglise keel, ainsa tõeallikana.

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"
  }
}
Anna võtmetele nimi selle järgi, mida need kirjeldavad, mitte selle järgi, kus need asuvad: 'cart.item_count' on parem kui 'homepage_cart_label'. Võtmed peaksid kasutajaliidese ümberkujundamise üle elama.
4

Kasuta tõlkeid koodis

Tõlgitud stringide otsimiseks kutsu i18n.t() punktidega eraldatud võtmerajaga. Lokaati saab iga kutse puhul alistada ilma globaalset seadistust muutmata.

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"
Pesastatud võtmed kasutavad punktkirja: i18n.t('nav.home'). Kui JSON-võtmed sisaldavad sõnasõnalisi punkte, tõlgendab python-i18n neid pesastamise eraldajatena. Väldi võtmenimedes punkte.
5

Kohatäitjad ja mitmusevormid

python-i18n toetab kohatäitjate interpoleerimist süntaksiga %{name} ning lihtsaid mitmusevorme alamvõtmetega 'zero', 'one' ja 'many'. Edasta mõlema funktsiooni väärtused i18n.t()-le märksõnaargumentidena.

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-i mitmusekäsitlus kasutab kolme kategooriat: zero, one ja many. See katab inglise ja paljud teised keeled, kuid ei toeta täielikke CLDR-i mitmusereegleid (few, two, other). Keerukate mitmusevormidega keelte, nagu araabia, vene või poola keel, puhul võib äärejuhtumeid olla vaja käsitsi või täiustatud teegiga hallata.
6

Lokaadi vahetamine käitusajal

Vaheta aktiivset lokaati globaalselt funktsiooniga i18n.set('locale', code) või alista see iga kutse puhul märksõnaargumendiga locale. Veebiraamistikes tuvasta kasutaja eelistatud keel päringust ja määra lokaat enne renderdamist.

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', ...) muudab lokaati globaalselt. Mitmelõimelistes veebiserverites (gunicorn workeritega, Django) võib see põhjustada võistlusolukorra, kus üks päring muudab lokaati teise renderdamise ajal. Selle vältimiseks kasuta kutsepõhiseid lokaadi alistusi või lõimekohalikku talletust.
7

Nutikas varulokaat python-i18n-locale-chain'iga

Vaikimisi toetab python-i18n ainult üht varulokaati. Kui pt-BR kasutajal pole pt-BR tõlkeid, liigub teek otse inglise varukeelele ning eirab täiesti sobivaid pt-PT tõlkeid. python-i18n-locale-chain parandab selle seadistatavate varulokaadiahelatega, mis katavad 75 lokaadivarianti.

python-i18n-locale-chain on tasuta avatud lähtekoodiga pakett. Üks funktsioonikutse aktiveerib 75 sisseehitatud varulokaadiahelat hiina, portugali, hispaania, prantsuse, saksa, itaalia, hollandi, inglise, araabia, norra ja malai keele piirkondlike variantide jaoks.
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()
Kõige olulisemad testitavad ahelad: pt-BR → pt-PT → pt → en (portugali), es-MX → es-419 → es → en (hispaania), zh-Hant-HK → zh-Hant-TW → zh-Hant → en (traditsiooniline hiina). Need katavad kõige levinumad piirkondliku varulokaadi olukorrad.
8

Automatiseeri tõlked

Kui i18n-i seadistus on valmis, tõlgi lokaadifailid tehisintellektiga. Palu IDE-s oma tehisintellekti abilisel lähtefail tõlkida või kasuta CI/CD-konveieris i18n Agent'i CLI-d.

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
Tõlgi järk-järgult. Kui lisad lähtefaili uusi võtmeid, tõlgi kõigi failide uuesti loomise asemel ainult diff. Nii säilivad inimeste ülevaadatud tõlked.

Automatiseeri tõlkekvaliteet

Leia i18n-validate'i abil puuduvad võtmed ja katkised kohatäitjad enne avaldamist. Testi kasutajaliidest i18n-pseudo abil pseudotõlgetega enne päris tõlgete saabumist.

Levinud komistuskivid

Tõlked tagastavad töötlemata võtmeid

Põhjused: load_path pole määratud või osutab valele kataloogile, file_format ei vasta faililaienditele või failinimed ei vasta lokaadikoodidele. Veendu, et i18n.load_path sisaldaks õiget kataloogi ja failid oleks õigesti nimetatud (nt en.json, de.json).

YAML-faile ei laadita

python-i18n vajab YAML-i toe jaoks PyYAML-i, mida vaikimisi ei paigaldata. Paigalda see käsuga pip install python-i18n[YAML]. Ilma selleta eiratakse YAML-faile märkamatult ning tõlked tagastavad puuduvate võtmete kohatäitjad.

Pesastatud võtmete otsingud nurjuvad

python-i18n kasutab pesastatud võtmete jaoks punktkirja: i18n.t('nav.home'). Kui JSON kasutab lamedaid võtmeid, mille nimes on punktid (nt üks võti 'nav.home'), tõlgendab teek seda pesastatud otsinguna ja nurjub. Kasuta selle asemel päriselt pesastatud JSON-objekte.

Lokaadimuudatused lekivad päringute vahel

i18n.set('locale', ...) on globaalne toiming. Mitmelõimelistes serverites võib üks päring muuta lokaati teise renderdamise ajal. Kasuta üksikutes i18n.t() kutsetes märksõnaargumenti locale= või määra lokaat middleware'iga lõimekohalikku talletusse.

Soovituslik failistruktuur

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

Tõlgi ka:

Proovi i18n Agent'i kohe

Kukuta tõlkefail siia

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

või klõpsa faili valimiseks

Sihtkeeled

Registreerumine pole vajalikKohene hinnang

Varulokaat python-i18n-locale-chain'iga

Kui piirkondlikust lokaadist, näiteks es-419-st, puudub tõlkevõti, liigub python-i18n otse vaikelokaadile ega kontrolli esmalt põhilokaati 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

Vaata meie varulokaadi juhendist kõigi toetatud raamistike ja 75 sisseehitatud ahela loendit. Learn more →

Korduma kippuvad küsimused