Skip to main content

Python i18n: комплетан водич за локализацију

Подесите python-i18n са JSON или YAML датотекама превода, обрадите чуваре места и множине, а затим аутоматизујте преводе помоћу AI технологије.

1

Инсталирајте python-i18n

python-i18n је лагана библиотека за Python интернационализацију. Одмах подржава JSON и YAML датотеке превода, угнежђене кључеве, интерполацију чувара места и множину.

Terminal
pip install python-i18n
python-i18n подразумевано подржава JSON. За YAML датотеке превода инсталирајте необавезну YAML зависност помоћу pip install python-i18n[YAML], која додаје PyYAML.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Подесите преводе

Поставите формат датотеке, додајте путање датотека превода и подесите подразумевани и резервни локал. Увезите ову конфигурацију на улазној тачки апликације пре било ког позива за превођење.

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 мора да показује на директоријум који садржи датотеке превода, а не на одређену датотеку. Ако преводи враћају необрађене кључеве, проверите да ли је load_path исправан и да ли имена датотека одговарају кодовима локала (нпр. en.json, de.json).
3

Направите датотеке превода

Направите по једну датотеку за сваки језик у JSON или YAML формату. Користите угнежђене кључеве да организујете текстове по функционалности или страници. Нека изворни језик (обично енглески) буде једини извор истине.

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"
  }
}
Именујте кључеве према ономе што описују, а не месту на којем се појављују: 'cart.item_count' је боље од 'homepage_cart_label'. Кључеви треба да преживе редизајн корисничког интерфејса.
4

Користите преводе у коду

Позовите i18n.t() са путањом кључа раздвојеном тачкама да пронађете преведене текстове. Можете да промените локал за појединачни позив без промене глобалне поставке.

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"
Угнежђени кључеви користе тачкасту нотацију: i18n.t('nav.home'). Ако JSON кључеви садрже дословне тачке, python-i18n ће их тумачити као разделнике угнежђивања. Избегавајте тачке у именима кључева.
5

Чувари места и множина

python-i18n подржава интерполацију чувара места синтаксом %{name} и основну множину помоћу поткључева 'zero', 'one' и 'many'. Проследите именоване аргументе функцији 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 систему користи три категорије: zero, one и many. То покрива енглески и многе језике, али не подржава сва CLDR правила множине (few, two, other). За језике попут арапског, руског или пољског са сложеним облицима множине можда ћете морати ручно да обрадите рубне случајеве или користите напреднију библиотеку.
6

Промена локала током извршавања

Глобално промените активни локал помоћу i18n.set('locale', code) или га промените за појединачни позив именованим аргументом locale. У веб-радним оквирима откријте жељени језик корисника из захтева и поставите локал пре приказивања.

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', ...) глобално мења локал. На вишенитним веб-серверима (gunicorn са worker процесима, Django) то може да изазове услове трке, при којима један захтев мења локал док се други приказује. Користите промену локала за појединачни позив или складиште локално за нит да то избегнете.
7

Паметни резервни локали уз python-i18n-locale-chain

python-i18n подразумевано подржава само један резервни локал. Када корисник локала pt-BR нема преводе за pt-BR, библиотека одмах прелази на енглеску резерву и занемарује сасвим добре преводе за pt-PT. python-i18n-locale-chain то исправља подесивим ланцима резерве који обухватају 75 варијанти локала.

python-i18n-locale-chain је бесплатан пакет отвореног кода. Један позив функције активира 75 уграђених ланаца резерве за регионалне варијанте кинеског, португалског, шпанског, француског, немачког, италијанског, холандског, енглеског, арапског, норвешког и малајског.
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()
Најважнији ланци за тестирање: pt-BR -> pt-PT -> pt -> en (португалски), es-MX -> es-419 -> es -> en (шпански), zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en (традиционални кинески). Они обухватају најчешће сценарије регионалне резерве.
8

Аутоматизујте преводе

Када завршите i18n подешавање, преведите датотеке локала помоћу AI. У IDE окружењу затражите од AI помоћника да преведе изворну датотеку или користите i18n Agent CLI у CI/CD pipeline процесу.

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
Преводите постепено. Када додате нове кључеве у изворну датотеку, преведите само разлику уместо поновног генерисања свих датотека. Тиме се чувају преводи које су људи прегледали.

Аутоматизујте квалитет превода

Помоћу i18n-validate алатке откријте недостајуће кључеве и неисправне чуваре места пре испоруке. Тестирајте кориснички интерфејс псеудопреводима помоћу i18n-pseudo алатке пре него што стигну прави преводи.

Уобичајене замке

Преводи враћају необрађене кључеве

Узроци: load_path није постављен или показује на погрешан директоријум, file_format не одговара наставцима датотека или имена датотека не одговарају кодовима локала. Проверите да ли i18n.load_path садржи исправан директоријум и да ли су датотеке исправно именоване (нпр. en.json, de.json).

YAML датотеке се не учитавају

python-i18n захтева PyYAML за YAML подршку, али се он подразумевано не инсталира. Инсталирајте га помоћу pip install python-i18n[YAML]. Без њега се YAML датотеке неприметно занемарују, а преводи враћају чуваре места за недостајуће кључеве.

Претрага угнежђених кључева не успева

python-i18n користи тачкасту нотацију за угнежђене кључеве: i18n.t('nav.home'). Ако JSON користи равне кључеве са тачкама у имену (нпр. 'nav.home' као један кључ), библиотека их тумачи као угнежђену претрагу и не успева. Уместо тога користите стварне угнежђене JSON објекте.

Промене локала прелазе између захтева

i18n.set('locale', ...) је глобална операција. На вишенитним серверима један захтев може да промени локал док се други приказује. Користите именовани аргумент locale= у појединачним позивима i18n.t() или поставите локал у складишту локалном за нит помоћу посредничког софтвера.

Препоручена структура датотека

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

Преведите и:

Испробајте i18n Agent сада

Пустите датотеку за превођење овде

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

или кликните за избор

Циљни језици

Регистрација није потребнаТренутна процена

Резервни локали уз python-i18n-locale-chain

Када кључ превода недостаје у регионалном локалу као што је es-419, python-i18n одмах прелази на подразумевани локал уместо да прво провери надређени локал 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

Погледајте наш водич за резервне локале за целу листу подржаних система и 75 уграђених ланаца. Learn more →

Честа питања