Skip to main content

Python i18n: Panduan Lengkap Penyetempatan

Sediakan python-i18n dengan fail terjemahan JSON atau YAML, kendalikan ruang letak dan bentuk jamak, kemudian automatikkan terjemahan dengan AI.

1

Pasang python-i18n

python-i18n ialah pustaka pengantarabangsaan ringan untuk Python. Pustaka ini terus menyokong fail terjemahan JSON dan YAML, kekunci bersarang, interpolasi ruang letak, dan bentuk jamak.

Terminal
pip install python-i18n
python-i18n menyokong JSON secara lalai. Untuk fail terjemahan YAML, pasang kebergantungan YAML pilihan dengan pip install python-i18n[YAML], yang menambahkan PyYAML.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Konfigurasikan Terjemahan

Tetapkan format fail, tambahkan laluan fail terjemahan, serta konfigurasikan lokal lalai dan sandaran anda. Import konfigurasi ini pada titik masuk aplikasi sebelum sebarang panggilan terjemahan.

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 mesti menunjuk ke direktori yang mengandungi fail terjemahan anda, bukan ke fail tertentu. Jika terjemahan mengembalikan kekunci mentah, semak bahawa load_path anda betul dan nama fail sepadan dengan kod lokal (contohnya, en.json, de.json).
3

Cipta Fail Terjemahan

Cipta satu fail bagi setiap bahasa dalam format JSON atau YAML. Gunakan kekunci bersarang untuk menyusun rentetan mengikut ciri atau halaman. Jadikan bahasa sumber anda (biasanya bahasa Inggeris) sebagai satu-satunya sumber kebenaran.

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"
  }
}
Namakan kekunci berdasarkan perkara yang diterangkannya, bukan tempat ia muncul: 'cart.item_count' lebih baik daripada 'homepage_cart_label'. Kekunci patut kekal sesuai selepas reka bentuk semula UI.
4

Gunakan Terjemahan dalam Kod anda

Panggil i18n.t() dengan laluan kekunci yang dipisahkan titik untuk mencari rentetan terjemahan. Anda boleh menggantikan lokal bagi setiap panggilan tanpa mengubah tetapan 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"
Kekunci bersarang menggunakan notasi titik: i18n.t('nav.home'). Jika kekunci JSON anda mengandungi titik literal, python-i18n akan mentafsirkannya sebagai pemisah aras bersarang. Elakkan titik dalam nama kekunci.
5

Ruang Letak dan Bentuk Jamak

python-i18n menyokong interpolasi ruang letak dengan sintaks %{name} dan bentuk jamak asas menggunakan subkekunci 'zero', 'one', dan 'many'. Hantar argumen kata kunci kepada i18n.t() untuk kedua-dua ciri tersebut.

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"
Bentuk jamak python-i18n menggunakan tiga kategori: zero, one, dan many. Kategori ini merangkumi bahasa Inggeris dan banyak bahasa lain, tetapi tidak menyokong seluruh peraturan bentuk jamak CLDR (few, two, other). Untuk bahasa seperti Arab, Rusia, atau Poland dengan bentuk jamak kompleks, anda mungkin perlu mengendalikan kes khusus secara manual atau menggunakan pustaka yang lebih canggih.
6

Menukar Lokal Semasa Masa Jalan

Tukar lokal aktif secara global dengan i18n.set('locale', code), atau gantikannya bagi setiap panggilan dengan argumen kata kunci locale. Dalam rangka kerja web, kesan bahasa pilihan pengguna daripada permintaan dan tetapkan lokal sebelum memaparkan.

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', ...) mengubah lokal secara global. Dalam pelayan web berbilang bebenang (gunicorn dengan pekerja, Django), hal ini boleh menyebabkan keadaan perlumbaan apabila satu permintaan mengubah lokal semasa permintaan lain sedang dipaparkan. Gunakan penggantian lokal setiap panggilan atau storan setempat bebenang untuk mengelakkannya.
7

Sandaran Lokal Pintar dengan python-i18n-locale-chain

