Skip to main content

Išsamus Python i18n lokalizavimo vadovas

Sukonfigūruokite python-i18n su JSON arba YAML vertimo failais, apdorokite vietos rezervavimo ženklus bei daugiskaitą ir automatizuokite vertimus naudodami DI.

1

Įdiegti python-i18n

python-i18n yra nedidelė Python internacionalizavimo biblioteka. Ji iškart palaiko JSON ir YAML vertimo failus, įdėtinius raktus, vietos rezervavimo ženklų interpoliavimą ir daugiskaitą.

Terminal
pip install python-i18n
python-i18n pagal numatytąją nuostatą palaiko JSON. YAML vertimo failams įdiekite pasirenkamą YAML priklausomybę su pip install python-i18n[YAML], kuri prideda PyYAML.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Sukonfigūruoti vertimus

Nustatykite failų formatą, pridėkite vertimo failų kelius ir sukonfigūruokite numatytąją bei atsarginę lokales. Importuokite šią konfigūraciją programos įėjimo taške prieš bet kurį vertimo iškvietimą.

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 turi nurodyti katalogą, kuriame yra vertimo failai, o ne konkretų failą. Jei vertimai grąžina neapdorotus raktus, patikrinkite, ar load_path tinkamas ir ar failų pavadinimai atitinka lokalių kodus (pvz., en.json, de.json).
3

Sukurti vertimo failus

Sukurkite po vieną kiekvienos kalbos failą JSON arba YAML formatu. Eilutes pagal funkciją ar puslapį tvarkykite įdėtiniais raktais. Šaltinio kalbą (paprastai anglų) laikykite vieninteliu patikimu šaltiniu.

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"
  }
}
Raktus pavadinkite pagal tai, ką jie apibūdina, o ne kur rodomi: „cart.item_count“ geriau nei „homepage_cart_label“. Raktai turėtų išlikti pertvarkius UI.
4

Naudoti vertimus kode

Iškvieskite i18n.t() su taškais atskirtu rakto keliu išverstoms eilutėms rasti. Kiekviename iškvietime galite pakeisti lokalę nekeisdami visuotinės nuostatos.

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"
Įdėtiniai raktai naudoja taškinį žymėjimą: i18n.t('nav.home'). Jei JSON raktuose yra tikrų taškų, python-i18n interpretuos juos kaip įdėjimo skyriklius. Raktų pavadinimuose taškų venkite.
5

Vietos rezervavimo ženklai ir daugiskaita

python-i18n palaiko vietos rezervavimo ženklų interpoliavimą su %{name} sintakse ir pagrindinę daugiskaitą su papildomais raktais 'zero', 'one' bei 'many'. Abiem atvejams perduokite raktažodžių argumentus į 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"
python-i18n daugiskaita naudoja tris kategorijas: zero, one ir many. Jos apima anglų ir daugelį kitų kalbų, bet nepalaiko visų CLDR daugiskaitos taisyklių (few, two, other). Kalbose su sudėtingomis daugiskaitos formomis, pavyzdžiui, arabų, rusų ar lenkų, kraštinius atvejus gali tekti apdoroti rankomis arba naudoti išmanesnę biblioteką.
6

Lokalės keitimas vykdymo metu

Pakeiskite aktyvią lokalę visuotinai su i18n.set('locale', code) arba kiekvienam iškvietimui atskirai su raktažodžio argumentu locale. Interneto sistemose aptikite pageidaujamą naudotojo kalbą iš užklausos ir nustatykite lokalę prieš atvaizduodami.

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', ...) pakeičia lokalę visuotinai. Kelių gijų interneto serveriuose (gunicorn su darbuotojais, Django) tai gali sukelti lenktyniavimo sąlygas: viena užklausa pakeičia lokalę, kai kita dar atvaizduojama. Kad to išvengtumėte, naudokite lokalės pakeitimus kiekviename iškvietime arba gijos vietinę saugyklą.
7

Išmani atsarginė lokalė su python-i18n-locale-chain

