Skip to main content

Python i18n: Kumpletong Gabay sa Localization

I-setup ang python-i18n gamit ang mga JSON o YAML translation file, hawakan ang mga placeholder at plural, at pagkatapos ay i-automate ang mga pagsasalin gamit ang AI.

1

I-install ang python-i18n

Magaan na internationalization library para sa Python ang python-i18n. Sinusuportahan nito ang mga JSON at YAML translation file, mga nested key, placeholder interpolation, at pluralization out of the box.

Terminal
pip install python-i18n
Sinusuportahan ng python-i18n ang JSON bilang default. Para sa mga YAML translation file, i-install ang optional YAML dependency gamit ang pip install python-i18n[YAML], na nagdaragdag ng PyYAML.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

I-configure ang Mga Pagsasalin

Itakda ang file format, idagdag ang mga path ng translation file, at i-configure ang inyong default at fallback locale. I-import ang configuration na ito sa entry point ng inyong application bago tumawag ng anumang translation.

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)
Dapat ituro ng load_path ang directory na naglalaman ng inyong mga translation file, hindi ang isang partikular na file. Kung raw key ang ibinabalik ng mga translation, tiyaking tama ang load_path at tumutugma ang mga filename sa inyong locale code (hal., en.json, de.json).
3

Gumawa ng Mga Translation File

Gumawa ng isang file bawat wika sa JSON o YAML format. Gumamit ng mga nested key para ayusin ang mga string ayon sa feature o page. Panatilihin ang source language (karaniwang English) bilang nag-iisang source of truth.

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"
  }
}
Pangalanan ang mga key batay sa kung ano ang inilalarawan nila, hindi kung saan sila lumalabas: mas mabuti ang 'cart.item_count' kaysa sa 'homepage_cart_label'. Dapat makaligtas ang mga key sa UI redesign.
4

Gamitin ang Mga Pagsasalin sa Inyong Code

Tawagin ang i18n.t() gamit ang dot-separated na key path para hanapin ang mga naisaling string. Maaari ninyong i-override ang locale sa bawat tawag nang hindi binabago ang global setting.

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"
Gumagamit ang mga nested key ng dot notation: i18n.t('nav.home'). Kung may literal na tuldok ang mga JSON key ninyo, ituturing iyon ng python-i18n bilang separator ng nesting. Iwasan ang mga tuldok sa pangalan ng key.
5

Mga Placeholder at Pluralization

Sinusuportahan ng python-i18n ang placeholder interpolation gamit ang %{name} syntax at basic pluralization gamit ang 'zero', 'one', at 'many' na sub-key. I-pass ang mga keyword argument sa i18n.t() para sa parehong feature.

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"
Tatlong kategorya ang gamit ng pluralization ng python-i18n: zero, one, at many. Sakop nito ang English at maraming wika ngunit hindi nito sinusuportahan ang buong CLDR plural rules (few, two, other). Para sa mga wikang tulad ng Arabic, Russian, o Polish na may kumplikadong plural form, maaaring kailanganin ninyong hawakan ang mga edge case nang manu-mano o gumamit ng mas advanced na library.
6

Pagpapalit ng Locale sa Runtime

Palitan ang active locale nang global gamit ang i18n.set('locale', code) o i-override sa bawat tawag gamit ang locale keyword argument. Sa mga web framework, tuklasin ang preferred language ng user mula sa request at itakda ang locale bago mag-render.

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")
Binabago ng i18n.set('locale', ...) ang locale nang global. Sa mga multi-threaded na web server (gunicorn na may worker, Django), maaari itong magdulot ng race condition kung binabago ng isang request ang locale habang nagre-render ang isa pa. Gumamit ng per-call locale override o thread-local storage upang maiwasan ito.
7

Smart Locale Fallback gamit ang python-i18n-locale-chain

Bilang default, iisang fallback locale lang ang sinusuportahan ng python-i18n. Kapag walang pt-BR translation ang pt-BR user, dumidiretso ang library sa English fallback at hindi pinapansin ang maayos na pt-PT translation. Inaayos ito ng python-i18n-locale-chain gamit ang mga configurable na fallback chain na sumasaklaw sa 75 locale variant.

