Skip to main content

Pilnīgs Python i18n lokalizācijas ceļvedis

Iestatiet python-i18n ar JSON vai YAML tulkošanas failiem, apstrādājiet vietturus un daudzskaitli, pēc tam automatizējiet tulkošanu ar MI.

1

Instalēt python-i18n

python-i18n ir viegla Python internacionalizācijas bibliotēka. Tā uzreiz atbalsta JSON un YAML tulkošanas failus, ligzdotas atslēgas, vietturu interpolāciju un daudzskaitli.

Terminal
pip install python-i18n
python-i18n pēc noklusējuma atbalsta JSON. YAML tulkošanas failiem instalējiet izvēles YAML atkarību ar pip install python-i18n[YAML], kas pievieno PyYAML.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Konfigurēt tulkojumus

Iestatiet failu formātu, pievienojiet tulkošanas failu ceļus un konfigurējiet noklusējuma un atkāpšanās lokalizācijas. Importējiet šo konfigurāciju lietotnes ieejas punktā pirms jebkura tulkošanas izsaukuma.

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 jānorāda uz direktoriju, kurā atrodas tulkošanas faili, nevis uz konkrētu failu. Ja tulkojumi atgriež neapstrādātas atslēgas, pārbaudiet, vai load_path ir pareizs un failu nosaukumi atbilst lokalizāciju kodiem (piemēram, en.json, de.json).
3

Izveidot tulkošanas failus

Izveidojiet vienu failu katrai valodai JSON vai YAML formātā. Sakārtojiet virknes pēc funkcijas vai lapas ar ligzdotām atslēgām. Avota valodu (parasti angļu) uzturiet kā vienīgo patiesības avotu.

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"
  }
}
Nosauciet atslēgas pēc tā, ko tās apraksta, nevis kur tās parādās: „cart.item_count“ ir labāks par „homepage_cart_label“. Atslēgām jāiztur UI pārveide.
4

Izmantot tulkojumus kodā

Izsauciet i18n.t() ar punktiem atdalītu atslēgas ceļu, lai atrastu tulkotas virknes. Katrā izsaukumā varat pārrakstīt lokalizāciju, nemainot globālo iestatījumu.

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"
Ligzdotās atslēgas izmanto punktu notāciju: i18n.t('nav.home'). Ja JSON atslēgās ir burtiski punkti, python-i18n tos interpretēs kā ligzdošanas atdalītājus. Izvairieties no punktiem atslēgu nosaukumos.
5

Vietturi un daudzskaitlis

python-i18n atbalsta vietturu interpolāciju ar %{name} sintaksi un daudzskaitļa pamatgadījumus ar apakšatslēgām 'zero', 'one' un 'many'. Abām funkcijām nododiet atslēgvārdu 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 daudzskaitlis izmanto trīs kategorijas: zero, one un many. Tās aptver angļu un daudzas citas valodas, bet neatbalsta visas CLDR daudzskaitļa kārtulas (few, two, other). Valodām ar sarežģītām daudzskaitļa formām, piemēram, arābu, krievu vai poļu, robežgadījumi var būt jāapstrādā manuāli vai jāizmanto attīstītāka bibliotēka.
6

Lokalizācijas pārslēgšana izpildlaikā

Pārslēdziet aktīvo lokalizāciju globāli ar i18n.set('locale', code) vai pārrakstiet katram izsaukumam ar atslēgvārda argumentu locale. Tīmekļa sistēmās nosakiet lietotāja vēlamo valodu no pieprasījuma un iestatiet lokalizāciju pirms atveides.

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', ...) maina lokalizāciju globāli. Daudzpavedienu tīmekļa serveros (gunicorn ar darbiniekiem, Django) tas var radīt sacensības apstākļus: viens pieprasījums maina lokalizāciju, kamēr cits tiek atveidots. Lai to novērstu, izmantojiet lokalizācijas pārrakstīšanu katrā izsaukumā vai pavedienam lokālu krātuvi.
7

Vieda lokalizācijas atkāpšanās ar python-i18n-locale-chain

