Skip to main content

Python i18n: повний посібник із локалізації

Налаштуйте python-i18n із файлами перекладу JSON або YAML, опрацюйте заповнювачі та форми множини, а потім автоматизуйте переклад за допомогою ШІ.

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 із робочими процесами, 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, перекладіть файли локалей за допомогою ШІ. Попросіть ШІ-помічника у Вашому IDE перекласти вихідний файл або скористайтеся 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 не завантажуються

Для підтримки YAML бібліотеці python-i18n потрібен PyYAML, але за замовчуванням його не встановлено. Установіть його за допомогою 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 →

Поширені запитання