GitHub Actions¶

Gunakan GitHub Actions apabila anda mahu repositori menterjemah dokumen yang diubah secara automatik dan membuka pull request dengan keluaran yang dijana.

Mulakan dengan tetapan standard GITHUB_TOKEN, termasuk untuk repositori organisasi di mana polisi membenarkannya. Lihat Tetapan Aplikasi GitHub apabila organisasi anda memerlukan identiti Aplikasi atau anda memerlukan larian aliran kerja hiliran automatik.

Penyuntingan manusia: aliran kerja ini menterjemah semula fail sumber yang diubah sepenuhnya dan boleh menulis ganti kata-kata yang disunting dalam terjemahan mereka. Semak setiap PR sebelum menggabungkan. Pemeliharaan pada aras blok Markdown bagi suntingan yang diterima memerlukan integrasi tersuai dengan penyedia status terjemahan API Python.

PR terjemahan README pertama anda¶

Mula dengan satu fail akar README.md dan satu bahasa sasaran. Aliran kerja ini menterjemah Markdown sahaja, jadi Azure AI Vision tidak diperlukan.

Salin translate-readme.yml (lihat templat di GitHub) ke .github/workflows/translate-readme.yml dalam repositori yang anda mahu terjemahkan, dan komitkan ke cawangan lalai repositori itu. Templat menggunakan root Action dalam Azure/co-op-translator@main, yang memasang CLI dari rujukan sumber yang sama. Kuncikan (pin) commit yang telah disemak untuk larian yang boleh diulang.
Buka Actions > Translate README > Run workflow, pilih satu bahasa, dan biarkan Preview only ditanda. Semak anggaran token dalam langkah pratonton. Pratonton tidak memanggil penyedia model, menulis terjemahan, atau membuat PR.
Tambah rahsia untuk satu penyedia teks, dan dayakan Benarkan GitHub Actions untuk membuat dan meluluskan permintaan tarik di bawah Settings > Actions > General. Templat meminta contents: write dan pull-requests: write untuk tugasnya; anda tidak perlu menukar kebenaran lalai untuk setiap aliran kerja. Jika polisi organisasi menyekat kebenaran atau tetapan ini, minta pentadbir tentang Aplikasi GitHub yang diluluskan.
Jalankan aliran kerja sekali lagi dengan Preview only tidak ditanda. Ia membuat pratonton, menterjemah, menjalankan co-op-review --readme-only, dan hanya membuat atau mengemas kini PR terjemahan selepas terjemahan dan semakan berjaya. Ringkasan aliran kerja menyediakan pautan ke PR.
Semak pernyataan dan perubahan fail dalam PR, kemudian gabungkan apabila bersedia. Aliran kerja tidak menggabungkan secara automatik.

PR tersebut hanya mengandungi translations/<language>/README.md dan fail metadata bahasa. README sumber kekal tidak berubah, dan pautan ke dokumen lain terus menunjuk kepada dokumen sumber. Badan PR menyenaraikan fail yang diubah dan hasil semakan struktur. Jika terjemahan atau semakan gagal, periksa ringkasan aliran kerja dan log langkah yang gagal; tiada PR akan dibuat. Jika tiada perubahan, tiada PR baru diperlukan.

Nota organisasi dan CI: Aplikasi GitHub adalah pilihan, bukan syarat pemilikan organisasi. Dengan GITHUB_TOKEN, aliran kerja pull-request untuk membuka, mengemas kini, atau membuka semula PR memerlukan pengguna dengan akses tulis untuk memilih Approve workflows to run. Aliran kerja push tidak dicetuskan oleh token ini. Untuk CI hiliran tanpa pengawasan, lihat Tetapan Aplikasi GitHub dan peraturan pencetus aliran kerja GitHub.

Prasyarat¶

Sebelum membuat aliran kerja, konfigurasikan rahsia perkhidmatan AI yang diperlukan untuk 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
Anthropic: ANTHROPIC_API_KEY, ANTHROPIC_MODEL, plus optional ANTHROPIC_BASE_URL

Terjemahan imej juga memerlukan Azure AI Vision:

AZURE_AI_SERVICE_API_KEY
AZURE_AI_SERVICE_ENDPOINT

Lihat Konfigurasi dan Tetapan Azure AI untuk butiran konfigurasi setempat.

Tetapan Standard¶

Selepas mencuba aliran kerja README, gunakan tetapan ini untuk menterjemah fail Markdown repositori ke beberapa bahasa. Ia menjalankan semakan Markdown sebelum membuka PR dan tidak memerlukan Azure AI Vision.

Langkah 1: Tambah Rahsia Repositori¶

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

Pilih rahsia Actions

Langkah 2: Dayakan Kebenaran Aliran Kerja¶

Buka Settings > Actions > General.

Di bawah Workflow permissions:

Dayakan Benarkan GitHub Actions untuk membuat dan meluluskan permintaan tarik.
Simpan tetapan tersebut.

Tugas di bawah meminta contents: write dan pull-requests: write secara jelas. Kekalkan kebenaran lalai aliran kerja repositori tanpa perubahan. Jika polisi organisasi menyekat penciptaan PR, tanya pentadbir tentang Aplikasi GitHub yang diluluskan.