Pēc noklusējuma python-i18n atbalsta tikai vienu atkāpšanās lokalizāciju. Ja pt-BR lietotājam nav pt-BR tulkojumu, bibliotēka uzreiz pāriet uz angļu valodu un ignorē labus pt-PT tulkojumus. python-i18n-locale-chain to novērš ar konfigurējamām atkāpšanās ķēdēm, kas aptver 75 lokalizāciju variantus.

python-i18n-locale-chain ir bezmaksas atvērtā pirmkoda pakotne. Viens funkcijas izsaukums aktivizē 75 iebūvētas atkāpšanās ķēdes ķīniešu, portugāļu, spāņu, franču, vācu, itāļu, nīderlandiešu, angļu, arābu, norvēģu un malajiešu valodu reģionālajiem variantiem.
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()
Svarīgākās pārbaudāmās ķēdes: pt-BR -> pt-PT -> pt -> en (portugāļu), es-MX -> es-419 -> es -> en (spāņu), zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en (tradicionālā ķīniešu). Tās aptver izplatītākos reģionālās atkāpšanās scenārijus.
8

Automatizēt tulkošanu

Kad i18n iestatīšana ir pabeigta, tulkojiet lokalizācijas failus ar MI. IDE lūdziet MI asistentam iztulkot avota failu vai CI/CD konveijerā izmantojiet 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
Tulkojiet pakāpeniski. Pievienojot avota failam jaunas atslēgas, tulkojiet tikai izmaiņas, nevis ģenerējiet visus failus no jauna. Tas saglabā cilvēku pārskatītos tulkojumus.

Automatizēt tulkojumu kvalitāti

Ar i18n-validate pirms izlaišanas atrodiet trūkstošās atslēgas un bojātos vietturus. Kamēr īstie tulkojumi vēl nav gatavi, pārbaudiet UI ar i18n-pseudo pseidotulkojumiem.

Biežākās kļūdas

Tulkojumi atgriež neapstrādātas atslēgas

Iemesli: load_path nav iestatīts vai norāda nepareizu direktoriju, file_format neatbilst failu paplašinājumiem vai failu nosaukumi neatbilst lokalizāciju kodiem. Pārbaudiet, vai i18n.load_path ietver pareizo direktoriju un faili ir pareizi nosaukti (piemēram, en.json, de.json).

YAML faili netiek ielādēti

YAML atbalstam python-i18n vajadzīgs PyYAML, taču tas pēc noklusējuma nav instalēts. Instalējiet ar pip install python-i18n[YAML]. Bez tā YAML faili tiek klusām ignorēti, un tulkojumi atgriež trūkstošu atslēgu vietturus.

Ligzdotu atslēgu meklēšana neizdodas

python-i18n ligzdotām atslēgām izmanto punktu notāciju: i18n.t('nav.home'). Ja JSON izmanto plakanas atslēgas ar punktiem nosaukumā (piemēram, 'nav.home' kā vienu atslēgu), bibliotēka to interpretē kā ligzdotu meklēšanu un neizdodas. Tā vietā izmantojiet īstus ligzdotus JSON objektus.

Lokalizāciju izmaiņas pārklājas starp pieprasījumiem

i18n.set('locale', ...) ir globāla darbība. Daudzpavedienu serveros viens pieprasījums var mainīt lokalizāciju, kamēr cits tiek atveidots. Atsevišķos i18n.t() izsaukumos izmantojiet atslēgvārda argumentu locale= vai ar starpprogrammatūru iestatiet lokalizāciju pavedienam lokālā krātuvē.

Ieteicamā failu 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
└── ...

Tulkojiet arī:

Izmēģiniet i18n Agent tūlīt

Nometiet tulkošanas failu šeit

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

vai noklikšķiniet, lai izvēlētos

Mērķa valodas

Reģistrācija nav vajadzīgaTūlītēja tāme

Lokalizācijas atkāpšanās ar python-i18n-locale-chain

Ja reģionālajā lokalizācijā, piemēram, es-419, trūkst tulkojuma atslēgas, python-i18n uzreiz pāriet uz noklusējuma lokalizāciju, nevis vispirms pārbauda vecāklokalizāciju 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

Pilnu atbalstīto sistēmu sarakstu un 75 iebūvētās ķēdes skatiet mūsu lokalizāciju atkāpšanās ceļvedī. Learn more →

Bieži uzdotie jautājumi