Skip to main content

Python i18n: Kompletní průvodce lokalizací

Nastavte python-i18n s překladovými soubory JSON nebo YAML, řešte zástupné symboly a plurály a poté automatizujte překlady pomocí AI.

1

Nainstalujte python-i18n

python-i18n je lehká knihovna pro internacionalizaci v Pythonu. Podporuje překladové soubory JSON a YAML, vnořené klíče, interpolaci zástupných symbolů a pluralizaci bez dalšího nastavování.

Terminal
pip install python-i18n
python-i18n ve výchozím stavu podporuje JSON. Pro překladové soubory YAML nainstalujte volitelnou závislost pomocí pip install python-i18n[YAML], která přidá PyYAML.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Nakonfigurujte překlady

Nastavte formát souboru, přidejte cesty k překladovým souborům a nakonfigurujte výchozí a fallback lokály. Tuto konfiguraci importujte ve vstupním bodě aplikace před jakýmikoli voláními překladu.

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í ukazovat na adresář obsahující Vaše překladové soubory, nikoli na konkrétní soubor. Pokud překlady vracejí syrové klíče, zkontrolujte, že load_path je správně a že názvy souborů odpovídají kódům lokál (např. en.json, de.json).
3

Vytvořte překladové soubory

Vytvořte jeden soubor pro každý jazyk ve formátu JSON nebo YAML. Používejte vnořené klíče pro uspořádání řetězců podle funkce nebo stránky. Zdrojový jazyk (obvykle angličtinu) udržujte jako jediný zdroj pravdy.

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"
  }
}
Pojmenovávejte klíče podle toho, co popisují, ne podle toho, kde se zobrazují: 'cart.item_count' je lepší než 'homepage_cart_label'. Klíče by měly přežít redesign UI.
4

Používejte překlady v kódu

Pro vyhledání přeložených řetězců zavolejte i18n.t() s cestou klíče oddělenou tečkami. Lokálu můžete pro jednotlivé volání přepsat, aniž byste měnili globální nastavení.

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"
Vnořené klíče používají tečkovou notaci: i18n.t('nav.home'). Pokud Vaše klíče v JSON obsahují doslovné tečky, python-i18n je bude interpretovat jako oddělovače vnoření. Vyhněte se tečkám v názvech klíčů.
5

Zástupné symboly a pluralizace

python-i18n podporuje interpolaci zástupných symbolů pomocí syntaxe %{name} a základní pluralizaci pomocí podklíčů 'zero', 'one' a 'many'. Pro obě funkce předávejte do i18n.t() pojmenované argumenty.

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"
Pluralizace v python-i18n používá tři kategorie: zero, one a many. To pokrývá angličtinu a mnoho jazyků, ale nepodporuje plná pravidla množných čísel CLDR (few, two, other). U jazyků jako arabština, ruština nebo polština se složitými tvary množného čísla možná budete muset okrajové případy řešit ručně nebo použít pokročilejší knihovnu.
6

Přepínání lokál za běhu

Aktivní lokálu můžete globálně přepnout pomocí i18n.set('locale', code) nebo ji pro jednotlivé volání přepsat pomocí pojmenovaného argumentu locale. Ve webových frameworkech detekujte preferovaný jazyk uživatele z requestu a lokálu nastavte před vykreslování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', ...) mění lokálu globálně. Ve vícevláknových webových serverech (gunicorn s workery, Django) to může způsobit race condition, kdy jeden request změní lokálu, zatímco jiný se zrovna vykresluje. Používejte přepis lokály pro jednotlivá volání nebo thread-local storage, abyste tomu předešli.
7

Inteligentní fallback locale s python-i18n-locale-chain

Ve výchozím nastavení python-i18n podporuje pouze jedno fallback locale. Když uživatel pt-BR nemá překlady pro pt-BR, knihovna skočí rovnou na anglické fallback locale a ignoruje plně použitelné překlady pt-PT. python-i18n-locale-chain to řeší pomocí konfigurovatelných fallback řetězců, které pokrývají 75 variant locale.

python-i18n-locale-chain je bezplatný open-source balíček. Jediné volání funkce aktivuje 75 vestavěných fallback řetězců pro regionální varianty čínštiny, portugalštiny, španělštiny, francouzštiny, němčiny, italštiny, nizozemštiny, angličtiny, arabštiny, norštiny a malajštiny.
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()
Nejdůležitější řetězce k otestování: pt-BR -> pt-PT -> pt -> en (portugalština), es-MX -> es-419 -> es -> en (španělština), zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en (tradiční čínština). Tyto pokrývají nejběžnější scénáře regionálního fallbacku.
8

Automatizovat překlady

Po dokončení nastavení i18n přeložte své locale soubory pomocí AI. V IDE požádejte svého AI asistenta o překlad zdrojového souboru nebo v CI/CD pipeline použijte 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
Překládejte inkrementálně. Když do zdrojového souboru přidáte nové klíče, přeložte jen rozdíl místo opětovného generování všech souborů. Zachováte tak překlady zkontrolované člověkem.

Automatizovat kvalitu překladů

Zachyťte chybějící klíče a rozbité placeholdery před vydáním pomocí i18n-validate. Otestujte své UI pomocí pseudo-překladů v i18n-pseudo ještě předtím, než dorazí skutečné překlady.

Běžné problémy

Překlady vracejí neformátované klíče

Příčiny: load_path není nastavený nebo ukazuje do nesprávného adresáře, file_format neodpovídá příponám souborů nebo názvy souborů neodpovídají kódům locale. Ověřte, že i18n.load_path obsahuje správný adresář a že soubory jsou správně pojmenované (např. en.json, de.json).

Soubory YAML se nenačítají

python-i18n vyžaduje pro podporu YAML balíček PyYAML, který se ve výchozím nastavení neinstaluje. Nainstalujte jej pomocí pip install python-i18n[YAML]. Bez něj se soubory YAML tiše ignorují a překlady vracejí placeholdery pro chybějící klíč.

Vyhledávání vnořených klíčů selhává

python-i18n používá tečkovou notaci pro vnořené klíče: i18n.t('nav.home'). Pokud Váš JSON používá ploché klíče s tečkami v názvu (např. 'nav.home' jako jeden klíč), knihovna to interpretuje jako vnořené vyhledávání a selže. Použijte místo toho skutečně vnořené JSON objekty.

Změny locale se přenášejí mezi requesty

i18n.set('locale', ...) je globální operace. Ve vícevláknových serverech může jeden request změnit locale ve chvíli, kdy jiný request renderuje. Použijte klíčový argument locale= u jednotlivých volání i18n.t() nebo nastavte locale v úložišti thread-local pomocí middleware.

Doporučená struktura souborů

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

Přeložit také:

Vyzkoušejte i18n Agent nyní

Sem přetáhněte svůj překladový soubor

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

nebo klikněte a vyberte soubor

Cílové jazyky

Bez registraceOkamžitý odhad

Locale fallback s python-i18n-locale-chain

Když v regionálním locale, jako je es-419, chybí překladový klíč, python-i18n skočí rovnou na výchozí locale místo toho, aby nejdříve zkontroloval rodičovské locale 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'],
'}')

# Použití: t('greeting', locale='es') — použije fallback přes řetězec

Podívejte se do našeho průvodce Locale Fallback, kde najdete kompletní seznam podporovaných frameworků a 75 vestavěných řetězců. Learn more →

Často kladené otázky