GitHub Actions

Use GitHub Actions cuando desee que un repositorio traduzca automáticamente la documentación modificada y abra un pull request con los resultados generados.

La mayoría de los repositorios deberían usar la configuración estándar GITHUB_TOKEN. Use la configuración con GitHub App sólo cuando su organización restrinja los permisos del token predeterminado o requiera autenticación basada en aplicaciones.

Prerequisitos

Antes de crear el flujo de trabajo, configure los secretos del servicio de IA que su ejecución de traducción necesita.

La traducción de texto requiere un proveedor de modelo de lenguaje:

• 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, además de opcionales OPENAI_ORG_ID y OPENAI_BASE_URL

La traducción de imágenes requiere además Azure AI Vision:

• AZURE_AI_SERVICE_API_KEY
• AZURE_AI_SERVICE_ENDPOINT

Consulte Configuration y Azure AI Setup para obtener detalles de configuración local.

Standard Setup

Use esta configuración para la mayoría de los repositorios públicos y privados.

Step 1: Add Repository Secrets

En su repositorio de destino, abra Settings > Secrets and variables > Actions, luego agregue los secretos del proveedor que su flujo de trabajo utilizará.

Step 2: Enable Workflow Permissions

Abra Settings > Actions > General.

Bajo Workflow permissions:

1. Seleccione Read and write permissions.
2. Habilite Allow GitHub Actions to create and approve pull requests.
3. Guarde la configuración.

Step 3: Add the Workflow

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

Cambie translate -l "es fr de" -y a los idiomas de destino y las banderas de contenido que su proyecto necesite. Para repositorios grandes, agregue un filtro paths: bajo on: para que el flujo de trabajo sólo se ejecute cuando cambie la documentación.

GitHub App Setup

Use esta configuración cuando GITHUB_TOKEN no pueda crear commits o pull requests en su organización.

Step 1: Create or Install a GitHub App

Cree una GitHub App con acceso de lectura/escritura a Contenido y Solicitudes de extracción, o instale la aplicación proporcionada por la organización si su organización ya mantiene una.

Anote:

• App ID
• Contenido de la clave privada

Almacénelos como secretos del repositorio:

• GH_APP_ID
• GH_APP_PRIVATE_KEY

Step 2: Generate an App Token

Use el mismo flujo de trabajo que en la configuración estándar, pero agregue un paso de app-token antes del paso del 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

Los runners alojados por GitHub tienen una duración máxima por trabajo. Repositorios grandes o muchos idiomas de destino pueden exceder ese límite.

Para cargas de trabajo de traducción grandes:

• Traduce menos idiomas por ejecución.
• Use banderas de contenido como -md, -nb, o -img.
• Use un runner autoalojado cuando el tamaño del repositorio o la latencia del modelo haga que los runners alojados sean poco confiables.

Review in CI

Use co-op-review cuando un pull request deba validar las traducciones generadas sin llamar a proveedores LLM o Vision.

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

co-op-review es un comando de revisión determinista en beta. Sus comprobaciones y el esquema de salida pueden evolucionar, pero está diseñado para ser seguro para CI porque no escribe archivos ni llama a proveedores de modelos.