Skip to main content

Python i18n: ghidul complet pentru localizare

Configurați python-i18n cu fișiere de traducere JSON sau YAML, gestionați substituenții și formele de plural, apoi automatizați traducerile cu IA.

1

Instalați python-i18n

python-i18n este o bibliotecă simplă de internaționalizare pentru Python. Acceptă fișiere de traducere JSON și YAML, chei imbricate, interpolarea substituenților și pluralizarea fără configurări suplimentare.

Terminal
pip install python-i18n
python-i18n acceptă implicit JSON. Pentru fișierele de traducere YAML, instalați dependența YAML opțională cu pip install python-i18n[YAML], care adaugă PyYAML.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Configurați traducerile

Setați formatul fișierelor, adăugați căile către fișierele de traducere și configurați setarea regională implicită și pe cea de rezervă. Importați această configurație în punctul de intrare al aplicației înainte de orice apel de traducere.

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 trebuie să indice directorul care conține fișierele de traducere, nu un anumit fișier. Dacă traducerile returnează cheile brute, verificați dacă load_path este corect și dacă numele fișierelor corespund codurilor setărilor regionale (de exemplu, en.json, de.json).
3

Creați fișierele de traducere

Creați câte un fișier pentru fiecare limbă, în format JSON sau YAML. Utilizați chei imbricate pentru a organiza șirurile după funcționalitate sau pagină. Păstrați limba-sursă, de obicei engleza, drept unica sursă de referință.

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"
  }
}
Denumiți cheile după ceea ce descriu, nu după locul unde apar: 'cart.item_count' este mai potrivit decât 'homepage_cart_label'. Cheile trebuie să rămână valabile după reproiectarea interfeței.
4

Utilizați traducerile în cod

Apelați i18n.t() cu o cale de chei separată prin puncte pentru a căuta șirurile traduse. Puteți înlocui setarea regională pentru fiecare apel fără a modifica setarea globală.

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"
Cheile imbricate utilizează notația cu puncte: i18n.t('nav.home'). Dacă numele cheilor JSON conțin puncte literale, python-i18n le va interpreta drept separatoare de imbricare. Evitați punctele în numele cheilor.
5

Substituenți și pluralizare

python-i18n acceptă interpolarea substituenților cu sintaxa %{name} și pluralizarea de bază prin subcheile 'zero', 'one' și 'many'. Transmiteți argumente cu cuvinte-cheie către i18n.t() pentru ambele funcționalități.

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"
Pluralizarea din python-i18n utilizează trei categorii: zero, one și many. Acestea acoperă engleza și numeroase alte limbi, dar nu acceptă toate regulile de plural CLDR (few, two, other). Pentru limbi precum araba, rusa sau poloneza, care au forme de plural complexe, poate fi necesar să gestionați manual cazurile-limită sau să utilizați o bibliotecă mai avansată.
6

Schimbarea setării regionale în timpul execuției

Schimbați global setarea regională activă cu i18n.set('locale', code) sau înlocuiți-o pentru fiecare apel prin argumentul cuvânt-cheie locale. În platformele web, detectați limba preferată a utilizatorului din solicitare și setați setarea regională înainte de redare.

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', ...) modifică setarea regională la nivel global. În serverele web cu mai multe fire de execuție (gunicorn cu procese worker, Django), aceasta poate provoca situații de concurență în care o solicitare schimbă setarea regională în timp ce alta este în curs de redare. Utilizați înlocuiri ale setării regionale pentru fiecare apel sau stocare locală pe firul de execuție pentru a evita această problemă.
7

Mecanism inteligent de rezervă pentru setările regionale cu python-i18n-locale-chain

În mod implicit, python-i18n acceptă o singură setare regională de rezervă. Atunci când un utilizator pt-BR nu are traduceri pt-BR, biblioteca revine direct la engleză, ignorând traducerile pt-PT perfect utilizabile. python-i18n-locale-chain remediază problema cu lanțuri de rezervă configurabile, care acoperă 75 de variante regionale.

python-i18n-locale-chain este un pachet gratuit, cu sursă deschisă. Un singur apel de funcție activează 75 de lanțuri de rezervă integrate pentru variantele regionale ale limbilor chineză, portugheză, spaniolă, franceză, germană, italiană, neerlandeză, engleză, arabă, norvegiană și malaeză.
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()
Lanțurile cu cel mai mare impact pentru testare sunt: pt-BR -> pt-PT -> pt -> en (portugheză), es-MX -> es-419 -> es -> en (spaniolă), zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en (chineză tradițională). Acestea acoperă cele mai frecvente scenarii regionale de rezervă.
8

Automatizați traducerile

După finalizarea configurării i18n, traduceți fișierele de localizare cu ajutorul IA. În IDE, solicitați asistentului IA să traducă fișierul-sursă sau utilizați CLI-ul i18n Agent în fluxul 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
Traduceți incremental. Când adăugați chei noi în fișierul-sursă, traduceți numai diferențele, fără a regenera toate fișierele. Astfel păstrați traducerile verificate de oameni.

Automatizați controlul calității traducerilor

Identificați cheile lipsă și substituenții nevalizi înainte de lansare cu i18n-validate. Testați interfața cu pseudotraduceri folosind i18n-pseudo înainte de sosirea traducerilor reale.

Probleme frecvente

Traducerile returnează cheile brute

Cauze: load_path nu este setat sau indică directorul greșit, file_format nu corespunde extensiilor fișierelor ori numele fișierelor nu corespund codurilor setărilor regionale. Verificați dacă i18n.load_path conține directorul corect și dacă fișierele sunt denumite corect (de exemplu, en.json, de.json).

Fișierele YAML nu se încarcă

python-i18n necesită PyYAML pentru suportul YAML, dar acesta nu este instalat implicit. Instalați-l cu pip install python-i18n[YAML]. Fără acesta, fișierele YAML sunt ignorate fără avertisment, iar traducerile returnează substituenți pentru cheile lipsă.

Căutările cheilor imbricate eșuează

python-i18n utilizează notația cu puncte pentru cheile imbricate: i18n.t('nav.home'). Dacă JSON utilizează chei plate cu puncte în nume (de exemplu, 'nav.home' drept cheie unică), biblioteca le interpretează drept căutări imbricate și operațiunea eșuează. Utilizați în schimb obiecte JSON imbricate reale.

Modificările setării regionale se propagă între solicitări

i18n.set('locale', ...) este o operațiune globală. În serverele cu mai multe fire de execuție, o solicitare poate schimba setarea regională în timp ce alta este în curs de redare. Utilizați argumentul cuvânt-cheie locale= pentru apelurile i18n.t() individuale sau stocați setarea regională într-un spațiu local pe firul de execuție printr-un middleware.

Structura recomandată a fișierelor

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

Traduceți și:

Încercați acum i18n Agent

Plasați aici fișierul de traducere

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

sau faceți clic pentru a-l selecta

Limbi țintă

Nu este necesară înregistrareaEstimare instantanee

Rezerva pentru setările regionale cu python-i18n-locale-chain

Atunci când lipsește o cheie de traducere dintr-o setare regională precum es-419, python-i18n revine direct la setarea regională implicită în loc să verifice mai întâi setarea regională părinte 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

Consultați Ghidul nostru privind mecanismele de rezervă pentru setările regionale, care conține lista completă a platformelor acceptate și cele 75 de lanțuri integrate. Learn more →

Întrebări frecvente