GitHub Actions¶

Gunakan GitHub Actions apabila anda mahu repositori menterjemah dokumentasi yang telah diubah secara automatik dan membuka permintaan tarik dengan keluaran yang dihasilkan.

Kebanyakan repositori harus menggunakan tetapan GITHUB_TOKEN standard. Gunakan persediaan GitHub App hanya apabila organisasi anda mengehadkan kebenaran token lalai atau memerlukan pengesahan berasaskan aplikasi.

Prerequisites¶

Sebelum membuat aliran kerja, konfigurasikan rahsia perkhidmatan AI yang diperlukan oleh larian terjemahan anda.

Terjemahan teks memerlukan satu penyedia model bahasa:

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

Terjemahan imej juga memerlukan Azure AI Vision:

AZURE_AI_SERVICE_API_KEY
AZURE_AI_SERVICE_ENDPOINT

Lihat Konfigurasi dan Persediaan Azure AI untuk butiran konfigurasi tempatan.

Standard Setup¶

Gunakan persediaan ini untuk kebanyakan repositori awam dan persendirian.

Step 1: Add Repository Secrets¶

Dalam repositori sasaran anda, buka Settings > Secrets and variables > Actions, kemudian tambahkan rahsia penyedia yang akan digunakan oleh aliran kerja anda.

Pilih rahsia Actions

Step 2: Enable Workflow Permissions¶

Buka Settings > Actions > General.

Di bawah Workflow permissions:

Select Read and write permissions.
Enable Allow GitHub Actions to create and approve pull requests.
Save the setting.

Tetapan kebenaran aliran kerja

Step 3: Add the Workflow¶

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

Tukar translate -l "es fr de" -y kepada bahasa sasaran dan bendera kandungan yang diperlukan oleh projek anda. Untuk repositori besar, tambahkan penapis paths: di bawah on: supaya aliran kerja hanya berjalan apabila dokumentasi berubah.

GitHub App Setup¶

Gunakan persediaan ini apabila GITHUB_TOKEN tidak boleh membuat komit atau permintaan tarik dalam organisasi anda.

Step 1: Create or Install a GitHub App¶

Cipta Aplikasi GitHub dengan akses baca/tulis ke Contents dan Pull requests, atau pasang aplikasi yang disediakan oleh organisasi jika organisasi anda sudah menyelenggarakannya.

Catatkan:

App ID
Private key contents

Simpan mereka sebagai rahsia repositori:

GH_APP_ID
GH_APP_PRIVATE_KEY

Step 2: Generate an App Token¶

Gunakan aliran kerja yang sama seperti persediaan standard, tetapi tambah langkah app-token sebelum langkah permintaan tarik:

      - 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¶

Runner yang dihos oleh GitHub mempunyai tempoh tugas maksimum. Repositori besar atau banyak bahasa sasaran boleh melebihi had tersebut.

Untuk beban kerja terjemahan yang besar:

Terjemah lebih sedikit bahasa setiap larian.
Gunakan bendera kandungan seperti -md, -nb, atau -img.
Gunakan runner hos sendiri apabila saiz repositori atau kelewatan model menjadikan runner yang dihos tidak boleh dipercayai.

Review in CI¶

Gunakan co-op-review apabila permintaan tarik perlu mengesahkan terjemahan yang dihasilkan tanpa memanggil penyedia LLM atau Vision.

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

co-op-review adalah arahan semakan deterministik beta. Pemeriksaannya dan skema output mungkin berubah, tetapi ia direka untuk selamat digunakan dalam CI kerana ia tidak menulis fail atau memanggil penyedia model.