تكامل Lingo.dev مع GitLab

تكامل Lingo.dev مع GitLab CI/CD هو تكامل آمن ومفتوح المصدر للـ CI/CD يقوم تلقائيًا بترجمة المحتوى الجديد ويمنع الترجمات غير المكتملة من الوصول إلى الإنتاج. يقوم بإنشاء طلبات الدمج أو الالتزامات مباشرة إلى فرعك، اعتمادًا على متطلبات سير عمل فريقك.

كما أنه ينفذ حل النزاعات التلقائي من خلال إعادة القاعدة (rebasing)، بحيث تبقى ترجماتك متزامنة مع الكود الخاص بك دون تدخل يدوي.

يدعم التكامل سيناريوهات سير العمل المتعددة:

1. الالتزامات المباشرة للفروع عند دفع تغييرات المحتوى
2. طلبات الدمج التي تستهدف الفروع لتحديثات الترجمة

عند الانتهاء من هذا الدليل، ستتمكن من:

1. إعداد الترجمة الآلية التي يتم تشغيلها بواسطة عمليات دفع الكود؛
2. تكوين المصادقة الآمنة باستخدام متغيرات المستودع؛
3. الاختيار بين الالتزامات المباشرة أو سير عمل طلبات الدمج؛
4. فهم كيفية تناسب الترجمة المستمرة مع العملية الحالية الخاصة بك.

لنبدأ!

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

إعداد المستودع

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

الخطوة 1. إعداد المصادقة

يحتاج تكامل Lingo.dev مع GitLab إلى الوصول إلى محرك الترجمة والمستودع الخاص بك. تتم المصادقة من خلال متغيرات المستودع التي تحافظ على أمان بيانات الاعتماد الخاصة بك.

إضافة مفتاح API الخاص بك

انتقل إلى الإعدادات الخاصة بمستودعك → CI/CD → المتغيرات، ثم أضف بيانات اعتماد محرك الترجمة الخاص بك:

لمستخدمي واجهة برمجة التطبيقات LLM الأساسية:

• اسم المتغير: OPENAI_API_KEY أو ANTHROPIC_API_KEY
• قيمة المتغير: مفتاح API الخاص بك من المزود المعني

لمستخدمي محرك Lingo.dev:

• اسم المتغير: LINGODOTDEV_API_KEY
• قيمة المتغير: مفتاح API الخاص بمشروعك من lingo.dev/app

إضافة رمز وصول GitLab

قم بإنشاء رمز وصول مخصص لعمليات المستودع:

1. اذهب إلى الإعدادات → رموز الوصول → إضافة رمز جديد
2. امنح هذه النطاقات:
   • api
   • read_repository
   • write_repository
3. أضف الرمز كمتغير مستودع:
   • اسم المتغير: GL_TOKEN
   • قيمة المتغير: رمز وصول GitLab الخاص بك

مهم: رمز وظيفة CI الافتراضي غير كافٍ. يجب عليك إنشاء رمز وصول مخصص لأن الرمز الافتراضي يفتقر إلى الأذونات اللازمة لعمليات git.

ملاحظة: بالنسبة للفروع المحمية، تأكد من أن متغيراتك مميزة أيضًا كمحمية. لن يمكن الوصول إلى المتغيرات غير المحمية في خطوط أنابيب الفروع المحمية.

الخطوة 2. إنشاء سير العمل

قم بإنشاء أو تحديث ملف .gitlab-ci.yml الخاص بك بهذا التكوين الأساسي:

lingodotdev:
  image: lingodotdev/ci-action:latest
  script:
    - echo "Done"

يستخدم هذا التكوين أحدث صورة Docker ويقوم بتشغيل محرك الترجمة تلقائيًا.

الأذونات المطلوبة

يتطلب GitLab CI/CD الوصول إلى متغيرات المستودع وعمليات git:

متغيرات المستودع:

• LINGODOTDEV_API_KEY — مطلوب لمستخدمي محرك Lingo.dev
• OPENAI_API_KEY أو ANTHROPIC_API_KEY — مطلوب لمستخدمي واجهة برمجة التطبيقات LLM الأولية
• GL_TOKEN — مطلوب لعمليات دفع git وإنشاء طلبات الدمج

نطاقات رمز الوصول:

• api — إنشاء وإدارة طلبات الدمج
• read_repository — الوصول إلى محتوى المستودع
• write_repository — دفع التعديلات وإنشاء الفروع

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

الخطوة 3. اختيار وضع سير العمل

تكامل Lingo.dev مع GitLab يدعم وضعين تشغيليين اعتمادًا على متطلبات مراجعة الكود لفريقك.

وضع الالتزام المباشر (الافتراضي)

يقوم التكامل بإجراء التزامات الترجمات مباشرة إلى الفرع الخاص بك:

lingodotdev:
  image: lingodotdev/ci-action:latest
  script:
    - echo "Done"

يعمل هذا الوضع بشكل أفضل لـ:

• المطورين المنفردين أو الفرق الصغيرة
• فروع الميزات التي ستتم مراجعتها قبل الدمج
• المشاريع التي لا تتطلب فيها تحديثات الترجمة مراجعة منفصلة

