الحاويات

مقدمة

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

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

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

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

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

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

وضع الإخراج

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

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

على سبيل المثال، عند استخدام حاوية 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")
نمط شامل (مثل "some/dir/*.json")

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

العنصر النائب `[locale]`

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

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

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

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

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

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

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

أنماط شاملة متكررة

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

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

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

استثناء الملفات

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

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

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

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

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

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

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