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

Див. Configuration та Azure AI Setup для деталей локального налаштування.

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

Використовуйте це налаштування для більшості публічних та приватних репозиторіїв.

Крок 1: Додайте секрети репозиторію¶

У цільовому репозиторії відкрийте Налаштування > Секрети та змінні > Дії, потім додайте секрети постачальників, які використовуватиме ваш workflow.

Виберіть секрети Дій

Крок 2: Увімкніть дозволи для робочого процесу¶

Відкрийте Налаштування > Дії > Загальні.

У розділі Дозволи робочого процесу:

Виберіть Read and write permissions.
Увімкніть Allow GitHub Actions to create and approve pull requests.
Збережіть налаштування.

Налаштування дозволів робочого процесу

Крок 3: Додайте робочий процес¶

Створіть .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/

Обмеження для раннерів¶

Хостираннери GitHub мають максимальну тривалість задачі. Великі репозиторії або багато цільових мов можуть перевищувати це обмеження.

Для великих обсягів перекладу:

Перекладайте менше мов за один запуск.
Використовуйте параметри вмісту, такі як -md, -nb або -img.
Використовуйте self-hosted runner, коли розмір репозиторію або затримка моделі робить hosted runners ненадійними.

Перевірка в 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, оскільки не записує файли і не викликає постачальників моделей.