اقدامات GitHub

از اقدامات GitHub زمانی استفاده کنید که می‌خواهید یک مخزن به‌صورت خودکار اسناد تغییر یافته را ترجمه کند و یک pull request با خروجی‌های تولیدشده باز کند.

بیشتر مخازن باید از تنظیم استاندارد 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

مشاهده کنید Configuration و Azure AI Setup برای جزئیات پیکربندی محلی.

تنظیم استاندارد

از این تنظیم برای اکثر مخازن عمومی و خصوصی استفاده کنید.

گام 1: افزودن اسرار مخزن

در مخزن هدف خود باز کنید Settings > Secrets and variables > Actions، سپس اسرار ارائه‌دهنده‌ای که گردش‌کار شما استفاده خواهد کرد را اضافه کنید.

گام 2: فعال‌سازی مجوزهای گردش‌کار

باز کنید Settings > Actions > General.

زیر Workflow permissions:

1. انتخاب کنید Read and write permissions.
2. فعال کنید Allow GitHub Actions to create and approve pull requests.
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 نمی‌تواند در سازمان شما کمیت یا pull request ایجاد کند.

گام 1: ایجاد یا نصب یک GitHub App

یک GitHub App با دسترسی خواندن/نوشتن به Contents و Pull requests ایجاد کنید، یا اپ ارائه‌شده توسط سازمان را نصب کنید اگر سازمان شما قبلاً یکی را نگهداری می‌کند.

یادداشت کنید:

• App ID
• محتوای کلید خصوصی

آن‌ها را به‌عنوان اسرار مخزن ذخیره کنید:

• GH_APP_ID
• GH_APP_PRIVATE_KEY

گام 2: تولید توکن App

از همان گردش‌کار مشابه تنظیم استاندارد استفاده کنید، اما یک گام app-token قبل از گام pull request اضافه کنید:

      - 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 استفاده کنید.
• زمانی که اندازهٔ مخزن یا تأخیر مدل باعث می‌شود رانرهای میزبانی‌شده قابل‌اعتماد نباشند، از یک رانر self-hosted استفاده کنید.

بازبینی در CI

از co-op-review استفاده کنید وقتی که یک pull request باید ترجمه‌های تولیدشده را بدون فراخوانی ارائه‌دهندگان LLM یا Vision اعتبارسنجی کند.

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

co-op-review یک فرمان بازبینی تعیین‌شونده بتا است. چک‌ها و ساختار خروجی آن ممکن است تکامل یابد، اما طراحی شده تا برای CI ایمن باشد زیرا فایل نمی‌نویسد و از ارائه‌دهندگان مدل فراخوانی نمی‌کند.