GitHub Actions¶

Use GitHub Actions when you want a repository to translate changed documentation automatically and open a pull request with the generated outputs.

Most repositories should use the standard GITHUB_TOKEN setup. Use the GitHub App setup only when your organization restricts the default token permissions or requires app-based authentication.

前提条件¶

ワークフローを作成する前に、翻訳の実行に必要な AI サービスのシークレットを構成してください。

テキスト翻訳には 1 つの言語モデルプロバイダーが必要です:

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 を開き、ワークフローが使用するプロバイダーのシークレットを追加します。

Actions のシークレットを選択

ステップ 2: ワークフローの権限を有効にする¶

設定 > Actions > 一般を開きます。

ワークフローの権限 の下で:

Read and write permissions を選択します。
Allow GitHub Actions to create and approve pull requests を有効にします。
設定を保存します。

ワークフローの権限設定

ステップ 3: ワークフローを追加¶

Create .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

それらをリポジトリのシークレットとして保存します:

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 ホストのランナーには最大ジョブ時間があります。大きなリポジトリや多数のターゲット言語はその制限を超える可能性があります。

大規模な翻訳ワークロードの場合:

1 回の実行で翻訳する言語数を減らす。
-md, -nb, または -img のようなコンテンツフラグを使用する。
リポジトリのサイズやモデルのレイテンシーによりホストされたランナーが信頼できない場合は、セルフホステッドランナーを使用する。

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 に対して安全になるよう設計されています。