Skip to main content

Python i18n: cjelovit vodič za lokalizaciju

Postavite python-i18n s JSON ili YAML datotekama prijevoda, obradite rezervirana mjesta i množinu, a zatim automatizirajte prijevode pomoću AI-ja.

1

Instalirajte python-i18n

python-i18n je jednostavna knjižnica za internacionalizaciju u Pythonu. Bez dodatnog postavljanja podržava JSON i YAML datoteke prijevoda, ugniježđene ključeve, interpolaciju rezerviranih mjesta i množinu.

Terminal
pip install python-i18n
python-i18n zadano podržava JSON. Za YAML datoteke prijevoda instalirajte neobaveznu ovisnost za YAML naredbom pip install python-i18n[YAML], čime se dodaje PyYAML.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Konfigurirajte prijevode

Postavite format datoteke, dodajte putanje datoteka prijevoda te odredite zadani i pričuvni jezik. Uvezite ovu konfiguraciju na ulaznoj točki aplikacije prije bilo kojeg poziva funkcije za prevođenje.

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 mora upućivati na mapu koja sadržava datoteke prijevoda, a ne na određenu datoteku. Ako prijevodi vraćaju neobrađene ključeve, provjerite je li load_path ispravan i odgovaraju li nazivi datoteka jezičnim oznakama (npr. en.json, de.json).
3

Izradite datoteke prijevoda

Izradite po jednu datoteku za svaki jezik u JSON ili YAML formatu. Upotrijebite ugniježđene ključeve kako biste tekstove organizirali prema značajci ili stranici. Neka izvorni jezik (obično engleski) bude jedini mjerodavni izvor.

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"
  }
}
Imenujte ključeve prema onome što opisuju, a ne mjestu na kojem se pojavljuju: 'cart.item_count' bolje je od 'homepage_cart_label'. Ključevi trebaju ostati primjenjivi i nakon redizajna korisničkog sučelja.
4

Upotrebljavajte prijevode u kodu

Pozovite i18n.t() s putanjom ključa razdvojenom točkama kako biste dohvatili prevedene tekstove. Aktivni jezik možete promijeniti za pojedinačni poziv bez promjene globalne postavke.

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"
Ugniježđeni ključevi koriste točkastu notaciju: i18n.t('nav.home'). Ako ključevi u JSON-u sadržavaju doslovne točke, python-i18n tumačit će ih kao razdjelnike ugniježđivanja. Izbjegavajte točke u nazivima ključeva.
5

Rezervirana mjesta i množina

python-i18n podržava interpolaciju rezerviranih mjesta sintaksom %{name} i osnovnu množinu pomoću potključeva 'zero', 'one' i 'many'. Za obje mogućnosti proslijedite imenovane argumente funkciji 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žina u sustavu python-i18n koristi tri kategorije: zero, one i many. To obuhvaća engleski i mnoge druge jezike, ali ne podržava sva CLDR pravila množine (few, two, other). Za jezike poput arapskog, ruskog ili poljskog sa složenim oblicima množine možda ćete morati ručno obraditi rubne slučajeve ili upotrijebiti napredniju knjižnicu.
6

Promjena jezika tijekom izvođenja

Globalno promijenite aktivni jezik pomoću i18n.set('locale', code) ili ga promijenite za pojedinačni poziv imenovanim argumentom locale. U web-radnim okvirima iz zahtjeva prepoznajte željeni korisnikov jezik i postavite ga prije prikaza.

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', ...) globalno mijenja jezik. Na višenitnim web-poslužiteljima (gunicorn s radnim procesima, Django) to može izazvati uvjete utrke, pri kojima jedan zahtjev mijenja jezik dok se drugi prikazuje. Kako biste to izbjegli, promijenite jezik za pojedinačni poziv ili upotrijebite lokalnu pohranu niti.
7

Pametni pričuvni odabir jezika uz python-i18n-locale-chain