Pagal numatytąją nuostatą python-i18n palaiko tik vieną atsarginę lokalę. Kai pt-BR naudotojas neturi pt-BR vertimų, biblioteka iškart pereina prie anglų kalbos ir nepaiso puikių pt-PT vertimų. python-i18n-locale-chain tai ištaiso konfigūruojamomis atsarginėmis grandinėmis, apimančiomis 75 lokalių variantus.

python-i18n-locale-chain yra nemokamas atvirojo kodo paketas. Vienas funkcijos iškvietimas aktyvina 75 integruotas atsargines grandines kinų, portugalų, ispanų, prancūzų, vokiečių, italų, nyderlandų, anglų, arabų, norvegų ir malajų kalbų regioniniams variantams.
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()
Svarbiausios išbandytinos grandinės: pt-BR -> pt-PT -> pt -> en (portugalų), es-MX -> es-419 -> es -> en (ispanų), zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en (tradicinė kinų). Jos apima dažniausius regioninius atsarginius scenarijus.
8

Automatizuoti vertimus

Baigę i18n sąranką išverskite lokalės failus naudodami DI. IDE paprašykite DI asistento išversti šaltinio failą arba CI/CD konvejeryje naudokite i18n Agent CLI.

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
Verskite palaipsniui. Pridėję naujų raktų prie šaltinio failo išverskite tik skirtumą, o ne generuokite visus failus iš naujo. Taip išsaugomi žmonių peržiūrėti vertimai.

Automatizuoti vertimo kokybę

Naudodami i18n-validate prieš išleidimą aptikite trūkstamus raktus ir sugadintus vietos rezervavimo ženklus. Kol dar nėra tikrų vertimų, patikrinkite UI su i18n-pseudo pseudoverstimais.

Dažnos klaidos

Vertimai grąžina neapdorotus raktus

Priežastys: load_path nenustatytas arba nurodo netinkamą katalogą, file_format neatitinka failų plėtinių arba failų pavadinimai neatitinka lokalių kodų. Patikrinkite, ar i18n.load_path yra tinkamas katalogas ir ar failai tinkamai pavadinti (pvz., en.json, de.json).

YAML failai neįkeliami

YAML palaikymui python-i18n reikia PyYAML, tačiau jis pagal numatytąją nuostatą neįdiegtas. Įdiekite su pip install python-i18n[YAML]. Be jo YAML failai tyliai ignoruojami, o vertimai grąžina trūkstamo rakto vietos rezervavimo ženklus.

Įdėtų raktų paieškos nepavyksta

python-i18n įdėtiems raktams naudoja taškinį žymėjimą: i18n.t('nav.home'). Jei JSON naudoja plokščius raktus su taškais pavadinime (pvz., 'nav.home' kaip vieną raktą), biblioteka tai interpretuoja kaip įdėtinę paiešką ir jos neatlieka. Vietoje to naudokite tikrus įdėtinius JSON objektus.

Lokalių pakeitimai persidengia tarp užklausų

i18n.set('locale', ...) yra visuotinė operacija. Kelių gijų serveriuose viena užklausa gali pakeisti lokalę, kai kita dar atvaizduojama. Atskiruose i18n.t() iškvietimuose naudokite raktažodžio argumentą locale= arba nustatykite lokalę gijos vietinėje saugykloje per tarpinę programinę įrangą.

Rekomenduojama failų struktūra

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

Taip pat verskite:

Išbandykite i18n Agent dabar

Nuvilkite vertimo failą čia

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

arba spustelėkite norėdami pasirinkti

Tikslinės kalbos

Registruotis nereikiaMomentinis įvertis

Atsarginė lokalė su python-i18n-locale-chain

Kai regioninėje lokalėje, pavyzdžiui, es-419, trūksta vertimo rakto, python-i18n iškart pereina prie numatytosios lokalės, užuot pirmiausia patikrinęs pirminę lokalę 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

Visą palaikomų sistemų sąrašą ir 75 integruotas grandines rasite mūsų atsarginių lokalių vadove. Learn more →

Dažnai užduodami klausimai