Ang python-i18n-locale-chain ay isang libre at open-source na package. Isang function call lang ang kailangan para paganahin ang 75 built-in na fallback chain para sa mga regional variant ng Chinese, Portuguese, Spanish, French, German, Italian, Dutch, English, Arabic, Norwegian, at Malay.
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()
Ang mga chain na may pinakamalaking epekto na dapat subukan: pt-BR -> pt-PT -> pt -> en (Portuguese), es-MX -> es-419 -> es -> en (Spanish), zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en (Chinese Traditional). Saklaw nito ang mga pinakakaraniwang regional fallback scenario.
8

I-automate ang Mga Salin

Kapag kumpleto na ang i18n setup ninyo, isalin ang inyong mga locale file gamit ang AI. Sa inyong IDE, hilingin sa AI assistant na isalin ang source file ninyo, o gamitin ang i18n Agent CLI sa inyong 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
Magsalin nang paunti-unti. Kapag nagdagdag kayo ng mga bagong key sa source file ninyo, isalin lamang ang diff sa halip na i-regenerate ang lahat ng file. Napapanatili nito ang anumang saling nasuri na ng tao.

I-automate ang Kalidad ng Pagsasalin

Matukoy ang mga nawawalang key at sirang placeholder bago ma-ship gamit ang i18n-validate. Subukan ang UI ninyo gamit ang mga pseudo-translation sa i18n-pseudo bago dumating ang mga tunay na salin.

Mga Karaniwang Pagkakamali

Nagbabalik ang Mga Salin ng Mga Raw Key

Mga sanhi: hindi naka-set ang load_path o tumuturo sa maling directory, hindi tumutugma ang file_format sa inyong mga file extension, o hindi tumutugma ang mga pangalan ng file sa mga locale code. Tiyakin na nasa i18n.load_path ang tamang directory at tama ang pagkakapangalan ng mga file (hal., en.json, de.json).

Hindi Naglo-load ang Mga YAML File

Kailangan ng python-i18n ang PyYAML para sa YAML support, ngunit hindi ito naka-install bilang default. I-install gamit ang pip install python-i18n[YAML]. Kapag wala ito, tahimik na hindi pinapansin ang mga YAML file at nagbabalik ang mga salin ng mga placeholder para sa missing key.

Pumapalya ang Nested Key Lookup

Gumagamit ang python-i18n ng dot notation para sa mga nested key: i18n.t('nav.home'). Kung ang JSON ninyo ay gumagamit ng flat na mga key na may tuldok sa pangalan (hal., 'nav.home' bilang iisang key), iintindihin ito ng library bilang nested lookup at papalya. Gumamit na lang ng tunay na nested na JSON object.

Tumatagas ang Pagbabago ng Locale sa Ibang Request

Global na operasyon ang i18n.set('locale', ...). Sa mga multi-threaded server, puwedeng baguhin ng isang request ang locale habang nagre-render ang isa pa. Gamitin ang locale= keyword argument sa mga indibidwal na i18n.t() call, o itakda ang locale sa thread-local storage gamit ang middleware.

Inirerekomendang Istruktura ng File

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

Magsalin din ng:

Subukan ang i18n Agent Ngayon

I-drop dito ang inyong translation file

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

o i-click para mag-browse

Mga target language

Hindi kailangan ang signupInstant na estimate

Locale Fallback gamit ang python-i18n-locale-chain

Kapag nawawala ang translation key sa isang regional locale tulad ng es-419, dumidiretso ang python-i18n sa default locale sa halip na i-check muna ang parent locale na 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'],
'}')

# Paggamit: t('greeting', locale='es') — magfa-fallback sa buong chain

Tingnan ang aming Locale Fallback Guide para sa buong listahan ng mga sinusuportahang framework at 75 built-in chain. Learn more →

Mga Madalas Itanong