co-op-translator

Co-op Translator GitHub Actionの利用方法（パブリックセットアップ）

対象者: このガイドは、ほとんどのパブリックまたはプライベートリポジトリで、標準のGitHub Actions権限が十分なユーザー向けです。組み込みのGITHUB_TOKENを利用します。

Co-op Translator GitHub Actionを使えば、リポジトリのドキュメント翻訳を自動化できます。このガイドでは、ソースのMarkdownファイルや画像が変更された際に、翻訳を更新したプルリクエストを自動作成する設定方法を説明します。

[!IMPORTANT]

ガイドの選び方:

このガイドは標準のGITHUB_TOKENを使ったシンプルなセットアップについて説明しています。ほとんどのユーザーに推奨される方法で、GitHub Appのプライベートキー管理が不要です。

事前準備

GitHub Actionの設定前に、必要なAIサービスの認証情報を用意してください。

1. 必須: AI言語モデルの認証情報 サポートされている言語モデルのいずれかの認証情報が必要です:

Azure OpenAI: エンドポイント、APIキー、モデル/デプロイメント名、APIバージョンが必要です。
OpenAI: APIキー（オプション: Org ID、Base URL、Model ID）。
詳細はサポートされているモデルとサービスをご覧ください。

2. オプション: AI Vision認証情報（画像翻訳用）

画像内のテキストも翻訳したい場合のみ必要です。
Azure AI Vision: エンドポイントとサブスクリプションキーが必要です。
未設定の場合、アクションはMarkdownのみモードで動作します。

セットアップと設定

標準のGITHUB_TOKENを使って、Co-op Translator GitHub Actionをリポジトリに設定する手順です。

ステップ1: 認証の仕組みを理解する（`GITHUB_TOKEN`の利用）

このワークフローは、GitHub Actionsが提供する組み込みのGITHUB_TOKENを利用します。このトークンは、ステップ3で設定した権限に基づき、リポジトリ操作の権限を自動的に付与します。

ステップ2: リポジトリシークレットの設定

AIサービスの認証情報のみを、リポジトリの設定で暗号化されたシークレットとして追加します。

対象のGitHubリポジトリにアクセスします。
Settings > Secrets and variables > Actionsに進みます。
Repository secretsの下で、必要なAIサービスごとにNew repository secretをクリックして追加します。

（画像説明: シークレット追加箇所）

必要なAIサービスシークレット（事前準備に応じてすべて追加してください）:

シークレット名	説明	値の取得元
`AZURE_AI_SERVICE_API_KEY`	Azure AI Service（Computer Vision）のキー	Azure AI Foundry
`AZURE_AI_SERVICE_ENDPOINT`	Azure AI Service（Computer Vision）のエンドポイント	Azure AI Foundry
`AZURE_OPENAI_API_KEY`	Azure OpenAIサービスのキー	Azure AI Foundry
`AZURE_OPENAI_ENDPOINT`	Azure OpenAIサービスのエンドポイント	Azure AI Foundry
`AZURE_OPENAI_MODEL_NAME`	Azure OpenAIモデル名	Azure AI Foundry
`AZURE_OPENAI_CHAT_DEPLOYMENT_NAME`	Azure OpenAIデプロイメント名	Azure AI Foundry
`AZURE_OPENAI_API_VERSION`	Azure OpenAIのAPIバージョン	Azure AI Foundry
`OPENAI_API_KEY`	OpenAIのAPIキー	OpenAI Platform
`OPENAI_ORG_ID`	OpenAI組織ID（オプション）	OpenAI Platform
`OPENAI_CHAT_MODEL_ID`	OpenAIモデルID（オプション）	OpenAI Platform
`OPENAI_BASE_URL`	OpenAI APIのカスタムBase URL（オプション）	OpenAI Platform

ステップ3: ワークフロー権限の設定

GitHub ActionがGITHUB_TOKEN経由でコードのチェックアウトやプルリクエスト作成を行うための権限が必要です。