وضع طلب الدمج

ينشئ التكامل طلبات دمج لتحديثات الترجمة:

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    LINGODOTDEV_PULL_REQUEST: "true"
  script:
    - echo "Done"

الإعداد المطلوب لوضع طلب الدمج

متغيرات المستودع: يجب تكوين كل من LINGODOTDEV_API_KEY و GL_TOKEN كمتغيرات مستودع.

متطلبات رمز الوصول: يجب أن يتضمن GL_TOKEN الخاص بك نطاق api لإنشاء وإدارة طلبات الدمج.

يعمل هذا الوضع بشكل أفضل لـ:

• الفرق ذات متطلبات مراجعة الكود الصارمة
• المشاريع التي تحتاج فيها تغييرات الترجمة إلى موافقة منفصلة
• سير العمل الذي يتطلب مراجعة صريحة لجميع التغييرات

الخطوة 4. سيناريوهات سير العمل

يتكيف تكامل Lingo.dev مع GitLab مع مختلف سير عمليات التطوير. فهم هذه السيناريوهات يساعدك على اختيار التكوين المناسب لفريقك.

السيناريو 1: تحديثات فرع الميزة (الالتزامات المباشرة)

المحفز: الدفع إلى فروع الميزات الإجراء: يلتزم بتحديثات الترجمة مباشرة إلى فرع الميزة

lingodotdev:
  image: lingodotdev/ci-action:latest
  script:
    - echo "Done"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH = /^feat/

التدفق: يتم دفع تغييرات المحتوى إلى فرع الميزة → يلتزم التكامل بالترجمات إلى نفس الفرع

هذا يبقي تحديثات الترجمة ضمن فرع الميزة، مما يضمن مراجعة الترجمات جنبًا إلى جنب مع التغييرات الأصلية.

السيناريو 2: طلبات الدمج للتحديثات (وضع طلب الدمج)

المحفز: الدفع إلى أي فرع مكوّن الإجراء: ينشئ طلب دمج مع تحديثات الترجمة

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    LINGODOTDEV_API_KEY: $MY_LINGODOTDEV_API_KEY # or OPENAI_API_KEY/ANTHROPIC_API_KEY
    LINGODOTDEV_PULL_REQUEST: "true"
    LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
  script:
    - echo "Done"

التدفق: يتم دفع تغييرات المحتوى إلى الفرع → ينشئ التكامل طلب دمج مع الترجمات

هذا يحافظ على مراجعات منفصلة لتحديثات الترجمة.

التكوين المتقدم

قم بتخصيص سلوك التكامل باستخدام متغيرات إضافية:

مثال مع محرك Lingo.dev:

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    LINGODOTDEV_API_KEY: $MY_LINGODOTDEV_API_KEY
    GL_TOKEN: $MY_GL_TOKEN
    LINGODOTDEV_PULL_REQUEST: "true"
    LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
    LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations via @lingodotdev"
    LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
    LINGODOTDEV_PROCESS_OWN_COMMITS: "true"
  script:
    - echo "Done"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH = /^feat/

مثال مع واجهة برمجة تطبيقات LLM الخام:

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    OPENAI_API_KEY: $MY_OPENAI_API_KEY # or ANTHROPIC_API_KEY
    GL_TOKEN: $MY_GL_TOKEN
    LINGODOTDEV_PULL_REQUEST: "true"
    LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
    LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations via @lingodotdev"
    LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
    LINGODOTDEV_PROCESS_OWN_COMMITS: "true"
  script:
    - echo "Done"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH = /^feat/

خيارات التكوين:

• LINGODOTDEV_API_KEY — مفتاح واجهة برمجة تطبيقات محرك Lingo.dev الخاص بك، إذا كنت تستخدم محرك Lingo.dev
• OPENAI_API_KEY — مفتاح واجهة برمجة تطبيقات OpenAI الخاص بك، إذا كنت تستخدم واجهة برمجة تطبيقات LLM الخام
• ANTHROPIC_API_KEY — مفتاح واجهة برمجة تطبيقات Anthropic الخاص بك، إذا كنت تستخدم واجهة برمجة تطبيقات LLM الخام
• LINGODOTDEV_PULL_REQUEST — إنشاء طلب دمج بدلاً من الالتزام المباشر (الافتراضي: false)
• LINGODOTDEV_PULL_REQUEST_TITLE — عنوان طلب الدمج المخصص (الافتراضي: feat: update translations via @lingodotdev)
• LINGODOTDEV_COMMIT_MESSAGE — رسالة الالتزام المخصصة (الافتراضي: feat: update translations via @lingodotdev)
• LINGODOTDEV_WORKING_DIRECTORY — تشغيل التكامل في دليل فرعي (الافتراضي: .)
• LINGODOTDEV_PROCESS_OWN_COMMITS — معالجة الالتزامات التي تم إجراؤها بواسطة هذا التكامل (الافتراضي: false)

استكشاف الأخطاء وإصلاحها

الأخطاء الشائعة وحلولها: