GitHub Actions

Käytä GitHub Actionsia, kun haluat, että repositorio kääntää muutetun dokumentaation automaattisesti ja avaa vetopyynnön luotujen tulosten kanssa.

Useimmat repositoriot voivat käyttää vakiomääritystä GITHUB_TOKEN-tokenilla. Käytä GitHub-sovelluksen asetusta vain, kun organisaatiosi rajoittaa oletustokenin käyttöoikeuksia tai edellyttää sovelluspohjaista todennusta.

Esivaatimukset

Ennen työnkulun luomista, määritä ne AI-palvelun salaisuudet, joita käännösajo tarvitsee.

Tekstikäännös vaatii yhden kielimallitoimittajan:

• 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

Kuvakäännös vaatii lisäksi Azure AI Visionin:

• AZURE_AI_SERVICE_API_KEY
• AZURE_AI_SERVICE_ENDPOINT

Lisätietoja paikallisesta konfiguroinnista: katso Konfigurointi ja Azure AI -asennus.

Vakioasetukset

Käytä tätä asetusta useimmissa julkisissa ja yksityisissä repositorioissa.

Vaihe 1: Lisää repositorion salaisuudet

Kohderepositoriossasi avaa Asetukset > Salaisuudet ja muuttujat > Toiminnot, ja lisää sitten ne palveluntarjoajan salaisuudet, joita työnkulku käyttää.

Vaihe 2: Ota työnkulun käyttöoikeudet käyttöön

Avaa Asetukset > Toiminnot > Yleiset.

Kohdassa Työnkulun käyttöoikeudet:

1. Valitse Luku- ja kirjoitusoikeudet.
2. Ota käyttöön Salli GitHub Actionsin luoda ja hyväksyä vetopyyntöjä.
3. Tallenna asetus.

Vaihe 3: Lisää työnkulku

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

Vaihda translate -l "es fr de" -y projektisi tarvitsemiksi kohdekieliksi ja sisältölipuiksi. Suurille repositorioille lisää paths:-suodatin on:-kohdan alle, jotta työnkulku suoritetaan vain, kun dokumentaatio muuttuu.

GitHub-sovelluksen asetukset

Käytä tätä asetusta, kun GITHUB_TOKEN ei voi luoda committeja tai vetopyyntöjä organisaatiossasi.

Vaihe 1: Luo tai asenna GitHub-sovellus

Luo GitHub-sovellus, jolla on luku- ja kirjoitusoikeudet kohteisiin Contents ja Pull requests, tai asenna organisaation tarjoama sovellus, jos organisaatiosi jo ylläpitää sellaista.

Kirjaa muistiin:

• App ID
• Yksityisen avaimen sisältö

Tallenna ne repositorion salaisuuksina:

• GH_APP_ID
• GH_APP_PRIVATE_KEY

Vaihe 2: Luo sovellustunnus

Käytä samaa työnkulkua kuin vakioasetuksessa, mutta lisää app-token-vaihe ennen vetopyyntövaihetta:

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

GitHubin ylläpitämillä runnereilla on enimmäistyöaikarajoitus. Suuret repositoriot tai monet kohdekielet voivat ylittää tämän rajan.

Suurille käännöstyömäärille:

• Käännä vähemmän kieliä yhtä ajoa kohden.
• Käytä sisältölippuja, kuten -md, -nb tai -img.
• Käytä itseisännöityä runneria, kun repositorion koko tai mallin latenssi tekee ylläpidetyistä runnereista epäluotettavia.

Tarkastus CI:ssä

Käytä co-op-review-komentoa, kun vetopyynnön tulee validoida luodut käännökset kutsumatta LLM- tai Vision-palveluntarjoajia.

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

co-op-review on beta-asteinen deterministinen tarkastuskomento. Sen tarkistukset ja ulostuloskeema voivat kehittyä, mutta se on suunniteltu CI:lle turvalliseksi, koska se ei kirjoita tiedostoja eikä kutsu mallipalveluntarjoajia.