Skip to main content

Python i18n: Kapsamlı yerelleştirme rehberi

python-i18n'i JSON veya YAML çeviri dosyalarıyla ayarlayın, yer tutucuları ve çoğulları yönetin, ardından çevirileri yapay zeka ile otomatikleştirin.

1

python-i18n'i yükleyin

python-i18n, Python için hafif bir uluslararasılaştırma kütüphanesidir. JSON ve YAML çeviri dosyalarını, iç içe anahtarları, yer tutucu eklemeyi ve çoğullaştırmayı kullanıma hazır olarak destekler.

Terminal
pip install python-i18n
python-i18n, JSON'u varsayılan olarak destekler. YAML çeviri dosyaları için PyYAML'ı ekleyen isteğe bağlı YAML bağımlılığını pip install python-i18n[YAML] komutuyla yükleyin.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Çevirileri yapılandırın

Dosya biçimini belirleyin, çeviri dosyası yollarını ekleyin ve varsayılan yerel ayarınızla geri dönüş yerel ayarınızı yapılandırın. Bu yapılandırmayı herhangi bir çeviri çağrısından önce uygulamanızın giriş noktasında içe aktarın.

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 belirli bir dosyayı değil, çeviri dosyalarınızın bulunduğu klasörü göstermelidir. Çeviriler işlenmemiş anahtarları döndürüyorsa load_path değerinizin doğru olduğunu ve dosya adlarının yerel ayar kodlarınızla eşleştiğini (ör. en.json, de.json) kontrol edin.
3

Çeviri dosyalarını oluşturun

JSON veya YAML biçiminde her dil için bir dosya oluşturun. Dizeleri özelliğe veya sayfaya göre düzenlemek için iç içe anahtarlar kullanın. Kaynak dilinizi (genellikle İngilizce) tek doğruluk kaynağı olarak koruyun.

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"
  }
}
Anahtarları göründükleri yere göre değil, tanımladıkları içeriğe göre adlandırın: 'cart.item_count', 'homepage_cart_label' değerinden daha iyidir. Anahtarlar kullanıcı arayüzü yeniden tasarımlarından etkilenmemelidir.
4

Çevirileri kodunuzda kullanın

Çevrilmiş dizeleri bulmak için i18n.t() işlevini noktalarla ayrılmış bir anahtar yoluyla çağırın. Genel ayarı değiştirmeden her çağrı için yerel ayarı geçersiz kılabilirsiniz.

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"
İç içe anahtarlar nokta gösterimini kullanır: i18n.t('nav.home'). JSON anahtarlarınız gerçek nokta karakterleri içeriyorsa python-i18n bunları iç içe geçme ayırıcıları olarak yorumlar. Anahtar adlarında nokta kullanmayın.
5

Yer tutucuları ve çoğullaştırmayı kullanın

python-i18n, %{name} söz dizimiyle yer tutucu eklemeyi ve 'zero', 'one' ve 'many' alt anahtarlarını kullanan temel çoğullaştırmayı destekler. Her iki özellik için de i18n.t() işlevine anahtar sözcük bağımsız değişkenleri aktarın.

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'in çoğullaştırması üç kategori kullanır: zero, one ve many. Bu kategoriler İngilizceyi ve birçok dili kapsar, ancak CLDR çoğul kurallarının tamamını (few, two, other) desteklemez. Arapça, Rusça veya Lehçe gibi karmaşık çoğul biçimleri olan dillerde uç durumları elle yönetmeniz veya daha gelişmiş bir kütüphane kullanmanız gerekebilir.
6

Çalışma zamanında yerel ayarı değiştirin

Etkin yerel ayarı i18n.set('locale', code) ile genel olarak değiştirin veya locale anahtar sözcük bağımsız değişkeniyle her çağrı için geçersiz kılın. Web çerçevelerinde kullanıcının tercih ettiği dili istekten algılayın ve içeriği oluşturmadan önce yerel ayarı belirleyin.

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', ...) yerel ayarı genel olarak değiştirir. Çok iş parçacıklı web sunucularında (çalışan süreçleri olan gunicorn, Django) bir istek yerel ayarı değiştirirken başka bir istek oluşturulma aşamasındaysa yarış durumları oluşabilir. Bunu önlemek için çağrıya özel yerel ayar geçersiz kılmaları veya iş parçacığına özgü depolama kullanın.
7

python-i18n-locale-chain ile akıllı yerel ayar geri dönüşü

