GitHub Actions¶

Utilisez GitHub Actions lorsque vous souhaitez qu'un dépôt traduise automatiquement la documentation modifiée et ouvre une pull request avec les sorties générées.

La plupart des dépôts doivent utiliser la configuration standard GITHUB_TOKEN. N'utilisez la configuration GitHub App que si votre organisation restreint les permissions du jeton par défaut ou exige une authentification basée sur une application.

Prerequisites¶

Avant de créer le workflow, configurez les secrets des services IA nécessaires à votre exécution de traduction.

Text translation requires one language model provider:

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

Image translation additionally requires Azure AI Vision:

AZURE_AI_SERVICE_API_KEY
AZURE_AI_SERVICE_ENDPOINT

Voir Configuration et Configuration Azure AI pour les détails de configuration locale.

Standard Setup¶

Utilisez cette configuration pour la plupart des dépôts publics et privés.

Step 1: Add Repository Secrets¶

Dans le dépôt cible, ouvrez Paramètres > Secrets and variables > Actions, puis ajoutez les secrets du fournisseur que votre workflow utilisera.

Sélectionner les secrets Actions

Step 2: Enable Workflow Permissions¶

Ouvrez Paramètres > Actions > Général.

Sous Autorisations du workflow:

Sélectionnez Read and write permissions.
Activez Allow GitHub Actions to create and approve pull requests.
Enregistrez le paramètre.

Paramètre d'autorisation du workflow

Step 3: Add the Workflow¶

Créez .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/

Change translate -l "es fr de" -y to the target languages and content flags your project needs. For large repositories, add a paths: filter under on: so the workflow only runs when documentation changes.

GitHub App Setup¶

Utilisez cette configuration lorsque GITHUB_TOKEN ne peut pas créer de commits ou de pull requests dans votre organisation.

Step 1: Create or Install a GitHub App¶

Créez une GitHub App avec un accès lecture/écriture à Contents et Pull requests, ou installez l'app fournie par l'organisation si votre organisation en maintient déjà une.

Notez:

ID de l'application
Contenu de la clé privée

Stockez-les comme secrets du dépôt: - GH_APP_ID - GH_APP_PRIVATE_KEY

Step 2: Generate an App Token¶

Utilisez le même workflow que la configuration standard, mais ajoutez une étape app-token avant l'étape de 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¶

Les runners hébergés par GitHub ont une durée maximale par job. Les grands dépôts ou de nombreuses langues cibles peuvent dépasser cette limite.

Pour de lourdes charges de traduction: - Traduisez moins de langues par exécution. - Utilisez des flags de contenu tels que -md, -nb ou -img. - Utilisez un runner auto-hébergé lorsque la taille du dépôt ou la latence du modèle rend les runners hébergés peu fiables.

Review in CI¶

Utilisez co-op-review lorsqu'une pull request doit valider les traductions générées sans appeler les fournisseurs LLM ou Vision.

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

co-op-review est une commande de revue déterministe en version bêta. Ses vérifications et son schéma de sortie peuvent évoluer, mais elle est conçue pour être sûre en CI car elle n'écrit pas de fichiers ni n'appelle de fournisseurs de modèles.