الحاويات

مقدمة

في ملف i18n.json، تحدد خاصية buckets:

• المحللات المستخدمة لاستخراج المحتوى القابل للترجمة من الملفات
• مكان وجود المحتوى القابل للترجمة في نظام الملفات
• ميزات معينة خاصة بالحاويات، مثل قفل المفاتيح

يعد تكوين الحاويات خطوة أساسية في إعداد خط أنابيب الترجمة باستخدام Lingo.dev CLI.

أنواع الحاويات

Lingo.dev CLI متوافق مع مجموعة واسعة من تنسيقات الملفات المعيارية في الصناعة (وبعض التنسيقات الأقل معيارية). كل من هذه التنسيقات مرتبط بنوع معين من الحاويات.

أنواع الحاويات مرادفة بشكل عام لتنسيقات الملفات، ولكن ليس دائمًا بعلاقة واحد لواحد. على سبيل المثال، تتعامل حاويتا "json" و"json-dictionary" مع المحتوى القابل للترجمة في ملفات JSON، لكن CLI يتوقع أن تكون الملفات منظمة بشكل مختلف، لذا فإن الحاويات متميزة.

وضع الإخراج

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

سبب هذا الاختلاف في السلوك هو أن أيًا من الخيارين يكون أكثر منطقية اعتمادًا على الحاوية. لا يوجد خيار واحد صحيح يمكن أن يعمل لجميع أنواع الحاويات.

على سبيل المثال، عند استخدام حاوية CSV، يتم تعديل ملفات .csv مباشرة. هذا لأنه من المعتاد أن تخزن ملفات CSV المحتوى المترجم لكل لغة في نفس الملف، في أعمدة منفصلة:

KEY,en,es
welcome_message,Welcome to our application,Bienvenido a nuestra aplicación

عند استخدام حاوية Markdown، من ناحية أخرى، يتم إخراج المحتوى المترجم إلى ملفات منفصلة لأنه ليس من المعتاد تخزين جميع الاختلافات المترجمة في ملف واحد.

من المهم فهم ذلك لسببين:

• ليس من الواضح على الفور أن الحاويات المختلفة تتصرف بطرق مختلفة.
• يجب عليك تعريف أنماط include و exclude بشكل مختلف بناءً على كيفية إخراج الملفات.

إنشاء الحاويات

لإنشاء حاوية، أضف إدخالاً إلى كائن buckets في ملف i18n.json:

{
  "buckets": {
    "json": {}
  }
}

يجب أن يتوافق كل مفتاح مع أحد أنواع الحاويات المدعومة، بينما يجب أن تكون القيمة كائناً يحتوي على تكوين صالح لتلك الحاوية.

يجب أن تحتوي خاصية buckets على إدخال صالح واحد على الأقل.

تضمين الملفات

كحد أدنى، يجب أن تحتوي الحاويات على خاصية include التي تحدد المحتوى المراد ترجمته:

{
  "buckets": {
    "json": {
      "include": []
    }
  }
}

يجب أن تكون هذه الخاصية مصفوفة من السلاسل النصية.

يمكن أن تكون كل سلسلة نصية واحدة مما يلي:

• مسار ملف (مثل "some/dir/labels.json")
• نمط glob (مثل "some/dir/*.json")

هذه القيم دائماً نسبية إلى ملف i18n.json.

عنصر نائب [locale]

عندما تُخرج الحاوية المحتوى المترجم إلى ملفات منفصلة (أي أنها لا تعدل ملفاً موجوداً)، يجب أن تحتوي أنماط include على عنصر نائب خاص [locale]:

{
  "buckets": {
    "json": {
      "include": ["[locale]/*.mdx"]
    }
  }
}

يتم استبدال هذا العنصر النائب في وقت التشغيل ويؤثر على المكان الذي يقوم فيه CLI بـ:

• البحث عن المحتوى المصدر
• إخراج المحتوى المترجم

على سبيل المثال، إذا كانت اللغة المصدر هي "en" واللغة المستهدفة هي "es"، فإن [locale]/*.mdx يجد جميع ملفات MDX في دليل en/ ويُخرج الملفات المترجمة إلى دليل es/.

موضع العنصر النائب [locale] ليس مهماً، مما يعني أن جميع هذه الأنماط صالحة:

• content/[locale]/*.mdx
• [locale]/*.mdx
• *.[locale].mdx

أنماط glob العودية

Lingo.dev CLI لا يدعم أنماط glob العودية. هذا يعني أن الأنماط مثل "**/*.json" لا تعمل. إذا حاولت تكوين نمط glob عودي، سيتم طرح خطأ.

امتدادات الملفات

في أنماط include، امتدادات الملفات لا تهم. سيحاول Lingo.dev CLI تحليل أي ملفات محددة بناءً على نوع الحاوية، بغض النظر عن الامتداد.

استبعاد الملفات

بالإضافة إلى أنماط include، تدعم الحاويات أيضًا أنماط exclude لاستبعاد مسارات الملفات أو أنماط glob من الترجمة:

{
  "buckets": {
    "json": {
      "include": ["[locale]/*.mdx"],
      "exclude": ["[locale]/ignored/*.mdx"],
    }
  }
}

تتبع هذه الأنماط نفس القواعد الخاصة بأنماط include.

ميزات خاصة بالحاوية

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

تتضمن الميزات الخاصة بالحاوية:

• تجاهل المفاتيح
• قفل المفاتيح
• ملاحظات المترجم

لمعرفة المزيد عن هذه الميزات، راجع الوثائق المرتبطة.