Skip to main content

Python i18n: kompletný sprievodca lokalizáciou

Nastavte python-i18n s prekladovými súbormi JSON alebo YAML, spracujte zástupné symboly a množné číslo a potom automatizujte preklady pomocou AI.

1

Nainštalujte python-i18n

python-i18n je ľahká internacionalizačná knižnica pre Python. Priamo podporuje prekladové súbory JSON a YAML, vnorené kľúče, interpoláciu zástupných symbolov a množné číslo.

Terminal
pip install python-i18n
python-i18n predvolene podporuje JSON. Pre prekladové súbory YAML nainštalujte voliteľnú závislosť príkazom pip install python-i18n[YAML], ktorá pridá PyYAML.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Nakonfigurujte preklady

Nastavte formát súborov, pridajte cesty k prekladovým súborom a nakonfigurujte predvolenú aj záložnú lokalitu. Túto konfiguráciu importujte vo vstupnom bode aplikácie pred prvým volaním prekladu.

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 musí smerovať na priečinok s prekladovými súbormi, nie na konkrétny súbor. Ak preklady vracajú nespracované kľúče, skontrolujte správnosť load_path a zhodu názvov súborov s kódmi lokalít (napr. en.json, de.json).
3

Vytvorte prekladové súbory

Vytvorte jeden súbor pre každý jazyk vo formáte JSON alebo YAML. Pomocou vnorených kľúčov usporiadajte texty podľa funkcie alebo stránky. Zdrojový jazyk, zvyčajne angličtinu, zachovajte ako hlavný zdroj.

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"
  }
}
Kľúče pomenúvajte podľa ich významu, nie podľa miesta zobrazenia: 'cart.item_count' je lepšie ako 'homepage_cart_label'. Kľúče by mali zostať platné aj po zmene návrhu používateľského rozhrania.
4

Používajte preklady v kóde

Volajte i18n.t() s cestou kľúča oddelenou bodkami, aby ste získali preložené texty. Lokalitu môžete prepísať pre jednotlivé volanie bez zmeny globálneho nastavenia.

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"
Vnorené kľúče používajú bodkovú notáciu: i18n.t('nav.home'). Ak kľúče JSON obsahujú doslovné bodky, python-i18n ich vyhodnotí ako oddeľovače vnorenia. V názvoch kľúčov sa bodkám vyhnite.
5

Zástupné symboly a množné číslo

python-i18n podporuje interpoláciu zástupných symbolov so syntaxou %{name} a základné množné číslo pomocou podkľúčov 'zero', 'one' a 'many'. Pre obe funkcie odovzdajte pomenované argumenty do 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žné číslo v python-i18n používa tri kategórie: zero, one a many. To postačuje pre angličtinu a mnohé ďalšie jazyky, ale nepodporuje všetky pravidlá CLDR (few, two, other). Pri jazykoch so zložitými formami, ako sú arabčina, ruština alebo poľština, môže byť potrebné spracovať okrajové prípady ručne alebo použiť pokročilejšiu knižnicu.
6

Prepínanie lokality počas behu

Aktívnu lokalitu globálne prepnite pomocou i18n.set('locale', code) alebo ju pre jednotlivé volanie prepíšte pomenovaným argumentom locale. Vo webových frameworkoch zistite preferovaný jazyk používateľa zo žiadosti a lokalitu nastavte pred vykreslením.

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', ...) mení lokalitu globálne. Vo viacvláknových webových serveroch (gunicorn s workers, Django) to môže spôsobiť súbeh, pri ktorom jedna žiadosť zmení lokalitu počas vykresľovania inej. Používajte prepísanie lokality pre jednotlivé volania alebo lokálne úložisko vlákna.
7

Inteligentná záložná lokalita s python-i18n-locale-chain

python-i18n predvolene podporuje iba jednu záložnú lokalitu. Ak používateľ pt-BR nemá preklady pt-BR, knižnica prejde priamo na angličtinu a ignoruje dostupné preklady pt-PT. python-i18n-locale-chain to rieši konfigurovateľnými záložnými reťazcami pre 75 variantov lokalít.

python-i18n-locale-chain je bezplatný balík s otvoreným zdrojovým kódom. Jediné volanie funkcie aktivuje 75 vstavaných záložných reťazcov pre regionálne varianty čínštiny, portugalčiny, španielčiny, francúzštiny, nemčiny, taliančiny, holandčiny, angličtiny, arabčiny, nórčiny a malajčiny.
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()
Najdôležitejšie reťazce na testovanie: pt-BR -> pt-PT -> pt -> en (portugalčina), es-MX -> es-419 -> es -> en (španielčina), zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en (tradičná čínština). Pokrývajú najbežnejšie regionálne scenáre záložných lokalít.
8

Automatizujte preklady

Po dokončení nastavenia i18n preložte lokalizačné súbory pomocou AI. V IDE požiadajte asistenta AI o preklad zdrojového súboru alebo použite CLI i18n Agent v pipeline CI/CD.

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
Prekladajte priebežne. Po pridaní nových kľúčov do zdrojového súboru preložte iba rozdiel namiesto opätovného vytvorenia všetkých súborov. Zachováte tým preklady skontrolované človekom.

Automatizujte kontrolu kvality prekladov

Pomocou i18n-validate odhaľte chýbajúce kľúče a poškodené zástupné symboly ešte pred vydaním. Používateľské rozhranie otestujte pseudoprekladmi z i18n-pseudo pred príchodom skutočných prekladov.

Časté problémy

Preklady vracajú nespracované kľúče

Príčiny: load_path nie je nastavený alebo smeruje do nesprávneho priečinka, file_format nezodpovedá príponám súborov alebo názvy súborov nezodpovedajú kódom lokalít. Overte, že i18n.load_path obsahuje správny priečinok a súbory sú správne pomenované (napr. en.json, de.json).

Súbory YAML sa nenačítavajú

python-i18n vyžaduje na podporu YAML balík PyYAML, ktorý sa predvolene neinštaluje. Nainštalujte ho príkazom pip install python-i18n[YAML]. Bez neho sa súbory YAML potichu ignorujú a preklady vracajú zástupné symboly chýbajúcich kľúčov.

Vyhľadávanie vnorených kľúčov zlyháva

python-i18n používa pre vnorené kľúče bodkovú notáciu: i18n.t('nav.home'). Ak JSON používa ploché kľúče s bodkami v názve (napr. 'nav.home' ako jediný kľúč), knižnica ho vyhodnotí ako vnorené vyhľadávanie a neuspeje. Namiesto toho použite skutočné vnorené objekty JSON.

Zmeny lokality prenikajú medzi žiadosťami

i18n.set('locale', ...) je globálna operácia. Vo viacvláknových serveroch môže jedna žiadosť zmeniť lokalitu počas vykresľovania inej. Pri jednotlivých volaniach i18n.t() použite pomenovaný argument locale= alebo nastavte lokalitu v lokálnom úložisku vlákna pomocou middleware.

Odporúčaná štruktúra súborov

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

Prekladajte aj:

Vyskúšajte i18n Agent teraz

Potiahnite súbor na preklad sem

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

alebo kliknite a vyberte súbor

Cieľové jazyky

Bez registrácieOkamžitý odhad

Záložná lokalita s python-i18n-locale-chain

Keď chýba kľúč prekladu v regionálnej lokalite, ako je es-419, python-i18n prejde priamo na predvolenú lokalitu namiesto toho, aby najprv skontroloval nadradenú lokalitu 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

V našom sprievodcovi záložnými lokalitami nájdete úplný zoznam podporovaných frameworkov a 75 vstavaných reťazcov. Learn more →

Často kladené otázky