GitHub Actions¶

Gebruik GitHub Actions wanneer je wilt dat een repository gewijzigde documentatie automatisch vertaalt en een pull request opent met de gegenereerde outputs.

De meeste repositories zouden de standaard GITHUB_TOKEN-configuratie moeten gebruiken. Gebruik de GitHub App-configuratie alleen wanneer je organisatie de standaard tokenmachtigingen beperkt of authenticatie op basis van een app vereist.

Vereisten¶

Voordat je de workflow aanmaakt, configureer de AI-service-secrets die je vertaalopdracht nodig heeft.

Tekstvertaling vereist één taalmodelprovider:

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 optioneel OPENAI_ORG_ID en OPENAI_BASE_URL

Voor afbeeldingsvertaling is daarnaast Azure AI Vision vereist:

AZURE_AI_SERVICE_API_KEY
AZURE_AI_SERVICE_ENDPOINT

Zie Configuratie en Azure AI-configuratie voor details over lokale configuratie.

Standaardinstelling¶

Gebruik deze instelling voor de meeste openbare en privérepositories.

Stap 1: Voeg repositorysecrets toe¶

Open in je doelrepository Instellingen > Secrets en variabelen > Acties, en voeg vervolgens de provider-secrets toe die je workflow zal gebruiken.

Selecteer Actions-secrets

Stap 2: Schakel workflowmachtigingen in¶

Open Instellingen > Acties > Algemeen.

Onder Workflow-machtigingen:

Selecteer Lees- en schrijfrechten.
Schakel Sta GitHub Actions toe om pull requests te maken en goed te keuren in.
Sla de instelling op.

Instelling voor workflowmachtigingen

Stap 3: Voeg de workflow toe¶

Maak .github/workflows/co-op-translator.yml aan:

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/

Wijzig translate -l "es fr de" -y naar de doeltalen en contentvlaggen die je project nodig heeft. Voor grote repositories voeg een paths:-filter toe onder on: zodat de workflow alleen wordt uitgevoerd wanneer documentatie verandert.

GitHub App-configuratie¶

Gebruik deze configuratie wanneer GITHUB_TOKEN geen commits of pull requests kan aanmaken in je organisatie.

Stap 1: Maak een GitHub App aan of installeer er een¶

Maak een GitHub App met lees-/schrijftoegang tot Inhoud en Pull requests, of installeer de door de organisatie geleverde app als je organisatie er al een beheert.

Noteer:

App ID
Inhoud van de private key

Sla ze op als repository-secrets:

GH_APP_ID
GH_APP_PRIVATE_KEY

Stap 2: Genereer een App-token¶

Gebruik dezelfde workflow als bij de standaardconfiguratie, maar voeg een app-tokenstap toe vóór de pull request-stap:

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

Runnerlimieten¶

Door GitHub gehoste runners hebben een maximale jobduur. Grote repositories of veel doeltalen kunnen die limiet overschrijden.

Voor grote vertaalworkloads:

Vertaal minder talen per uitvoering.
Gebruik contentvlaggen zoals -md, -nb of -img.
Gebruik een zelf-gehoste runner wanneer de repositorygrootte of modellatentie hosted runners onbetrouwbaar maakt.

Beoordeling in CI¶

Gebruik co-op-review wanneer een pull request gegenereerde vertalingen moet valideren zonder LLM- of Vision-providers aan te roepen.

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

co-op-review is een bètaversie van een deterministische review-opdracht. De controles en het uitvoerschema kunnen evolueren, maar het is ontworpen om veilig te zijn voor CI omdat het geen bestanden schrijft of modelproviders aanroept.