Skip to main content

Python i18n: teljes lokalizációs útmutató

Állítsa be a python-i18n csomagot JSON- vagy YAML-fordításfájlokkal, kezelje a helyőrzőket és többes számokat, majd automatizálja a fordítást mesterséges intelligenciával.

1

A python-i18n telepítése

A python-i18n könnyű nemzetköziesítési könyvtár Pythonhoz. Azonnal támogatja a JSON- és YAML-fordításfájlokat, az egymásba ágyazott kulcsokat, a helyőrző-interpolációt és a többes számot.

Terminal
pip install python-i18n
A python-i18n alapértelmezés szerint támogatja a JSON-t. YAML-fordításfájlokhoz telepítse a választható YAML-függőséget a pip install python-i18n[YAML] paranccsal, amely hozzáadja a PyYAML csomagot.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Fordítások beállítása

Állítsa be a fájlformátumot, adja hozzá a fordításfájlok elérési útjait, és adja meg az alapértelmezett és tartalék területeket. Minden fordítási hívás előtt importálja ezt a konfigurációt az alkalmazás belépési pontján.

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)
A load_path értéknek a fordításfájlokat tartalmazó könyvtárra, nem egy adott fájlra kell mutatnia. Ha a fordítások nyers kulcsokat adnak vissza, ellenőrizze a load_path helyességét és azt, hogy a fájlnevek megfelelnek-e a területkódoknak (például en.json, de.json).
3

Fordítási fájlok létrehozása

Hozzon létre nyelvenként egy JSON- vagy YAML-fájlt. A karakterláncokat funkció vagy oldal szerint egymásba ágyazott kulcsokkal rendezze. A forrásnyelvet (általában angolt) tartsa az igazság egyetlen forrásának.

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"
  }
}
A kulcsokat az általuk leírt fogalomról, ne a megjelenési helyükről nevezze el: a „cart.item_count” jobb a „homepage_cart_label” névnél. A kulcsoknak a felület újratervezését is túl kell élniük.
4

Fordítások használata a kódban

Ponttal elválasztott kulcsútvonallal hívja meg az i18n.t() függvényt a lefordított karakterláncok kereséséhez. Hívásonként felülírhatja a területet a globális beállítás módosítása nélkül.

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"
Az egymásba ágyazott kulcsok pontjelölést használnak: i18n.t('nav.home'). Ha JSON-kulcsai tényleges pontot tartalmaznak, a python-i18n beágyazási elválasztóként értelmezi. Kerülje a pontot a kulcsnevekben.
5

Helyőrzők és többes szám

A python-i18n a %{name} szintaxissal helyőrző-interpolációt, a 'zero', 'one' és 'many' alkulcsokkal alapvető többes számot támogat. Mindkét funkcióhoz kulcsszóargumentumokat adjon át az i18n.t() függvénynek.

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"
A python-i18n többesszám-kezelése három kategóriát használ: zero, one és many. Ez az angolt és sok nyelvet lefed, de nem támogatja a teljes CLDR-szabálykészletet (few, two, other). Összetett többes számú nyelveknél, például arabnál, orosznál vagy lengyelnél kézzel kellhet kezelnie a szélső eseteket, vagy fejlettebb könyvtárat kell használnia.
6

Területváltás futásidőben

Az aktív területet globálisan az i18n.set('locale', code) hívással váltsa, vagy hívásonként írja felül a locale kulcsszóargumentummal. Webes keretrendszerekben észlelje a felhasználó előnyben részesített nyelvét a kérésből, és renderelés előtt állítsa be a területet.

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")
Az i18n.set('locale', ...) globálisan módosítja a területet. Többszálú webszervereken (worker-alapú gunicorn, Django) ez versenyhelyzetet okozhat: az egyik kérés megváltoztatja a területet, miközben a másik renderel. Ennek elkerüléséhez használjon hívásonkénti terület-felülírást vagy szálspecifikus tárolót.
7

Intelligens területi tartalék python-i18n-locale-chain használatával

