GitHub Actions

Gamitin ang GitHub Actions kapag gusto mong awtomatikong isalin ng isang repository ang binagong dokumentasyon at magbukas ng pull request kasama ang mga nabuo na output.

Karamihan sa mga repository ay dapat gumamit ng karaniwang setup na GITHUB_TOKEN. Gamitin ang GitHub App setup lamang kapag nililimitahan ng iyong organisasyon ang default na mga permiso ng token o nangangailangan ng authentication na batay sa app.

Mga Kinakailangan

Bago gumawa ng workflow, i-configure ang mga AI service secret na kailangan ng iyong translation run.

Ang pagsasalin ng teksto ay nangangailangan ng isang provider ng language model:

• 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

Ang pagsasalin ng mga imahe ay nangangailangan din ng Azure AI Vision:

• AZURE_AI_SERVICE_API_KEY
• AZURE_AI_SERVICE_ENDPOINT

Tingnan ang Konfigurasyon at Pag-setup ng Azure AI para sa mga detalye ng lokal na konfigurasyon.

Karaniwang Pag-setup

Gamitin ang setup na ito para sa karamihan ng pampubliko at pribadong mga repositoryo.

Hakbang 1: Magdagdag ng Mga Sekreto ng Repositoryo

Sa target na repositoryo, buksan ang Mga Setting > Mga Sekreto at variable > Actions, pagkatapos idagdag ang mga provider secret na gagamitin ng iyong workflow.

Hakbang 2: Paganahin ang Mga Pahintulot ng Workflow

Buksan ang Mga Setting > Actions > Pangkalahatan.

Sa ilalim ng Mga Pahintulot ng Workflow:

1. Piliin ang Read and write permissions.
2. Paganahin ang Allow GitHub Actions to create and approve pull requests.
3. I-save ang setting.

Hakbang 3: Idagdag ang Workflow

Gumawa ng .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/

Palitan ang translate -l "es fr de" -y ng mga target na wika at content flags na kailangan ng iyong proyekto. Para sa malalaking repositoryo, magdagdag ng paths: filter sa ilalim ng on: upang tumakbo ang workflow lamang kapag may nagbago sa dokumentasyon.

Pag-setup ng GitHub App

Gamitin ang setup na ito kapag hindi makakalikha ng commits o pull requests ang GITHUB_TOKEN sa iyong organisasyon.

Hakbang 1: Gumawa o Mag-install ng GitHub App

Gumawa ng GitHub App na may read/write access sa Contents at Pull requests, o i-install ang app na ibinigay ng organisasyon kung mayroon na ang iyong organisasyon.

Itala:

• App ID
• Private key contents

Itago ang mga ito bilang mga sekreto ng repositoryo:

• GH_APP_ID
• GH_APP_PRIVATE_KEY

Hakbang 2: Gumawa ng App Token

Gamitin ang parehong workflow tulad ng sa karaniwang pag-setup, ngunit idagdag ang isang app-token na hakbang bago ang hakbang ng 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/

Mga Limitasyon ng Runner

Mayroong maximum na haba ng job ang mga GitHub-hosted runner. Ang malalaking repositoryo o maraming target na wika ay maaaring lumampas sa limit na iyon.

Para sa malalaking gawain ng pagsasalin:

• Isalin ang mas kaunting wika kada run.
• Gumamit ng content flags tulad ng -md, -nb, o -img.
• Gumamit ng self-hosted runner kapag ang laki ng repositoryo o latency ng model ay ginagawa ang hosted runners na hindi maaasahan.

Pagsusuri sa CI

Gamitin ang co-op-review kapag ang isang pull request ay dapat mag-validate ng mga nabuo na pagsasalin nang hindi tumatawag sa mga LLM o Vision provider.

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

co-op-review ay isang beta deterministic review command. Ang mga pagsusuri at output schema nito ay maaaring magbago, ngunit idinisenyo ito upang maging ligtas para sa CI dahil hindi ito sumusulat ng mga file o tumatawag sa mga model provider.