GitHub Actions

Use GitHub Actions quando quiser que um repositório traduza automaticamente a documentação alterada e abra um pull request com os resultados gerados.

A maioria dos repositórios deve utilizar a configuração padrão GITHUB_TOKEN. Utilize a configuração do GitHub App apenas quando a sua organização restringir as permissões do token predefinido ou exigir autenticação baseada em app.

Pré-requisitos

Antes de criar o workflow, configure os segredos dos serviços de IA de que a sua execução de tradução necessita.

A tradução de texto requer um fornecedor de modelos de linguagem:

• 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

A tradução de imagens requer adicionalmente o Azure AI Vision:

• AZURE_AI_SERVICE_API_KEY
• AZURE_AI_SERVICE_ENDPOINT

Consulte Configuração e Configuração do Azure AI para detalhes de configuração local.

Configuração padrão

Utilize esta configuração para a maioria dos repositórios públicos e privados.

Passo 1: Adicionar segredos ao repositório

No seu repositório de destino, abra Settings > Secrets and variables > Actions, depois adicione os segredos do fornecedor que o seu workflow irá usar.

Passo 2: Ativar permissões do workflow

Abra Settings > Actions > General.

Em Workflow permissions:

1. Selecione Read and write permissions.
2. Ative Allow GitHub Actions to create and approve pull requests.
3. Guarde a definição.

Passo 3: Adicionar o Workflow

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

Altere translate -l "es fr de" -y para as línguas-alvo e os flags de conteúdo de que o seu projeto necessita. Para repositórios grandes, adicione um filtro paths: sob on: para que o workflow só seja executado quando a documentação mudar.

Configuração do GitHub App

Utilize esta configuração quando o GITHUB_TOKEN não puder criar commits ou pull requests na sua organização.

Passo 1: Criar ou instalar um GitHub App

Crie um GitHub App com acesso de leitura/escrita a Contents e Pull requests, ou instale a app fornecida pela organização se a sua organização já mantiver uma.

Registe:

• App ID
• Private key contents

Armazene-os como segredos do repositório:

• GH_APP_ID
• GH_APP_PRIVATE_KEY

Passo 2: Gerar um token da App

Use o mesmo workflow da configuração padrão, mas adicione um passo de app-token antes do passo do 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/

Limites dos runners

Os runners hospedados pelo GitHub têm uma duração máxima por trabalho. Repositórios grandes ou muitas línguas-alvo podem exceder esse limite.

Para grandes cargas de tradução:

• Traduza menos línguas por execução.
• Utilize flags de conteúdo como -md, -nb ou -img.
• Utilize um runner self-hosted quando o tamanho do repositório ou a latência do modelo tornar os runners hospedados pouco fiáveis.

Revisão no CI

Utilize co-op-review quando um pull request deve validar traduções geradas sem invocar fornecedores LLM ou Vision.

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

co-op-review é um comando de revisão determinístico em fase beta. As suas verificações e esquema de saída podem evoluir, mas foi concebido para ser seguro para CI porque não escreve ficheiros nem chama fornecedores de modelos.