Skip to main content

Python i18n: Panduan Lengkap Lokalisasi

Siapkan python-i18n dengan file terjemahan JSON atau YAML, tangani placeholder dan bentuk jamak, lalu otomatiskan terjemahan dengan AI.

1

Instal python-i18n

python-i18n adalah pustaka internasionalisasi ringan untuk Python. Pustaka ini langsung mendukung file terjemahan JSON dan YAML, kunci bersarang, interpolasi placeholder, dan bentuk jamak.

Terminal
pip install python-i18n
python-i18n mendukung JSON secara default. Untuk file terjemahan YAML, instal dependensi YAML opsional 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

Atur format file, tambahkan jalur file terjemahan, serta konfigurasikan locale default dan fallback Anda. Impor konfigurasi ini di titik masuk aplikasi sebelum panggilan terjemahan apa pun.

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 harus menunjuk ke direktori yang berisi file terjemahan Anda, bukan ke file tertentu. Jika terjemahan mengembalikan kunci mentah, periksa bahwa load_path Anda benar dan nama file cocok dengan kode locale (misalnya, en.json, de.json).
3

Buat File Terjemahan

Buat satu file per bahasa dalam format JSON atau YAML. Gunakan kunci bersarang untuk mengatur string berdasarkan fitur atau halaman. Jadikan bahasa sumber Anda (biasanya bahasa Inggris) 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"
  }
}
Namai kunci berdasarkan hal yang dijelaskannya, bukan tempat kemunculannya: 'cart.item_count' lebih baik daripada 'homepage_cart_label'. Kunci harus tetap berlaku setelah UI didesain ulang.
4

Gunakan Terjemahan dalam Kode Anda

Panggil i18n.t() dengan jalur kunci yang dipisahkan titik untuk mencari string terjemahan. Anda dapat mengganti locale per panggilan tanpa mengubah pengaturan 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"
Kunci bersarang menggunakan notasi titik: i18n.t('nav.home'). Jika kunci JSON Anda mengandung titik literal, python-i18n akan menafsirkannya sebagai pemisah tingkat bersarang. Hindari titik dalam nama kunci.
5

Placeholder dan Bentuk Jamak

python-i18n mendukung interpolasi placeholder dengan sintaks %{name} dan bentuk jamak dasar menggunakan subkunci 'zero', 'one', dan 'many'. Teruskan argumen kata kunci ke i18n.t() untuk kedua fitur 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 mencakup bahasa Inggris dan banyak bahasa lain, tetapi tidak mendukung seluruh aturan bentuk jamak CLDR (few, two, other). Untuk bahasa seperti Arab, Rusia, atau Polandia dengan bentuk jamak kompleks, Anda mungkin perlu menangani kasus khusus secara manual atau menggunakan pustaka yang lebih canggih.
6

Mengganti Locale Saat Runtime

Ganti locale aktif secara global dengan i18n.set('locale', code), atau ganti per panggilan dengan argumen kata kunci locale. Dalam framework web, deteksi bahasa pilihan pengguna dari permintaan dan tetapkan locale sebelum merender.

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 locale secara global. Dalam server web multithread (gunicorn dengan worker, Django), hal ini dapat menyebabkan kondisi balapan ketika satu permintaan mengubah locale sementara permintaan lain sedang dirender. Gunakan penggantian locale per panggilan atau penyimpanan lokal-thread untuk menghindarinya.
7

Fallback Locale Cerdas dengan python-i18n-locale-chain

Secara default, python-i18n hanya mendukung satu locale fallback. Ketika pengguna pt-BR tidak memiliki terjemahan pt-BR, pustaka langsung beralih ke fallback bahasa Inggris dan mengabaikan terjemahan pt-PT yang sebenarnya sesuai. python-i18n-locale-chain memperbaikinya dengan rantai fallback yang dapat dikonfigurasi dan mencakup 75 varian locale.

python-i18n-locale-chain adalah paket sumber terbuka gratis. Satu panggilan fungsi mengaktifkan 75 rantai fallback bawaan untuk varian regional bahasa Tionghoa, Portugis, Spanyol, Prancis, Jerman, Italia, Belanda, Inggris, Arab, Norwegia, 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()
Rantai yang paling berdampak untuk diuji: pt-BR -> pt-PT -> pt -> en (Portugis), es-MX -> es-419 -> es -> en (Spanyol), zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en (Tionghoa Tradisional). Rantai ini mencakup skenario fallback regional paling umum.
8

Otomatiskan Penerjemahan

Setelah penyiapan i18n selesai, terjemahkan file bahasa dengan AI. Di IDE, minta asisten AI menerjemahkan file sumber atau gunakan CLI i18n Agent di pipeline 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 bertahap. Ketika Anda menambahkan kunci baru ke file sumber, terjemahkan hanya perbedaannya alih-alih membuat ulang semua file. Cara ini mempertahankan terjemahan yang telah ditinjau manusia.

Otomatiskan Kualitas Terjemahan

Temukan kunci hilang dan placeholder rusak sebelum dirilis dengan i18n-validate. Uji UI dengan terjemahan semu menggunakan i18n-pseudo sebelum terjemahan asli tersedia.

Kesalahan Umum

Terjemahan Mengembalikan Kunci Mentah

Penyebabnya: load_path belum ditetapkan atau menunjuk ke direktori yang salah, file_format tidak cocok dengan ekstensi file Anda, atau nama file tidak cocok dengan kode locale. Pastikan i18n.load_path berisi direktori yang benar dan file telah dinamai dengan benar (misalnya, en.json, de.json).

File YAML Tidak Dimuat

python-i18n memerlukan PyYAML untuk dukungan YAML, tetapi paket ini tidak diinstal secara default. Instal dengan pip install python-i18n[YAML]. Tanpanya, file YAML akan diabaikan tanpa pemberitahuan dan terjemahan mengembalikan placeholder kunci yang tidak tersedia.

Pencarian Kunci Bersarang Gagal

python-i18n menggunakan notasi titik untuk kunci bersarang: i18n.t('nav.home'). Jika JSON Anda menggunakan kunci datar yang memiliki titik dalam namanya (misalnya, 'nav.home' sebagai satu kunci), pustaka menafsirkannya sebagai pencarian bersarang dan gagal. Gunakan objek JSON bersarang yang sebenarnya.

Perubahan Locale Bocor Antarpermintaan

i18n.set('locale', ...) adalah operasi global. Dalam server multithread, satu permintaan dapat mengubah locale ketika permintaan lain sedang dirender. Gunakan argumen kata kunci locale= pada setiap panggilan i18n.t(), atau tetapkan locale dalam penyimpanan lokal-thread melalui middleware.

Struktur File yang Disarankan

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

Terjemahkan juga:

Coba i18n Agent Sekarang

Lepaskan file terjemahan Anda di sini

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

atau klik untuk menjelajahi

Bahasa target

Tidak perlu mendaftarEstimasi instan

Fallback Locale dengan python-i18n-locale-chain

Ketika kunci terjemahan tidak tersedia dalam locale regional seperti es-419, python-i18n langsung beralih ke locale default alih-alih memeriksa locale 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 Fallback Bahasa kami untuk daftar lengkap framework yang didukung dan 75 rantai bawaan. Learn more →

Pertanyaan yang Sering Diajukan