GitHub Actions¶

리포지토리가 변경된 문서를 자동으로 번역하고 생성된 결과물로 풀 리퀘스트를 열도록 하려면 GitHub Actions를 사용하세요.

대부분의 리포지토리는 표준 GITHUB_TOKEN 설정을 사용해야 합니다. 조직에서 기본 토큰 권한을 제한하거나 앱 기반 인증을 요구하는 경우에만 GitHub App 설정을 사용하세요.

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

자세한 로컬 구성 방법은 구성 및 Azure AI 설정을 참조하세요.

Standard Setup¶

이 설정은 대부분의 공개 및 비공개 리포지토리에 사용하세요.

Step 1: Add Repository Secrets¶

대상 리포지토리에서 Settings > Secrets and variables > Actions를 열고 워크플로에서 사용할 공급자 시크릿을 추가하세요.

Actions 시크릿 선택

Step 2: Enable Workflow Permissions¶

Settings > Actions > General을 엽니다.

Under Workflow permissions:

Select Read and write permissions.
Enable Allow GitHub Actions to create and approve pull requests.
Save the setting.

워크플로 권한 설정

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을 생성하거나 조직에서 이미 관리하는 앱이 있으면 해당 앱을 설치하세요.

다음을 기록하세요:

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에 안전하도록 설계되었습니다.