تكوين i18n.json

i18n.json هو ملف تكوين قياسي يتحكم في سلوك واجهة سطر أوامر Lingo.dev و**تكاملات CI/CD لـ Lingo.dev**.

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

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

الإصدار

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

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

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

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

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

تكوين اللغة المحلية

يحدد قسم اللغة المحلية اللغات التي تعالجها واجهة سطر أوامر Lingo.dev:

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

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

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

npx lingo.dev@latest show locale sources  # لغات المصدر المتاحة
npx lingo.dev@latest show locale targets  # لغات الهدف المتاحة

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

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

  • 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 — ملفات موارد XML لنظام Android
  • 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.8,
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

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

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": 1.8,
  "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 إصدارًا أقدم للتكوين، فإنها:

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

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

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

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