Skip to main content

Python i18n: الدليل الكامل للتوطين

أعد إعداد python-i18n باستخدام ملفات ترجمة JSON أو YAML، وتعامل مع placeholders وصيغ الجمع، ثم أتمتِ الترجمات باستخدام AI.

1

تثبيت python-i18n

python-i18n هي مكتبة تدويل خفيفة الوزن لـ Python. تدعم ملفات ترجمة JSON وYAML، والمفاتيح المتداخلة، وإقحام الـ placeholders، وصيغ الجمع بشكل جاهز.

Terminal
pip install python-i18n
يدعم python-i18n صيغة JSON افتراضياً. لاستخدام ملفات ترجمة YAML، ثبّت الاعتماد الاختياري عبر pip install python-i18n[YAML]، ما يضيف PyYAML.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

تهيئة الترجمات

حدِّد صيغة الملف، وأضِف مسارات ملفات الترجمة، واضبط locale الافتراضي وlocales التراجع. استورد هذه التهيئة في نقطة دخول تطبيقك قبل أي استدعاءات ترجمة.

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 ومن أن أسماء الملفات تطابق رموز locale لديك (مثل 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() باستخدام مسار مفتاح مفصول بنقاط للبحث عن السلاسل المترجمة. يمكنك تجاوز locale لكل استدعاء من دون تغيير الإعداد العام.

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

تبديل locale أثناء التشغيل

بدّل locale النشط على مستوى التطبيق باستخدام i18n.set('locale', code)، أو تجاوز ذلك لكل استدعاء باستخدام الوسيط locale. في أطر الويب، اكتشف اللغة المفضلة لدى المستخدم من الطلب واضبط 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', ...) قيمة locale على مستوى التطبيق. في خوادم الويب متعددة الخيوط (gunicorn مع workers، Django)، قد يتسبب ذلك في حالات سباق حيث يغيّر طلب واحد locale بينما يكون طلب آخر في منتصف التصيير. استخدم تجاوز locale لكل استدعاء أو تخزيناً محلياً لكل خيط لتجنّب ذلك.
7

تراجع ذكي للّغات مع python-i18n-locale-chain

افتراضياً، يدعم python-i18n locale تراجعاً واحداً فقط. عندما لا تتوفر ترجمات pt-BR لمستخدم pt-BR، تقفز المكتبة مباشرةً إلى تراجع الإنجليزية، متجاهلةً ترجمات pt-PT المتاحة. يعالج python-i18n-locale-chain ذلك عبر سلاسل تراجع قابلة للتهيئة تغطي 75 متغيراً من locale.

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، ترجم ملفات locale باستخدام الذكاء الاصطناعي. في IDE، اطلب من مساعدك بالذكاء الاصطناعي ترجمة ملف المصدر، أو استخدم i18n Agent CLI ضمن مسار 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
ترجم تدريجياً. عند إضافة مفاتيح جديدة إلى ملف المصدر، ترجم الفرق فقط بدلاً من إعادة توليد جميع الملفات. يحافظ ذلك على أي ترجمات تمت مراجعتها بشرياً.

أتمتة جودة الترجمة

التقط المفاتيح المفقودة والعناصر النائبة المعطلة قبل الشحن باستخدام i18n-validate. اختبر واجهة المستخدم بترجمات وهمية باستخدام i18n-pseudo قبل وصول الترجمات الحقيقية.

أخطاء شائعة

الترجمات تُرجع المفاتيح الخام

الأسباب: لم يتم ضبط load_path أو أنه يشير إلى المجلد الخطأ، أو أن file_format لا يطابق امتدادات ملفاتك، أو أن أسماء الملفات لا تطابق رموز locale. تحقّق من أن i18n.load_path يحتوي على المجلد الصحيح، وأن الملفات مسماة بصورة صحيحة (مثل: en.json، de.json).

ملفات YAML لا يتم تحميلها

يتطلب python-i18n تثبيت PyYAML لدعم YAML، لكنه لا يُثبَّت افتراضياً. ثبّته عبر pip install python-i18n[YAML]. من دونه، يتم تجاهل ملفات YAML بصمت وتُرجع الترجمات عناصر نائبة لمفاتيح مفقودة.

يفشل البحث عن المفاتيح المتداخلة

يستخدم python-i18n تدوين النقطة للمفاتيح المتداخلة: i18n.t('nav.home'). إذا كانت JSON لديك تستخدم مفاتيح مسطّحة تتضمن نقاطاً حرفية في الاسم (مثل: 'nav.home' كمفتاح واحد)، فستفسّرها المكتبة على أنها بحث متداخل وتفشل. استخدم كائنات JSON متداخلة فعلية بدلاً من ذلك.

تسرب تغييرات locale بين الطلبات

يُعد i18n.set('locale', ...) عمليةً عامة على مستوى التطبيق. في الخوادم متعددة الخيوط، يمكن لطلب واحد تغيير locale بينما يقوم طلب آخر بالتصيير. استخدم الوسيط locale= على استدعاءات i18n.t() الفردية، أو اضبط locale في تخزين محلي لكل خيط عبر middleware.

بنية الملفات الموصى بها

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

أو انقر للاستعراض

اللغات المستهدفة

لا حاجة إلى التسجيلتقدير فوري

تراجع locale باستخدام python-i18n-locale-chain

عندما يكون مفتاح الترجمة مفقوداً في locale إقليمي مثل es-419، يقفز python-i18n مباشرةً إلى locale الافتراضي بدلاً من التحقق من locale الأب 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

اطّلع على دليل Locale Fallback لدينا للاطلاع على القائمة الكاملة للأطر المدعومة و75 سلسلة مدمجة. Learn more →

الأسئلة الشائعة