GitHub Actions

当您希望仓库自动翻译已更改的文档并使用生成的输出打开拉取请求时，请使用 GitHub Actions。

大多数仓库应使用标准的 GITHUB_TOKEN 设置。仅当您的组织限制默认令牌权限或需要基于应用的身份验证时，才使用 GitHub 应用设置。

Prerequisites

在创建工作流之前，配置翻译运行所需的 AI 服务密钥。

文本翻译需要一个语言模型提供商：

• 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

参见 Configuration 和 Azure AI Setup 以获取本地配置的详细信息。

Standard Setup

针对大多数公共和私有仓库，请使用此设置。

Step 1: Add Repository Secrets

在目标仓库中，打开 Settings > Secrets and variables > Actions，然后添加工作流将使用的提供者密钥。

Step 2: Enable Workflow Permissions

打开 Settings > Actions > General。

在 Workflow permissions 下：

1. 选择 Read and write permissions。
2. 启用 Allow GitHub Actions to create and approve pull requests。
3. 保存设置。

Step 3: Add the Workflow

创建 .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 更改为项目需要的目标语言和内容标志。对于大型仓库，请在 on: 下添加 paths: 过滤器，以便仅在文档更改时运行工作流。

GitHub App Setup

当 GITHUB_TOKEN 无法在您的组织中创建提交或拉取请求时，请使用此设置。

Step 1: Create or Install a GitHub App

创建一个对 Contents 和 Pull requests 具有读/写访问权限的 GitHub 应用，或者如果您的组织已经维护此类应用，请安装组织提供的应用。

记录：

• App ID
• Private key contents

将它们存储为仓库密钥：

• GH_APP_ID
• GH_APP_PRIVATE_KEY

Step 2: Generate an App Token

使用与标准设置相同的工作流，但在拉取请求步骤之前添加一个 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/

Runner Limits

GitHub 托管的运行器有最长的作业时长。大型仓库或许多目标语言可能会超出该限制。

对于大型翻译工作负载：

• 每次运行翻译更少的语言。
• 使用诸如 -md、-nb 或 -img 的内容标志。
• 当仓库大小或模型延迟使托管运行器不可靠时，使用自托管运行器。

Review in 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 安全，因为它不会写入文件或调用模型提供者。