GitHub Actions¶

Użyj GitHub Actions, gdy chcesz, aby repozytorium automatycznie tłumaczyło zmienioną dokumentację i otwierało pull request z wygenerowanymi wynikami.

Większość repozytoriów powinna korzystać ze standardowej konfiguracji GITHUB_TOKEN. Użyj konfiguracji GitHub App tylko wtedy, gdy Twoja organizacja ogranicza domyślne uprawnienia tokena lub wymaga uwierzytelniania opartego na aplikacji.

Prerequisites¶

Zanim utworzysz workflow, skonfiguruj sekrety usług AI, których będzie wymagać Twoje uruchomienie tłumaczenia.

Tłumaczenie tekstu wymaga jednego dostawcy modelu językowego:

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

Tłumaczenie obrazów dodatkowo wymaga Azure AI Vision:

AZURE_AI_SERVICE_API_KEY
AZURE_AI_SERVICE_ENDPOINT

Zobacz Konfiguracja i Ustawienia Azure AI po szczegóły konfiguracji lokalnej.

Standard Setup¶

Użyj tej konfiguracji dla większości repozytoriów publicznych i prywatnych.

Step 1: Add Repository Secrets¶

W docelowym repozytorium otwórz Settings > Secrets and variables > Actions, a następnie dodaj sekrety dostawcy, których będzie używać workflow.

Wybierz sekrety Actions

Step 2: Enable Workflow Permissions¶

Otwórz Settings > Actions > General.

W sekcji Workflow permissions:

Wybierz Read and write permissions.
Włącz Allow GitHub Actions to create and approve pull requests.
Zapisz ustawienie.

Ustawienie uprawnień workflow

Step 3: Add the Workflow¶

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/

Zmień translate -l "es fr de" -y na docelowe języki i flagi zawartości, których potrzebuje Twój projekt. Dla dużych repozytoriów dodaj filtr paths: w sekcji on:, aby workflow uruchamiał się tylko wtedy, gdy zmieniana jest dokumentacja.

GitHub App Setup¶

Użyj tej konfiguracji, gdy GITHUB_TOKEN nie może tworzyć commitów lub pull requestów w Twojej organizacji.

Step 1: Create or Install a GitHub App¶

Utwórz GitHub App z dostępem do odczytu i zapisu do Contents i Pull requests, lub zainstaluj aplikację dostarczoną przez organizację, jeśli taka istnieje.

Zanotuj:

App ID
Private key contents

Przechowuj je jako sekrety repozytorium:

GH_APP_ID
GH_APP_PRIVATE_KEY

Step 2: Generate an App Token¶

Użyj tego samego workflow co w standardowej konfiguracji, ale dodaj krok app-token przed krokiem tworzenia pull requesta:

      - 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¶

Runnery hostowane przez GitHub mają maksymalny czas trwania zadania. Duże repozytoria lub wiele docelowych języków mogą przekroczyć ten limit.

Dla dużych zadań tłumaczeniowych:

Tłumacz mniej języków na jedno uruchomienie.
Używaj flag zawartości takich jak -md, -nb lub -img.
Użyj runnera self-hosted, gdy rozmiar repozytorium lub opóźnienia modelu czynią runnery hostowane zawodnymi.

Review in CI¶

Użyj co-op-review, gdy pull request powinien zweryfikować wygenerowane tłumaczenia bez wywoływania dostawców LLM lub Vision.

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

co-op-review to beta wersja deterministycznego polecenia przeglądu. Jego sprawdzenia i schemat wyjścia mogą się zmieniać, ale zostało zaprojektowane tak, aby było bezpieczne dla CI, ponieważ nie zapisuje plików ani nie wywołuje dostawców modeli.