GitHub Actions¶

Използвайте GitHub Actions, когато искате дадено хранилище да превежда автоматично променената документация и да отвори pull request с генерираните резултати.

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

Prerequisites¶

Преди да създадете workflow, конфигурирайте секретите за AI услугите, от които се нуждае вашето преводно изпълнение.

Text translation requires one language model provider:

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

Image translation additionally requires Azure AI Vision:

AZURE_AI_SERVICE_API_KEY
AZURE_AI_SERVICE_ENDPOINT

Вижте Конфигурация и Настройка на Azure AI за подробности относно локалната конфигурация.

Standard Setup¶

Използвайте тази настройка за повечето публични и частни хранилища.

Step 1: Add Repository Secrets¶

В целевото ви хранилище отворете Настройки > Secrets and variables > Actions, след това добавете секретите на доставчика, които вашият workflow ще използва.

Изберете секретите за Actions

Step 2: Enable Workflow Permissions¶

Отворете Настройки > Actions > Общи.

Под Разрешения за работния процес:

Изберете Read and write permissions.
Активирайте Allow GitHub Actions to create and approve pull requests.
Запазете настройката.

Настройка на разрешенията за workflow

Step 3: Add the 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/

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

GitHub App Setup¶

Използвайте тази настройка когато GITHUB_TOKEN не може да създава комити или pull request-и във вашата организация.

Step 1: Create or Install a GitHub App¶

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

Запишете:

App ID
Private key contents

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

GH_APP_ID
GH_APP_PRIVATE_KEY

Step 2: Generate an App Token¶

Използвайте същия 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/

Runner Limits¶

GitHub-hosted runners имат максимална продължителност на задача. Големи хранилища или много целеви езици могат да превишат това ограничение.

За големи преводни натоварвания:

Превеждайте по-малко езици на изпълнение.
Използвайте флагове за съдържание като -md, -nb или -img.
Използвайте self-hosted runner, когато размерът на репозитория или латентността на модела правят hosted runner-ите ненадеждни.

Review in 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, тъй като не записва файлове и не извиква доставчици на модели.