Secara lalai, python-i18n hanya menyokong satu lokal sandaran. Apabila pengguna pt-BR tidak mempunyai terjemahan pt-BR, pustaka terus beralih kepada sandaran bahasa Inggeris dan mengabaikan terjemahan pt-PT yang sebenarnya sesuai. python-i18n-locale-chain membaikinya dengan rantaian sandaran boleh dikonfigurasikan yang merangkumi 75 varian lokal.

python-i18n-locale-chain ialah pakej sumber terbuka percuma. Satu panggilan fungsi mengaktifkan 75 rantaian sandaran terbina dalam untuk varian serantau bahasa Cina, Portugis, Sepanyol, Perancis, Jerman, Itali, Belanda, Inggeris, Arab, Norway, dan Melayu.
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()
Rantaian yang paling berimpak untuk diuji: pt-BR -> pt-PT -> pt -> en (Portugis), es-MX -> es-419 -> es -> en (Sepanyol), zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en (Cina Tradisional). Rantaian ini merangkumi senario sandaran serantau paling lazim.
8

Automatikkan Terjemahan

Selepas persediaan i18n selesai, terjemah fail bahasa dengan AI. Dalam IDE, minta pembantu AI menterjemah fail sumber atau gunakan CLI i18n Agent dalam saluran 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
Terjemahkan secara berperingkat. Apabila anda menambahkan kekunci baharu pada fail sumber, terjemahkan hanya perbezaannya dan bukannya menjana semula semua fail. Cara ini mengekalkan terjemahan yang telah disemak manusia.

Automatikkan Kualiti Terjemahan

Kesan kekunci hilang dan ruang letak rosak sebelum dikeluarkan dengan i18n-validate. Uji UI dengan terjemahan pseudo menggunakan i18n-pseudo sebelum terjemahan sebenar tersedia.

Kesilapan Umum

Terjemahan Mengembalikan Kekunci Mentah

Puncanya: load_path belum ditetapkan atau menunjuk ke direktori yang salah, file_format tidak sepadan dengan sambungan fail anda, atau nama fail tidak sepadan dengan kod lokal. Pastikan i18n.load_path mengandungi direktori yang betul dan fail telah dinamakan dengan betul (contohnya, en.json, de.json).

Fail YAML Tidak Dimuatkan

python-i18n memerlukan PyYAML untuk sokongan YAML, tetapi pakej ini tidak dipasang secara lalai. Pasang dengan pip install python-i18n[YAML]. Tanpanya, fail YAML akan diabaikan secara senyap dan terjemahan mengembalikan ruang letak kekunci yang tiada.

Carian Kekunci Bersarang Gagal

python-i18n menggunakan notasi titik untuk kekunci bersarang: i18n.t('nav.home'). Jika JSON anda menggunakan kekunci rata yang mempunyai titik dalam namanya (contohnya, 'nav.home' sebagai satu kekunci), pustaka mentafsirkannya sebagai carian bersarang dan gagal. Gunakan objek JSON bersarang yang sebenar.

Perubahan Lokal Bocor Antara Permintaan

i18n.set('locale', ...) ialah operasi global. Dalam pelayan berbilang bebenang, satu permintaan boleh mengubah lokal semasa permintaan lain sedang dipaparkan. Gunakan argumen kata kunci locale= pada setiap panggilan i18n.t(), atau tetapkan lokal dalam storan setempat bebenang melalui perisian tengah.

Struktur Fail yang Disyorkan

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

Terjemah juga:

Cuba i18n Agent Sekarang

Lepaskan fail terjemahan anda di sini

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

atau klik untuk semak imbas

Bahasa sasaran

Tidak perlu mendaftarAnggaran serta-merta

Sandaran Lokal dengan python-i18n-locale-chain

Apabila kekunci terjemahan tiada dalam lokal serantau seperti es-419, python-i18n terus beralih kepada lokal lalai dan bukannya menyemak lokal induk es terlebih dahulu.

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

Lihat Panduan Sandaran Bahasa kami untuk senarai lengkap rangka kerja yang disokong dan 75 rantaian terbina dalam. Learn more →

Soalan Lazim