Alapértelmezés szerint a python-i18n csak egyetlen tartalékterületet támogat. Ha egy pt-BR felhasználónak nincs pt-BR fordítása, a könyvtár közvetlenül az angol tartalékra vált, figyelmen kívül hagyva a megfelelő pt-PT fordítást. A python-i18n-locale-chain ezt 75 területi változatot lefedő, beállítható tartalékláncokkal javítja.

A python-i18n-locale-chain ingyenes, nyílt forráskódú csomag. Egyetlen függvényhívás aktivál 75 beépített tartalékláncot a kínai, portugál, spanyol, francia, német, olasz, holland, angol, arab, norvég és maláj regionális változataihoz.
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()
A legfontosabb tesztelendő láncok: pt-BR -> pt-PT -> pt -> en (portugál), es-MX -> es-419 -> es -> en (spanyol), zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en (hagyományos kínai). Ezek lefedik a leggyakoribb regionális tartalékhelyzeteket.
8

Fordítások automatizálása

A kész i18n-beállítással AI segítségével fordítsa le a területi fájlokat. Az IDE-ben kérje meg AI-asszisztensét a forrásfájl lefordítására, vagy használja az i18n Agent CLI-t a CI/CD-folyamatban.

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
Fordítson fokozatosan. Új kulcsok forrásfájlhoz adásakor csak a különbséget fordítsa le az összes fájl újragenerálása helyett. Így megmaradnak az ember által ellenőrzött fordítások.

A fordítási minőség automatizálása

Az i18n-validate segítségével még kiadás előtt találja meg a hiányzó kulcsokat és hibás helyőrzőket. Az i18n-pseudo használatával valódi fordítások beérkezése előtt tesztelje a felületet pszeudofordításokkal.

Gyakori buktatók

A fordítások nyers kulcsokat adnak vissza

Okok: a load_path nincs beállítva vagy hibás könyvtárra mutat, a file_format nem egyezik a fájlkiterjesztésekkel, vagy a fájlnevek nem egyeznek a területkódokkal. Ellenőrizze, hogy az i18n.load_path a megfelelő könyvtárat tartalmazza-e, és a fájlnevek helyesek-e (például en.json, de.json).

A YAML-fájlok nem töltődnek be

A python-i18n PyYAML csomagot igényel a YAML-támogatáshoz, de ez alapértelmezés szerint nincs telepítve. Telepítse a pip install python-i18n[YAML] paranccsal. Enélkül a YAML-fájlok csendben kimaradnak, a fordítások pedig hiányzókulcs-helyőrzőt adnak vissza.

Az egymásba ágyazott kulcsok keresése meghiúsul

A python-i18n pontjelölést használ egymásba ágyazott kulcsokhoz: i18n.t('nav.home'). Ha a JSON lapos, pontot tartalmazó kulcsokat használ (például egyetlen „nav.home” kulcsot), a könyvtár egymásba ágyazott keresésként értelmezi, és meghiúsul. Használjon ténylegesen egymásba ágyazott JSON-objektumokat.

A területváltások átszivárognak a kérések között

Az i18n.set('locale', ...) globális művelet. Többszálú szervereken az egyik kérés módosíthatja a területet, miközben egy másik renderel. Használja a locale= kulcsszóargumentumot az egyes i18n.t() hívásoknál, vagy middleware segítségével állítsa be a területet szálspecifikus tárolóban.

Ajánlott fájlszerkezet

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

Also translate:

Try i18n Agent Now

Drop your translation file here

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

or click to browse

Target languages

No signup requiredInstant estimate

Területi tartalék python-i18n-locale-chain használatával

Ha egy fordítási kulcs hiányzik egy regionális területi beállításból, például az es-419 változatból, a python-i18n az es szülőterület ellenőrzése helyett közvetlenül az alapértelmezett területre vált.

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'],
'}')

# Használat: t('greeting', locale='es') — végigjárja a tartalékláncot

A támogatott keretrendszerek és a 75 beépített lánc teljes listájáért tekintse meg Területi tartalék útmutatónkat. Learn more →

Gyakran Ismételt Kérdések