GitHub Actions

Usa GitHub Actions quando desideri che un repository traduca automaticamente la documentazione modificata e apra una pull request con gli output generati.

La maggior parte dei repository dovrebbe utilizzare la configurazione standard con GITHUB_TOKEN. Usa la configurazione con GitHub App solo quando la tua organizzazione limita le autorizzazioni del token predefinito o richiede l'autenticazione basata su app.

Prerequisiti

Prima di creare il workflow, configura i segreti del servizio AI necessari per l'esecuzione della traduzione.

La traduzione di testo richiede un provider di modelli linguistici:

• 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

La traduzione delle immagini richiede inoltre Azure AI Vision:

• AZURE_AI_SERVICE_API_KEY
• AZURE_AI_SERVICE_ENDPOINT

Consulta Configurazione e Configurazione di Azure AI per i dettagli sulla configurazione locale.

Standard Setup

Usa questa configurazione per la maggior parte dei repository pubblici e privati.

Step 1: Add Repository Secrets

Nel repository di destinazione, apri Settings > Secrets and variables > Actions, quindi aggiungi i segreti del provider che il tuo workflow utilizzerà.

Step 2: Enable Workflow Permissions

Apri Settings > Actions > General.

Sotto Autorizzazioni del workflow:

1. Seleziona Lettura e scrittura.
2. Abilita Consenti a GitHub Actions di creare e approvare pull request.
3. Salva l'impostazione.

Step 3: Add the Workflow

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

Cambia translate -l "es fr de" -y con le lingue di destinazione e i flag di contenuto necessari al tuo progetto. Per repository di grandi dimensioni, aggiungi un filtro paths: sotto on: in modo che il workflow venga eseguito solo quando la documentazione cambia.

GitHub App Setup

Usa questa configurazione quando GITHUB_TOKEN non può creare commit o pull request nella tua organizzazione.

Step 1: Create or Install a GitHub App

Crea un'app GitHub con accesso di lettura/scrittura a Contents e Pull requests, oppure installa l'app fornita dall'organizzazione se la tua organizzazione ne mantiene già una.

Annota:

• App ID
• Contenuto della chiave privata

Memorizzali come segreti del repository:

• GH_APP_ID
• GH_APP_PRIVATE_KEY

Step 2: Generate an App Token

Usa lo stesso workflow della configurazione standard, ma aggiungi un passaggio app-token prima del passaggio della pull request:

      - 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

I runner ospitati da GitHub hanno una durata massima per job. Repository di grandi dimensioni o molti linguaggi di destinazione possono superare tale limite.

Per carichi di lavoro di traduzione elevati:

• Traduci meno lingue per esecuzione.
• Usa flag di contenuto come -md, -nb o -img.
• Usa un runner self-hosted quando la dimensione del repository o la latenza del modello rendono i runner ospitati inaffidabili.

Review in CI

Usa co-op-review quando una pull request deve convalidare le traduzioni generate senza invocare provider LLM o Vision.

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

co-op-review è un comando di revisione deterministico in beta. I suoi controlli e lo schema di output possono evolvere, ma è progettato per essere sicuro per la CI perché non scrive file né chiama provider di modelli.