تكوين i18n.json

i18n.json هو ملف تكوين قياسي يتحكم في سلوك Lingo.dev CLI و**تكاملات Lingo.dev CI/CD**.

ينفذ ملف i18n.json تكوينًا قائمًا على المخطط يفصل إعدادات اللغة وأنماط اكتشاف الملفات وتكوين محرك الترجمة بالذكاء الاصطناعي إلى أقسام متميزة. ونتيجة لذلك، يفهم المطورون بالضبط كيفية عمل سير عمل الترجمة والتوطين الخاص بهم من خلال قراءة ملف التكوين.

يفترض هذا الدليل أنك قمت بتثبيت Lingo.dev CLI وتقوم بتكوين سير عمل الترجمة. عند الانتهاء، ستفهم البنية الكاملة لملف i18n.json وخيارات التكوين وكيفية تحكم كل قسم في سلوك الترجمة.

الإصدار

يحدد حقل version إصدار مخطط التكوين:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10"
}

عناصر التكوين:

  • $schema — يشير إلى تعريف مخطط JSON للإكمال التلقائي والتحقق من الصحة في بيئة التطوير المتكاملة. يساعد المخطط في اكتشاف أخطاء التكوين مبكرًا من خلال توفير التوثيق المضمن والتحقق من النوع.
  • version — إصدار مخطط التكوين لتوافق الترحيل.

يستخدم Lingo.dev CLI هذا الحقل لترحيل التكوين التلقائي عند إصدار إصدارات مخطط جديدة.

تكوين اللغة

يحدد قسم locale اللغات التي يعالجها Lingo.dev CLI:

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja", "de"]
  }
}

تتبع رموز اللغة معيار BCP 47 لعلامات اللغة، والذي يتضمن رموز اللغة من ISO 639 ورموز المنطقة الاختيارية من ISO 3166-1. تتضمن الأمثلة en وen-US وes-ES وzh-Hans.

يدعم Lingo.dev CLI أيضًا تنسيقات اللغة الخاصة بالمنصة مثل اصطلاح en-rUS في Android لأدلة الموارد. للحصول على القائمة الكاملة لرموز اللغة المدعومة، قم بتشغيل:

npx lingo.dev@latest show locale sources  # Available source languages
npx lingo.dev@latest show locale targets  # Available target languages

إذا لم يكن رمز اللغة الخاص بك مدعومًا، يرجى فتح طلب سحب لإضافته!

عناصر التكوين:

  • locale.source — رمز اللغة المصدر الذي يحدد الملفات التي تحتوي على المحتوى الموثوق. تتدفق جميع الترجمات من المصدر إلى الأهداف.
  • locale.targets — مصفوفة من رموز اللغة المستهدفة التي تمثل الأسواق المستهدفة. يتوافق كل رمز مع ملف منفصل أو قسم داخل ملف، اعتمادًا على التنسيق.

أوامر التحقق من اللغة:

تكوين المزود

يحدد قسم المزود خدمة الترجمة بالذكاء الاصطناعي التي يستخدمها Lingo.dev CLI. هذا القسم اختياري ويستخدم محرك الترجمة بالذكاء الاصطناعي من Lingo.dev افتراضيًا عند حذفه.

للوصول المباشر إلى واجهة برمجة تطبيقات LLM:

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Your custom translation prompt with {source} and {target} placeholders"
  }
}

لمحرك Lingo.dev:

لاستخدام محرك Lingo.dev، احذف قسم المزود بالكامل. يختار المحرك النماذج والمطالبات تلقائيًا بناءً على أبحاث التحسين وإعدادات محرك Lingo.dev الخاصة بك.

عناصر التكوين:

  • provider.id — معرّف خدمة الترجمة بالذكاء الاصطناعي (مثل "openai" أو "anthropic").
  • provider.model — اسم نموذج الترجمة بالذكاء الاصطناعي (مثل "gpt-4o-mini" لـ OpenAI أو "claude-3-haiku" لـ Anthropic).
  • provider.prompt — مطالبة النظام التي توجه سلوك الترجمة. يتم استبدال العناصر النائبة {source} و {target} برموز اللغة الفعلية أثناء التشغيل.

تكوين الحاويات

