GitHub Actions

Use GitHub Actions when you want a repository to translate changed documentation automatically and open a pull request with the generated outputs.

Most repositories should use the standard GITHUB_TOKEN setup. Use the GitHub App setup only when your organization restricts the default token permissions or requires app-based authentication.

Požadavky

Před vytvořením workflow nakonfigurujte tajné hodnoty (secrets) AI služby, které váš běh překladu potřebuje.

Překlad textu vyžaduje jednoho poskytovatele jazykového modelu:

• 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

Překlad obrázků navíc vyžaduje Azure AI Vision:

• AZURE_AI_SERVICE_API_KEY
• AZURE_AI_SERVICE_ENDPOINT

See Konfigurace and Nastavení Azure AI for local configuration details.

Standardní nastavení

Toto nastavení použijte pro většinu veřejných i soukromých repozitářů.

Krok 1: Přidejte tajné hodnoty repozitáře

V cílovém repozitáři otevřete Settings > Secrets and variables > Actions, potom přidejte tajné hodnoty poskytovatele, které bude váš workflow používat.

Krok 2: Povolit oprávnění workflow

Otevřete Settings > Actions > General.

V sekci Workflow permissions:

1. Vyberte Read and write permissions.
2. Povolit Allow GitHub Actions to create and approve pull requests.
3. Uložte nastavení.

Krok 3: Přidejte workflow

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

Změňte translate -l "es fr de" -y na cílové jazyky a přepínače obsahu, které váš projekt potřebuje. U velkých repozitářů přidejte filtr paths: pod on:, aby workflow běžel pouze při změnách dokumentace.

GitHub App Setup

Použijte toto nastavení, když GITHUB_TOKEN nemůže ve vaší organizaci vytvářet commity nebo pull requesty.

Krok 1: Vytvořte nebo nainstalujte GitHub App

Vytvořte GitHub App s oprávněním pro čtení/zápis do Contents a Pull requests, nebo nainstalujte aplikaci poskytovanou organizací, pokud ji vaše organizace již spravuje.

Poznamenejte si:

• App ID
• Obsah soukromého klíče

Uložte je jako tajné hodnoty repozitáře:

• GH_APP_ID
• GH_APP_PRIVATE_KEY

Krok 2: Vygenerujte token aplikace

Použijte stejný workflow jako ve standardním nastavení, ale přidejte krok s app-tokenem před krokem pro 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/

Omezení runnerů

Na GitHubu hostovaní runneři mají maximální dobu trvání úlohy. Velké repozitáře nebo mnoho cílových jazyků může tento limit překročit.

Pro rozsáhlé překladové úlohy:

• Překládejte méně jazyků na jeden běh.
• Používejte přepínače obsahu, jako -md, -nb nebo -img.
• Použijte self-hosted runner, pokud velikost repozitáře nebo latence modelu činí hostované runnery nespolehlivými.

Kontrola v CI

Použijte co-op-review, když by pull request měl ověřit vygenerované překlady, aniž by volal poskytovatele LLM nebo Vision.

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

co-op-review je beta deterministický kontrolní příkaz. Jeho kontroly a výstupní schéma se mohou vyvíjet, ale je navržen tak, aby byl bezpečný pro CI, protože nezapisuje soubory ani nevolá poskytovatele modelů.