GitHub Actions¶

Используйте GitHub Actions, когда вы хотите, чтобы репозиторий автоматически переводил изменённую документацию и открывал pull request с сгенерированными результатами.

Большинству репозиториев следует использовать стандартную настройку с GITHUB_TOKEN. Используйте настройку через GitHub App только если ваша организация ограничивает разрешения токена по умолчанию или требует аутентификацию на основе приложения.

Предварительные требования¶

Перед созданием workflow настройте секреты сервисов ИИ, необходимые для запуска перевода.

Для перевода текста требуется один поставщик языковой модели:

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, плюс опционально OPENAI_ORG_ID и OPENAI_BASE_URL

Для перевода изображений дополнительно требуется Azure AI Vision:

AZURE_AI_SERVICE_API_KEY
AZURE_AI_SERVICE_ENDPOINT

См. Конфигурация и Настройка Azure AI для подробной локальной настройки.

Стандартная настройка¶

Используйте эту конфигурацию для большинства публичных и приватных репозиториев.

Шаг 1: Добавьте секреты репозитория¶

В целевом репозитории откройте Settings > Secrets and variables > Actions, затем добавьте секреты провайдера, которые будет использовать ваш workflow.

Выберите секреты Actions

Шаг 2: Включите разрешения рабочего процесса¶

Откройте Settings > Actions > General.

Под Workflow permissions:

Выберите Read and write permissions.
Включите Allow GitHub Actions to create and approve pull requests.
Сохраните настройку.

Настройка разрешений рабочего процесса

Шаг 3: Добавьте workflow¶

Создайте .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/

Измените translate -l "es fr de" -y на целевые языки и флаги содержимого, необходимые вашему проекту. Для больших репозиториев добавьте фильтр paths: в разделе on:, чтобы workflow запускался только при изменениях в документации.

Настройка GitHub App¶

Используйте эту настройку, когда GITHUB_TOKEN не может создавать коммиты или pull request в вашей организации.

Шаг 1: Создайте или установите GitHub App¶

Создайте GitHub App с правами чтения/записи для Contents и Pull requests, или установите предоставляемый организацией апп, если у вашей организации уже есть такой.

Запишите:

ID приложения
Содержимое приватного ключа

Сохраните их как секреты репозитория:

GH_APP_ID
GH_APP_PRIVATE_KEY

Шаг 2: Сгенерируйте токен приложения¶

Используйте тот же workflow, что и в стандартной настройке, но добавьте шаг app-token перед шагом 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/

Ограничения раннеров¶

Запускатели (runners), размещаемые GitHub, имеют максимальную длительность задания. Большие репозитории или большое количество целевых языков могут превысить этот лимит.

Для больших объёмов перевода:

Переводите меньше языков за один запуск.
Используйте флаги содержимого, такие как -md, -nb или -img.
Используйте self-hosted runner, когда размер репозитория или задержки модели делают размещаемые раннеры ненадёжными.

Проверка в CI¶

Используйте co-op-review, когда в pull request нужно проверить сгенерированные переводы без вызова LLM или Vision-провайдеров.

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

co-op-review — это бета-версия детерминированной команды проверки. Её проверки и схема вывода могут изменяться, но она разработана безопасной для CI, потому что не записывает файлы и не вызывает провайдеров моделей.