python-i18n varsayılan olarak yalnızca tek bir geri dönüş yerel ayarını destekler. pt-BR kullanıcısı için pt-BR çevirileri bulunmadığında kütüphane, kullanılabilir pt-PT çevirilerini yok sayarak doğrudan İngilizce geri dönüşe geçer. python-i18n-locale-chain, 75 yerel ayar çeşidini kapsayan yapılandırılabilir geri dönüş zincirleriyle bu sorunu giderir.

python-i18n-locale-chain ücretsiz ve açık kaynaklı bir pakettir. Tek bir işlev çağrısı; Çince, Portekizce, İspanyolca, Fransızca, Almanca, İtalyanca, Felemenkçe, İngilizce, Arapça, Norveççe ve Malayca bölgesel çeşitleri için yerleşik 75 geri dönüş zincirini etkinleştirir.
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()
Test edilmesi en önemli zincirler: pt-BR -> pt-PT -> pt -> en (Portekizce), es-MX -> es-419 -> es -> en (İspanyolca), zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en (Geleneksel Çince). Bunlar en yaygın bölgesel geri dönüş senaryolarını kapsar.
8

Çevirileri otomatikleştirin

i18n kurulumunuzu tamamladıktan sonra yerel ayar dosyalarınızı yapay zeka kullanarak çevirin. IDE'nizde yapay zeka yardımcınızdan kaynak dosyanızı çevirmesini isteyin veya CI/CD işlem hattınızda i18n Agent CLI'ı kullanın.

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
Çevirileri aşamalı olarak yapın. Kaynak dosyanıza yeni anahtarlar eklediğinizde tüm dosyaları yeniden oluşturmak yerine yalnızca farkı çevirin. Böylece insanlar tarafından incelenmiş çeviriler korunur.

Çeviri kalitesini otomatikleştirin

Eksik anahtarları ve bozuk yer tutucuları yayımlanmadan önce i18n-validate ile yakalayın. Gerçek çeviriler gelmeden önce kullanıcı arayüzünüzü i18n-pseudo ile sözde çeviriler kullanarak test edin.

Yaygın sorunlar

Çeviriler işlenmemiş anahtarları döndürüyor

Nedenler: load_path ayarlanmamış veya yanlış klasörü gösteriyor olabilir, file_format dosya uzantılarınızla eşleşmeyebilir ya da dosya adları yerel ayar kodlarıyla eşleşmeyebilir. i18n.load_path değerinin doğru klasörü içerdiğini ve dosyaların doğru adlandırıldığını (ör. en.json, de.json) doğrulayın.

YAML dosyaları yüklenmiyor

python-i18n, YAML desteği için PyYAML gerektirir, ancak bu paket varsayılan olarak yüklenmez. pip install python-i18n[YAML] komutuyla yükleyin. PyYAML olmadan YAML dosyaları sessizce yok sayılır ve çeviriler eksik anahtar yer tutucuları döndürür.

İç içe anahtar aramaları başarısız oluyor

python-i18n iç içe anahtarlar için nokta gösterimini kullanır: i18n.t('nav.home'). JSON dosyanızda adında nokta bulunan düz anahtarlar varsa (ör. tek bir anahtar olarak 'nav.home') kütüphane bunu iç içe bir arama olarak yorumlar ve başarısız olur. Bunun yerine gerçek iç içe JSON nesneleri kullanın.

Yerel ayar değişiklikleri istekler arasında sızıyor

i18n.set('locale', ...) genel bir işlemdir. Çok iş parçacıklı sunucularda bir istek, başka bir istek oluşturulurken yerel ayarı değiştirebilir. Her i18n.t() çağrısında locale= anahtar sözcük bağımsız değişkenini kullanın veya yerel ayarı ara yazılımla iş parçacığına özgü depolamada belirleyin.

Önerilen dosya yapısı

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

Şunları da çevirin:

i18n Agent'ı şimdi deneyin

Çeviri dosyanızı buraya bırakın

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

veya göz atmak için tıklayın

Hedef diller

Kayıt gerekmezAnında fiyat tahmini

python-i18n-locale-chain ile yerel ayar geri dönüşü

es-419 gibi bölgesel bir yerel ayarda çeviri anahtarı eksik olduğunda python-i18n, önce üst yerel ayar es'i denetlemek yerine doğrudan varsayılan yerel ayara geçer.

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'],
'}')

# Kullanım: t('greeting', locale='es') — zincir boyunca geri dönüş yapar

Desteklenen çerçevelerin tam listesi ve yerleşik 75 zincir için Yerel Ayar Geri Dönüşü Rehberimize bakın. Learn more →

Sık sorulan sorular