GitHub Actions

當你希望倉庫自動翻譯變更的文件並用產生的輸出建立拉取請求時，請使用 GitHub Actions。

大多數倉庫應該使用標準的 GITHUB_TOKEN 設定。只有當你的組織限制預設的 token 權限或需要以應用程式為基礎的驗證時，才使用 GitHub App 設定。

先決條件

在建立 workflow 之前，請設定你的翻譯執行所需的 AI 服務秘密（secrets）。

文字翻譯需要一個語言模型供應商：

• 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, plus optional OPENAI_ORG_ID and OPENAI_BASE_URL

影像翻譯另外需要 Azure AI Vision:

• AZURE_AI_SERVICE_API_KEY
• AZURE_AI_SERVICE_ENDPOINT

請參閱 設定 和 Azure AI 設定 以取得本機配置詳情。

標準設定

對於大多數公開和私人倉庫，請使用此設定。

第 1 步：新增倉庫秘密

在你的目標倉庫中，打開 設定 > 秘密與變數 > Actions，然後新增你的工作流程將使用的提供者 secrets。

第 2 步：啟用工作流程權限

前往 設定 > Actions > 一般。

在 工作流程權限 底下：

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/

Change translate -l "es fr de" -y to the target languages and content flags your project needs. For large repositories, add a paths: filter under on: so the workflow only runs when documentation changes.

GitHub App 設定

當 GITHUB_TOKEN 無法在你的組織中建立提交或拉取請求時，請使用此設定。

第 1 步：建立或安裝 GitHub App

建立一個對 Contents 和 Pull requests 擁有讀寫存取權的 GitHub App，或是安裝組織已提供的應用程式（若你的組織已有維護一個）。

記下：

• App ID
• Private key contents

將它們儲存為倉庫 Secrets：

• GH_APP_ID
• GH_APP_PRIVATE_KEY

第 2 步：產生 App 令牌

使用與標準設定相同的 workflow，但在建立拉取請求的步驟之前加入 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 托管的 runners 有最大工作時長。大型倉庫或大量目標語言可能會超出該限制。

對於大型翻譯工作量：

• 每次執行翻譯較少的語言數量。
• 使用內容旗標，例如 -md、-nb 或 -img。
• 當倉庫大小或模型延遲使托管 runner 不可靠時，請使用自我托管的 runner。

在 CI 中審查

當拉取請求需要驗證產生的翻譯但不呼叫 LLM 或 Vision 供應商時，請使用 co-op-review。

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

co-op-review 是一個測試版的確定性審查指令。其檢查項目與輸出結構可能會改變，但它被設計為對 CI 安全，因為它不會寫入檔案或呼叫模型供應商。