تحدد الحاويات أنماط اكتشاف الملفات وقواعد المعالجة. تمثل كل حاوية تنسيق ملف بأنماط تضمين/استبعاد محددة.

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json", "app/[locale]/*.json"],
      "exclude": ["locales/[locale]/internal.json"],
      "lockedKeys": ["app/version", "config/apiUrl"],
      "injectLocale": ["settings/language"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"],
      "exclude": ["docs/[locale]/drafts/*.md"]
    }
  }
}

عناصر التكوين:

  • buckets.[bucket-type] — مجموعة التكوين لحاوية تنسيق ملف محدد.
    • buckets.[bucket-type].include — مصفوفة أنماط اكتشاف الملفات. يمكن أن تحتوي على سلاسل نصية أو كائنات.
      • buckets.[bucket-type].include.[string] — نمط مسار ملف بسيط مع عنصر نائب [locale].
      • buckets.[bucket-type].include.[object] — تكوين نمط متقدم بالخصائص التالية:
        • path — نمط مسار الملف مع عنصر نائب [locale].
        • delimiter — الفاصل المستخدم لرموز اللغة. الافتراضي هو - (شرطة)، ويمكن تجاوزه إلى _ (شرطة سفلية). يتجاوز الفاصل من تكوين اللغة.
    • buckets.[bucket-type].exclude — مصفوفة أنماط استبعاد الملفات لتخطيها أثناء المعالجة.
    • buckets.[bucket-type].lockedKeys — مصفوفة المفاتيح التي لا ينبغي ترجمتها. تستخدم الشرطة المائلة / كفاصل للمفاتيح المتداخلة. استخدم العلامة النجمية * لمطابقة مفاتيح متعددة.
    • buckets.[bucket-type].ignoredKeys — مصفوفة المفاتيح التي يجب تجاهلها أثناء الترجمة. تستخدم الشرطة المائلة / كفاصل للمفاتيح المتداخلة. استخدم العلامة النجمية * لمطابقة مفاتيح متعددة.
    • buckets.[bucket-type].injectLocale — مصفوفة المفاتيح التي يجب حقن رمز اللغة فيها تلقائيًا. تستخدم الشرطة المائلة / كفاصل للمفاتيح المتداخلة. استخدم العلامة النجمية * لمطابقة مفاتيح متعددة.

بنية النمط الأساسية

أنماط التضمين تستخدم صيغة شبيهة بـ glob مع العنصر النائب الخاص [locale]:

  • locales/[locale].json ← locales/en.json، locales/es.json
  • docs/[locale]/*.md ← docs/en/*.md، docs/es/*.md

أنماط الاستبعاد تمنع معالجة ملفات محددة ضمن أنماط التضمين.

خيارات النمط المتقدمة

محددات اللغة المخصصة لتنسيقات أسماء الملفات المختلفة:

{
  "include": [
    "standard/[locale].json",
    {
      "path": "underscore/[locale].json",
      "delimiter": "_"
    }
  ]
}

المحددات المتاحة:

  • - (شرطة): en-US.json
  • _ (شرطة سفلية): en_US.json

نصيحة: يتحكم هذا الإعداد في المحدد المستخدم في اسم الملف، لذا يمكنك استخدامه في إعداد monorepo حيث تحتوي المشاريع المختلفة على اصطلاحات محددات مختلفة.

أنواع الحاويات المدعومة

Lingo.dev CLI يدعم أنواع الحاويات التالية لتنسيقات الملفات المختلفة:

  • android — ملفات موارد Android XML
  • csv — ملفات CSV مع ملفات منفصلة لكل لغة مستهدفة
  • flutter — ملفات Flutter ARB
  • html — ملفات HTML مع ملفات منفصلة لكل لغة مستهدفة
  • json — ملفات JSON مع ملفات منفصلة لكل لغة مستهدفة
  • markdown — ملفات Markdown مع ملفات منفصلة لكل لغة مستهدفة
  • mdx — ملفات MDX مع ملفات منفصلة لكل لغة مستهدفة
  • xcode-strings — ملفات Xcode .strings القديمة
  • xcode-stringsdict — ملفات Xcode .stringsdict للجمع
  • xcode-xcstrings — ملفات كتالوج سلاسل Xcode
  • yaml — ملفات YAML مع ملفات منفصلة لكل لغة مستهدفة
  • yaml-root-key — ملفات YAML مع مفاتيح جذر قائمة على اللغة
  • properties — ملفات Java .properties
  • po — ملفات GNU gettext .po
  • xml — ملفات XML عامة مع ملفات منفصلة لكل لغة مستهدفة
  • php — ملفات مصفوفات PHP
  • vue-json — ملفات Vue.js i18n JSON
  • typescript — ملفات TypeScript مع ملفات منفصلة لكل لغة مستهدفة

أمثلة التكوين

التكوين الأساسي

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

تكوين المستودع الأحادي

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en-US",
    "targets": ["es-ES", "fr-FR"]
  },
  "buckets": {
    "json": {
      "include": ["apps/web/locales/[locale].json"]
    },
    "mdx": {
      "include": ["packages/docs/content/[locale]/*.mdx"]
    },
    "xcode-xcstrings": {
      "include": ["ios/Localizable.xcstrings"]
    },
    "android": {
      "include": ["android/values-[locale]/strings.xml"]
    }
  }
}

ترحيل الإصدار

i18n.json ينفذ ترحيل إصدار ذكي يقوم تلقائيًا بتحديث تكوينك إلى إصدارات مخطط أحدث مع الحفاظ على جميع إعدادات المستخدم.

عندما يكتشف Lingo.dev CLI إصدار تكوين أقدم، فإنه:

  1. ينشئ نسخة احتياطية من ملف i18n.json الحالي
  2. يرحل التكوين إلى أحدث إصدار مخطط
  3. يحفظ جميع الإعدادات بما في ذلك الموفرين المخصصين وتكوينات الحاويات والمفاتيح المقفلة
  4. يحدث حقل الإصدار ليطابق المخطط الحالي

سلوك الترحيل:

يتم تشغيل الترحيل تلقائيًا أثناء أي عملية CLI تقرأ ملف التكوين. لا يلزم التدخل اليدوي، ويستمر سير عمل الترجمة دون انقطاع.

يضمن نظام الترحيل هذا بقاء تكوينات i18n.json متوافقة مع تحديثات Lingo.dev CLI مع الحفاظ على التوافق العكسي مع المشاريع الحالية.