GitHub Actions

Gunakan GitHub Actions ketika Anda ingin sebuah repositori menerjemahkan dokumentasi yang diubah secara otomatis dan membuka pull request dengan keluaran yang dihasilkan.

Sebagian besar repositori sebaiknya menggunakan pengaturan standar GITHUB_TOKEN. Gunakan pengaturan GitHub App hanya jika organisasi Anda membatasi izin token default atau memerlukan autentikasi berbasis aplikasi.

Prasyarat

Sebelum membuat workflow, konfigurasikan secret layanan AI yang diperlukan oleh proses 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 gambar juga memerlukan Azure AI Vision:

• AZURE_AI_SERVICE_API_KEY
• AZURE_AI_SERVICE_ENDPOINT

Lihat Konfigurasi dan Penyiapan Azure AI untuk rincian konfigurasi lokal.

Pengaturan Standar

Gunakan pengaturan ini untuk sebagian besar repositori publik dan pribadi.

Langkah 1: Tambahkan Secret Repositori

Di repositori target Anda, buka Settings > Secrets and variables > Actions, lalu tambahkan secret penyedia yang akan digunakan workflow Anda.

Langkah 2: Aktifkan Izin Workflow

Buka Settings > Actions > General.

Di bawah Workflow permissions:

1. Pilih Read and write permissions.
2. Aktifkan Allow GitHub Actions to create and approve pull requests.
3. Simpan pengaturan.

Langkah 3: Tambahkan 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/

Ubah translate -l "es fr de" -y ke bahasa target dan flag konten yang dibutuhkan proyek Anda. Untuk repositori besar, tambahkan filter paths: di bawah on: agar workflow hanya berjalan saat dokumentasi berubah.

Pengaturan GitHub App

Gunakan pengaturan ini ketika GITHUB_TOKEN tidak dapat membuat commit atau pull request dalam organisasi Anda.

Langkah 1: Buat atau Pasang GitHub App

Buat sebuah GitHub App dengan akses baca/tulis ke Contents dan Pull requests, atau pasang aplikasi yang disediakan organisasi jika organisasi Anda sudah memilikinya.

Catat:

• App ID
• Private key contents

Simpan sebagai secret repositori:

• GH_APP_ID
• GH_APP_PRIVATE_KEY

Langkah 2: Hasilkan Token Aplikasi

Gunakan workflow yang sama seperti pengaturan standar, tetapi tambahkan langkah app-token sebelum langkah 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/

Batasan Runner

Runner yang di-host oleh GitHub memiliki durasi pekerjaan maksimum. Repositori besar atau banyak bahasa target dapat melebihi batas tersebut.

Untuk beban kerja terjemahan yang besar:

• Terjemahkan lebih sedikit bahasa setiap kali dijalankan.
• Gunakan flag konten seperti -md, -nb, atau -img.
• Gunakan runner self-hosted ketika ukuran repositori atau latensi model membuat runner yang di-host menjadi tidak andal.

Review di CI

Gunakan co-op-review ketika sebuah pull request harus memvalidasi 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 perintah review deterministik versi beta. Pemeriksaan dan skema outputnya mungkin akan berkembang, tetapi perintah ini dirancang aman untuk CI karena tidak menulis file atau memanggil penyedia model.