Langkah 3: Tambah Aliran Kerja¶

Buat .github/workflows/co-op-translator.yml:

name: Co-op Translator

on:
  push:
    branches:
      - main

jobs:
  co-op-translator:
    runs-on: ubuntu-latest
    env:
      TARGET_LANGUAGES: "es fr de"

    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@v7
        with:
          python-version: "3.11"

      - 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_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 }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          ANTHROPIC_MODEL: ${{ secrets.ANTHROPIC_MODEL }}
          ANTHROPIC_BASE_URL: ${{ secrets.ANTHROPIC_BASE_URL }}
        run: |
          translate -l "$TARGET_LANGUAGES" -md -y

      - name: Review Markdown translations
        run: |
          python - <<'PY'
          import os
          from co_op_translator.api import run_review

          run_review(
              language_codes=os.environ["TARGET_LANGUAGES"].split(),
              markdown=True,
              notebook=False,
              output_format="github",
          )
          PY

      - 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.
            Markdown structure, freshness, and local links were reviewed.
            Review translation wording before merging.

            Generated by Co-op Translator.
          branch: update-translations
          base: main
          labels: translation, automated-pr
          delete-branch: true
          add-paths: |
            translations/

Tukar TARGET_LANGUAGES kepada bahasa yang projek anda perlukan. Semakan menggunakan API Python untuk memeriksa hanya Markdown, selaras dengan langkah terjemahan. Ralat terjemahan atau semakan menghentikan tugas sebelum penciptaan PR. Aliran kerja tidak menggabungkan PR secara automatik. Untuk repositori besar, tambah penapis paths: di bawah on.push supaya aliran kerja hanya dijalankan apabila dokumentasi berubah.

Pilihan: notebook dan imej¶

Untuk notebook, tambah -nb kepada arahan terjemahan dan tetapkan notebook=True dalam langkah semakan. Untuk teks imej, konfigurasikan dua rahsia Azure AI Vision, sampaikan ia dalam env langkah terjemahan, tambah -img kepada arahan, dan tambah translated_images/ ke add-paths langkah PR. Semak imej yang diterjemah secara visual; semakan deterministik tidak mengesahkan teks imej atau ketepatan linguistik.

Tetapan Aplikasi GitHub¶

Gunakan Aplikasi GitHub yang diluluskan apabila organisasi anda memerlukan identiti Aplikasi, atau apabila PR yang dijana perlu mencetus CI hiliran tanpa langkah kelulusan GITHUB_TOKEN. Aplikasi tidak memintas polisi organisasi; pentadbir masih mengawal pemasangan dan kebenarannya.

Langkah 1: Cipta atau Pasang Aplikasi GitHub¶

Gunakan Aplikasi yang disediakan organisasi jika ada, atau cipta satu dengan akses baca/tulis kepada Contents dan Pull requests. Pasangkannya pada repositori sasaran dengan sebarang kelulusan organisasi yang diperlukan.

Rekod:

ID Aplikasi
Kandungan kunci peribadi

Simpannya sebagai rahsia repositori:

GH_APP_ID
GH_APP_PRIVATE_KEY

Langkah 2: Jana Token Aplikasi¶

Tambah langkah ini segera sebelum langkah pull request sedia ada. Untuk templat README, gunakan syarat kejayaan yang sama supaya pratonton dan terjemahan yang gagal tidak meminta token Aplikasi:

      - name: Authenticate GitHub App
        id: generate_token
        if: ${{ !inputs.preview && steps.translate.outcome == 'success' && steps.review.outcome == 'success' }}
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ secrets.GH_APP_ID }}
          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
          permission-contents: write
          permission-pull-requests: write

Kemudian tukar hanya input token langkah pull request sedia ada kepada ${{ steps.generate_token.outputs.token }}. Kekalkan syarat kejayaannya, cawangan, badan PR, dan add-paths tanpa perubahan. Token tersebut biasanya berjurus kepada repositori semasa secara lalai. Apabila menyesuaikan tetapan standard selain daripada templat README, abaikan if di atas: aliran kerja itu menggunakan syarat kejayaan lalai, jadi penciptaan token dan penciptaan PR hanya berjalan selepas terjemahan dan semakan berjaya.

Lihat Action create-github-app-token rasmi untuk pemasangan dan kebenaran token.

Had Runner¶

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

Untuk beban kerja terjemahan yang besar:

Terjemahkan lebih sedikit bahasa setiap larian.
Gunakan penanda kandungan seperti -md, -nb, atau -img.
Gunakan runner yang dihos sendiri apabila saiz repositori atau latensi model menjadikan runner dihos tidak boleh dipercayai.

Semakan dalam CI¶

Gunakan co-op-review apabila satu pull request perlu mengesahkan terjemahan yang dijana 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 semakan deterministik beta. Semakannya dan skema keluaran mungkin berubah, tetapi ia direka untuk selamat bagi CI kerana ia tidak menulis fail atau memanggil penyedia model.