リポジトリでSettings > Actions > Generalに進みます。
Workflow permissionsセクションまでスクロールします。
Read and write permissionsを選択します。これでGITHUB_TOKENにcontents: writeとpull-requests: write権限が付与されます。
Allow GitHub Actions to create and approve pull requestsのチェックボックスがオンになっていることを確認します。
Saveをクリックします。

Permission setting

ステップ4: ワークフローファイルの作成

最後に、GITHUB_TOKENを使った自動化ワークフローのYAMLファイルを作成します。

リポジトリのルートディレクトリに.github/workflows/ディレクトリがなければ作成します。
.github/workflows/内にco-op-translator.ymlというファイルを作成します。
下記の内容を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
          # === AI Service Credentials ===
          AZURE_AI_SERVICE_API_KEY: $
          AZURE_AI_SERVICE_ENDPOINT: $
          AZURE_OPENAI_API_KEY: $
          AZURE_OPENAI_ENDPOINT: $
          AZURE_OPENAI_MODEL_NAME: $
          AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: $
          AZURE_OPENAI_API_VERSION: $
          OPENAI_API_KEY: $
          OPENAI_ORG_ID: $
          OPENAI_CHAT_MODEL_ID: $
          OPENAI_BASE_URL: $
        run: |
          # =====================================================================
          # IMPORTANT: Set your target languages here (REQUIRED CONFIGURATION)
          # =====================================================================
          # Example: Translate to Spanish, French, German. Add -y to auto-confirm.
          translate -l "es fr de" -y  # <--- MODIFY THIS LINE with your desired languages

      - name: Create Pull Request with translations
        uses: peter-evans/create-pull-request@v5
        with:
          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.

            ### 📋 Changes included
            - Translated contents are available in the `translations/` directory
            - Translated images are available in the `translated_images/` directory

            ---
            🌐 Automatically generated by the [Co-op Translator](https://github.com/Azure/co-op-translator) GitHub Action.
          branch: update-translations
          base: main
          labels: translation, automated-pr
          delete-branch: true
          add-paths: |
            translations/
            translated_images/

ワークフローのカスタマイズ:
- [!IMPORTANT] 対象言語: Run Co-op Translatorステップ内のtranslate -l "..." -yコマンドの言語コードリストは、必ずプロジェクトに合わせて見直し・修正してください。例のリスト（ar de es...）は置き換えや調整が必要です。
- トリガー（on:）: 現在の設定ではmainへのpushごとに実行されます。大規模リポジトリの場合は、YAML内のコメント例のようにpaths:フィルターを追加し、関連ファイル（例: ドキュメントソース）が変更された時のみ実行することで、ランナーの消費を抑えられます。
- PR詳細: Create Pull Requestステップのcommit-message、title、body、branch名、labelsなども必要に応じてカスタマイズしてください。

ワークフローの実行

[!WARNING]
GitHubホストランナーの時間制限:
ubuntu-latestなどのGitHubホストランナーは最大実行時間が6時間です。
ドキュメント量が多い場合、翻訳処理が6時間を超えるとワークフローは自動的に終了します。
対策として:

セルフホストランナーの利用（時間制限なし）

実行ごとの対象言語数を減らす

co-op-translator.ymlファイルがmainブランチ（またはon:トリガーで指定したブランチ）にマージされると、そのブランチへの変更がpushされるたびに（pathsフィルターを設定していれば該当ファイル変更時のみ）ワークフローが自動実行されます。

免責事項：本書類は、AI翻訳サービス Co-op Translator を使用して翻訳されています。正確性には努めておりますが、自動翻訳には誤りや不正確な表現が含まれる場合がありますのでご注意ください。原文（元の言語の文書）が正式な情報源となります。重要な情報については、専門の人間による翻訳を推奨します。本翻訳の利用によって生じたいかなる誤解や誤認についても、当方は責任を負いかねます。

This site is open source. Improve this page.