GitHub Actions

استخدم GitHub Actions عندما تريد أن يقوم المستودع بترجمة الوثائق المعدّلة تلقائيًا وفتح طلب سحب بالنتائج المولدة.

يجب على معظم المستودعات استخدام إعداد GITHUB_TOKEN القياسي. استخدم إعداد GitHub App فقط عندما تقوم منظمتك بتقييد أذونات الرمز المميز الافتراضية أو تتطلب مصادقة معتمدة على التطبيق.

المتطلبات المسبقة

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

تتطلب ترجمة النص مزود نموذج لغة واحد:

• Azure OpenAI: AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_MODEL_NAME, AZURE_OPENAI_CHAT_DEPLOYMENT_NAME, AZURE_OPENAI_API_VERSION
• OpenAI: OPENAI_API_KEY, OPENAI_CHAT_MODEL_ID, بالإضافة إلى اختياري OPENAI_ORG_ID و OPENAI_BASE_URL

تتطلب ترجمة الصور بالإضافة إلى ذلك Azure AI Vision:

• AZURE_AI_SERVICE_API_KEY
• AZURE_AI_SERVICE_ENDPOINT

انظر التكوين وإعداد Azure AI للحصول على تفاصيل التكوين المحلي.

الإعداد القياسي

استخدم هذا الإعداد لمعظم المستودعات العامة والخاصة.

الخطوة 1: إضافة أسرار المستودع

في المستودع المستهدف، افتح الإعدادات > الأسرار والمتغيرات > الإجراءات، ثم أضف أسرار المزود التي سيستخدمها سير العمل لديك.

الخطوة 2: تمكين أذونات سير العمل

افتح الإعدادات > الإجراءات > عام.

تحت أذونات سير العمل:

1. اختر أذونات القراءة والكتابة.
2. فعّل السماح لـ GitHub Actions بإنشاء والموافقة على طلبات السحب.
3. احفظ الإعداد.

الخطوة 3: إضافة سير العمل

قم بإنشاء .github/workflows/co-op-translator.yml:

name: Co-op Translator

on:
  push:
    branches:
      - main

jobs:
  co-op-translator:
    runs-on: ubuntu-latest

    permissions:
      contents: write
      pull-requests: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.10"

      - name: Install Co-op Translator
        run: |
          python -m pip install --upgrade pip
          pip install co-op-translator

      - name: Run Co-op Translator
        env:
          PYTHONIOENCODING: utf-8
          AZURE_AI_SERVICE_API_KEY: ${{ secrets.AZURE_AI_SERVICE_API_KEY }}
          AZURE_AI_SERVICE_ENDPOINT: ${{ secrets.AZURE_AI_SERVICE_ENDPOINT }}
          AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }}
          AZURE_OPENAI_ENDPOINT: ${{ secrets.AZURE_OPENAI_ENDPOINT }}
          AZURE_OPENAI_MODEL_NAME: ${{ secrets.AZURE_OPENAI_MODEL_NAME }}
          AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ secrets.AZURE_OPENAI_CHAT_DEPLOYMENT_NAME }}
          AZURE_OPENAI_API_VERSION: ${{ secrets.AZURE_OPENAI_API_VERSION }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          OPENAI_ORG_ID: ${{ secrets.OPENAI_ORG_ID }}
          OPENAI_CHAT_MODEL_ID: ${{ secrets.OPENAI_CHAT_MODEL_ID }}
          OPENAI_BASE_URL: ${{ secrets.OPENAI_BASE_URL }}
        run: |
          translate -l "es fr de" -y

      - name: Create Pull Request with translations
        uses: peter-evans/create-pull-request@v5
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          commit-message: "Update translations via Co-op Translator"
          title: "Update translations via Co-op Translator"
          body: |
            This PR updates translations for recent changes to the main branch.

            Generated by Co-op Translator.
          branch: update-translations
          base: main
          labels: translation, automated-pr
          delete-branch: true
          add-paths: |
            translations/
            translated_images/

غيّر translate -l "es fr de" -y إلى اللغات المستهدفة وعلامات المحتوى التي يحتاجها مشروعك. بالنسبة للمستودعات الكبيرة، أضف مرشح paths: تحت on: حتى يعمل سير العمل فقط عند تغيّر الوثائق.

إعداد GitHub App

استخدم هذا الإعداد عندما لا يمكن لـ GITHUB_TOKEN إنشاء الالتزامات أو طلبات السحب في مؤسستك.

الخطوة 1: إنشاء أو تثبيت GitHub App

أنشئ GitHub App بصلاحية قراءة/كتابة على Contents و Pull requests، أو ثبّت التطبيق المقدم من المؤسسة إذا كانت منظمتك تحتفظ بأحدها بالفعل.

سجل:

• App ID
• محتوى المفتاح الخاص

خزّنها كأسرار في المستودع:

• GH_APP_ID
• GH_APP_PRIVATE_KEY

الخطوة 2: توليد رمز التطبيق

استخدم نفس سير العمل كما في الإعداد القياسي، لكن أضف خطوة app-token قبل خطوة طلب السحب:

      - name: Authenticate GitHub App
        id: generate_token
        uses: tibdex/github-app-token@v1
        with:
          app_id: ${{ secrets.GH_APP_ID }}
          private_key: ${{ secrets.GH_APP_PRIVATE_KEY }}

      - name: Create Pull Request with translations
        uses: peter-evans/create-pull-request@v5
        with:
          token: ${{ steps.generate_token.outputs.token }}
          commit-message: "Update translations via Co-op Translator"
          title: "Update translations via Co-op Translator"
          branch: update-translations
          base: main
          delete-branch: true
          add-paths: |
            translations/
            translated_images/

قيود المشغّل

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

لأحمال الترجمة الكبيرة:

• ترجم عددًا أقل من اللغات في كل تشغيل.
• استخدم أعلام المحتوى مثل -md, -nb, أو -img.
• استخدم مشغّلًا مستضافًا ذاتيًا عندما يجعل حجم المستودع أو زمن استجابة النموذج المشغّلات المستضافة غير موثوقة.

المراجعة في CI

استخدم co-op-review عندما يجب أن يتحقق طلب السحب من الترجمات المولدة دون استدعاء مزوّدي LLM أو Vision.

      - name: Review translated outputs
        run: |
          co-op-review --changed-from "origin/${{ github.base_ref }}" --format github

co-op-review هو أمر مراجعة حتمي في طور البيتا. قد تتطور فحوصاته ومخطط الإخراج، لكنه مصمم ليكون آمنًا لـ CI لأنه لا يكتب ملفات ولا يستدعي مزوّدي النماذج.