GitHub Actions¶

Sử dụng GitHub Actions khi bạn muốn một kho lưu trữ tự động dịch các tài liệu đã thay đổi và mở một pull request với các đầu ra được sinh ra.

Hầu hết các kho lưu trữ nên sử dụng thiết lập GITHUB_TOKEN tiêu chuẩn. Chỉ sử dụng thiết lập GitHub App khi tổ chức của bạn hạn chế quyền của token mặc định hoặc yêu cầu xác thực dựa trên app.

Prerequisites¶

Trước khi tạo workflow, cấu hình các bí mật dịch vụ AI mà lần chạy dịch của bạn cần.

Dịch văn bản yêu cầu một nhà cung cấp mô hình ngôn ngữ:

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

Dịch hình ảnh ngoài ra còn yêu cầu Azure AI Vision:

AZURE_AI_SERVICE_API_KEY
AZURE_AI_SERVICE_ENDPOINT

Xem Cấu hình và Thiết lập Azure AI để biết chi tiết cấu hình cục bộ.

Standard Setup¶

Sử dụng cấu hình này cho hầu hết các kho lưu trữ công khai và riêng tư.

Step 1: Add Repository Secrets¶

Trong kho lưu trữ đích của bạn, mở Cài đặt > Bí mật và biến > Actions, sau đó thêm các bí mật của nhà cung cấp mà workflow của bạn sẽ sử dụng.

Chọn bí mật Actions

Step 2: Enable Workflow Permissions¶

Mở Cài đặt > Actions > Chung.

Trong Quyền workflow:

Chọn Quyền đọc và ghi.
Bật Cho phép GitHub Actions tạo và phê duyệt pull request.
Lưu cài đặt.

Cài đặt quyền workflow

Step 3: Add the Workflow¶

Tạo .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/

Thay translate -l "es fr de" -y bằng các ngôn ngữ đích và cờ nội dung mà dự án của bạn cần. Đối với các kho lưu trữ lớn, thêm một bộ lọc paths: dưới on: để workflow chỉ chạy khi tài liệu thay đổi.

GitHub App Setup¶

Sử dụng thiết lập này khi GITHUB_TOKEN không thể tạo commit hoặc pull request trong tổ chức của bạn.

Step 1: Create or Install a GitHub App¶

Tạo một GitHub App với quyền đọc/ghi tới Nội dung và Pull requests, hoặc cài đặt app do tổ chức cung cấp nếu tổ chức của bạn đã duy trì một app.

Ghi lại:

App ID
Nội dung khóa riêng tư

Lưu chúng làm bí mật trong kho lưu trữ:

GH_APP_ID
GH_APP_PRIVATE_KEY

Step 2: Generate an App Token¶

Sử dụng cùng workflow như cấu hình tiêu chuẩn, nhưng thêm một bước app-token trước bước 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¶

Các runner do GitHub lưu trữ có thời lượng công việc tối đa. Các kho lưu trữ lớn hoặc nhiều ngôn ngữ đích có thể vượt quá giới hạn đó.

Đối với khối lượng công việc dịch lớn:

Dịch ít ngôn ngữ hơn cho mỗi lần chạy.
Sử dụng các cờ nội dung như -md, -nb, hoặc -img.
Sử dụng một runner tự lưu trữ khi kích thước kho lưu trữ hoặc độ trễ mô hình khiến các runner được lưu trữ trở nên không đáng tin cậy.

Review in CI¶

Sử dụng co-op-review khi một pull request cần xác thực các bản dịch đã sinh mà không gọi tới các nhà cung cấp LLM hoặc Vision.

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

co-op-review là một lệnh rà soát beta có tính xác định. Các kiểm tra và lược đồ đầu ra của nó có thể thay đổi, nhưng nó được thiết kế an toàn cho CI vì nó không ghi tệp hoặc gọi tới các nhà cung cấp mô hình.