GitHub Actions

Verwenden Sie GitHub Actions, wenn ein Repository geänderte Dokumentation automatisch übersetzen und einen Pull Request mit den erzeugten Ausgaben öffnen soll.

Die meisten Repositories sollten die Standard-GITHUB_TOKEN-Konfiguration verwenden. Verwenden Sie die GitHub-App-Konfiguration nur, wenn Ihre Organisation die Standard-Tokenberechtigungen einschränkt oder app-basierte Authentifizierung erfordert.

Prerequisites

Bevor Sie den Workflow erstellen, konfigurieren Sie die Secrets des KI-Dienstes, die Ihr Übersetzungslauf benötigt.

Die Textübersetzung erfordert einen Anbieter für Sprachmodelle:

• 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, sowie optional OPENAI_ORG_ID und OPENAI_BASE_URL

Die Bildübersetzung erfordert zusätzlich Azure AI Vision:

• AZURE_AI_SERVICE_API_KEY
• AZURE_AI_SERVICE_ENDPOINT

Siehe Konfiguration und Azure AI-Setup für Details zur lokalen Konfiguration.

Standard Setup

Verwenden Sie diese Konfiguration für die meisten öffentlichen und privaten Repositories.

Step 1: Add Repository Secrets

In Ihrem Ziel-Repository, öffnen Sie Settings > Secrets and variables > Actions, und fügen Sie dann die Provider-Secrets hinzu, die Ihr Workflow verwenden wird.

Step 2: Enable Workflow Permissions

Öffnen Sie Settings > Actions > General.

Unter Workflow permissions:

1. Wählen Sie Read and write permissions.
2. Aktivieren Sie Allow GitHub Actions to create and approve pull requests.
3. Speichern Sie die Einstellung.

Step 3: Add the Workflow

Erstellen Sie .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/

Ändern Sie translate -l "es fr de" -y auf die Zielsprachen und Inhalts-Flags, die Ihr Projekt benötigt. Für große Repositories fügen Sie einen paths:-Filter unter on: hinzu, damit der Workflow nur ausgeführt wird, wenn sich die Dokumentation ändert.

GitHub App Setup

Verwenden Sie diese Einrichtung, wenn GITHUB_TOKEN in Ihrer Organisation keine Commits oder Pull Requests erstellen kann.

Step 1: Create or Install a GitHub App

Erstellen Sie eine GitHub App mit Lese-/Schreibzugriff auf Contents und Pull requests, oder installieren Sie die organisationsbereitgestellte App, falls Ihre Organisation bereits eine verwaltet.

Notieren Sie:

• App ID
• Inhalt des privaten Schlüssels

Speichern Sie diese als Repository-Secrets:

• GH_APP_ID
• GH_APP_PRIVATE_KEY

Step 2: Generate an App Token

Verwenden Sie denselben Workflow wie bei der Standardkonfiguration, fügen Sie jedoch einen App-Token-Schritt vor dem Pull-Request-Schritt hinzu:

      - 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

Bei von GitHub gehosteten Runnern gibt es eine maximale Jobdauer. Große Repositories oder viele Zielsprachen können dieses Limit überschreiten.

Für große Übersetzungsaufwände:

• Übersetzen Sie pro Lauf weniger Sprachen.
• Verwenden Sie Inhalts-Flags wie -md, -nb, oder -img.
• Verwenden Sie einen selbstgehosteten Runner, wenn die Repository-Größe oder die Modelllatenz gehostete Runner unzuverlässig macht.

Review in CI

Verwenden Sie co-op-review, wenn ein Pull Request die erzeugten Übersetzungen validieren soll, ohne LLM- oder Vision-Anbieter aufzurufen.

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

co-op-review ist ein Beta-Befehl für deterministische Überprüfungen. Seine Prüfungen und das Ausgabeschema können sich weiterentwickeln, aber er ist so konzipiert, dass er für CI sicher ist, weil er keine Dateien schreibt und keine Modellanbieter aufruft.