python-i18n zadano podržava samo jedan pričuvni jezik. Kada za korisnika s oznakom pt-BR nema prijevoda za pt-BR, knjižnica odmah prelazi na engleski i zanemaruje dostupne prijevode za pt-PT. python-i18n-locale-chain to ispravlja prilagodljivim pričuvnim lancima koji obuhvaćaju 75 jezičnih inačica.

python-i18n-locale-chain besplatan je paket otvorenog izvornog koda. Jedan poziv funkcije aktivira 75 ugrađenih pričuvnih lanaca za regionalne inačice kineskog, portugalskog, španjolskog, francuskog, njemačkog, talijanskog, nizozemskog, engleskog, arapskog, norveškog i malajskog.
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()
Najvažniji lanci za testiranje: pt-BR -> pt-PT -> pt -> en (portugalski), es-MX -> es-419 -> es -> en (španjolski), zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en (tradicionalni kineski). Oni obuhvaćaju najčešće scenarije regionalnog pričuvnog odabira.
8

Automatizirajte prijevode

Kada završite postavljanje i18n sustava, prevedite lokalizacijske datoteke pomoću AI-ja. U IDE-u zatražite od AI pomoćnika da prevede izvornu datoteku ili upotrijebite i18n Agent CLI u CI/CD procesu.

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
Prevodite postupno. Kada dodate nove ključeve u izvornu datoteku, prevedite samo razliku umjesto ponovnog generiranja svih datoteka. Time se čuvaju prijevodi koje su ljudi pregledali.

Automatizirajte provjeru kvalitete prijevoda

Alatom i18n-validate otkrijte ključeve koji nedostaju i neispravna rezervirana mjesta prije isporuke. Korisničko sučelje testirajte pseudoprijevodima iz alata i18n-pseudo prije nego što stignu stvarni prijevodi.

Uobičajene zamke

Prijevodi vraćaju neobrađene ključeve

Uzroci: load_path nije postavljen ili upućuje na pogrešnu mapu, file_format ne odgovara nastavcima datoteka ili nazivi datoteka ne odgovaraju jezičnim oznakama. Provjerite sadržava li i18n.load_path ispravnu mapu i jesu li datoteke ispravno imenovane (npr. en.json, de.json).

YAML datoteke se ne učitavaju

python-i18n zahtijeva PyYAML za podršku za YAML, ali taj se paket zadano ne instalira. Instalirajte ga naredbom pip install python-i18n[YAML]. Bez njega se YAML datoteke neprimjetno zanemaruju, a prijevodi vraćaju rezervirana mjesta za ključeve koji nedostaju.

Pretraga ugniježđenih ključeva ne uspijeva

python-i18n koristi točkastu notaciju za ugniježđene ključeve: i18n.t('nav.home'). Ako JSON koristi ravne ključeve s točkama u imenu (npr. 'nav.home' kao jedan ključ), knjižnica ih tumači kao ugniježđenu pretragu i ne uspijeva. Umjesto toga koristite stvarne ugniježđene JSON objekte.

Promjene jezika utječu na druge zahtjeve

i18n.set('locale', ...) globalna je operacija. Na višenitnim poslužiteljima jedan zahtjev može promijeniti jezik dok se drugi prikazuje. Upotrijebite imenovani argument locale= u pojedinačnim pozivima i18n.t() ili postavite jezik u lokalnoj pohrani niti s pomoću međuverzja.

Preporučena struktura datoteka

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

Prevedite i:

Isprobajte i18n Agent odmah

Povucite datoteku za prijevod ovdje

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

ili kliknite za odabir

Ciljni jezici

Registracija nije potrebnaProcjena odmah

Pričuvni odabir jezika uz python-i18n-locale-chain

Kada ključ prijevoda nedostaje u regionalnoj jezičnoj inačici kao što je es-419, python-i18n odmah prelazi na zadani jezik umjesto da prvo provjeri nadređenu jezičnu oznaku 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

U našem vodiču za pričuvni odabir jezika pogledajte cjelovit popis podržanih radnih okvira i 75 ugrađenih lanaca. Learn more →

Česta pitanja