co-op-translator

A Co-op Translator GitHub Action használata (Szervezeti útmutató)

Célközönség: Ez az útmutató Microsoft belső felhasználóknak vagy olyan csapatoknak szól, akik hozzáférnek a Co-op Translator előre elkészített GitHub App hitelesítő adataihoz, vagy saját egyedi GitHub Appot tudnak létrehozni.

Automatizáld a dokumentáció fordítását a Co-op Translator GitHub Action segítségével. Ez az útmutató lépésről lépésre bemutatja, hogyan állítsd be az actiont, hogy automatikusan létrehozzon pull requesteket a frissített fordításokkal, amikor a forrás Markdown fájlok vagy képek módosulnak.

[!IMPORTANT]

A megfelelő útmutató kiválasztása:

Ez az útmutató a GitHub App ID és Private Key használatát mutatja be. Általában ezt a “Szervezeti útmutató” módszert akkor kell választanod, ha: GITHUB_TOKEN jogosultságok korlátozottak: A szervezeted vagy a repository beállításai korlátozzák az alapértelmezett GITHUB_TOKEN által biztosított jogosultságokat. Ha például a GITHUB_TOKEN nem kapja meg a szükséges write jogosultságokat (mint a contents: write vagy pull-requests: write), akkor a Publikus beállítási útmutatóban leírt workflow nem fog működni jogosultság hiánya miatt. Egy dedikált GitHub App használata, amelynek jogosultságai kifejezetten meg vannak adva, megkerüli ezt a korlátozást.

Ha rád nem vonatkozik a fenti korlátozás:

Ha a standard GITHUB_TOKEN elegendő jogosultsággal rendelkezik a repositorydban (tehát nincs szervezeti korlátozás), akkor használd inkább a Publikus beállítási útmutatót GITHUB_TOKEN-nel. A publikus útmutató nem igényel App ID vagy Private Key beszerzését, csak a standard GITHUB_TOKEN-t és a repository jogosultságait használja.

Előfeltételek

Mielőtt beállítanád a GitHub Actiont, győződj meg róla, hogy rendelkezel a szükséges AI szolgáltatás hitelesítő adataival.

1. Szükséges: AI nyelvi modell hitelesítő adatok Legalább egy támogatott nyelvi modellhez szükséged lesz hitelesítő adatokra:

Azure OpenAI: Szükséges Endpoint, API Key, Modell/Deployment nevek, API verzió.
OpenAI: Szükséges API Key, (Opcionális: Org ID, Base URL, Modell ID).
Részletek: Támogatott modellek és szolgáltatások.
Beállítási útmutató: Azure OpenAI beállítása.

2. Opcionális: Computer Vision hitelesítő adatok (képek fordításához)

Csak akkor szükséges, ha képeken lévő szöveget is fordítani szeretnél.
Azure Computer Vision: Szükséges Endpoint és Subscription Key.
Ha nem adod meg, az action csak Markdown módban fut.
Beállítási útmutató: Azure Computer Vision beállítása.

Beállítás és konfiguráció

Kövesd az alábbi lépéseket a Co-op Translator GitHub Action beállításához a repositorydban:

1. lépés: GitHub App hitelesítés telepítése és konfigurálása

A workflow GitHub App hitelesítést használ, hogy biztonságosan tudjon műveleteket végezni a repositorydban (pl. pull requesteket létrehozni). Válassz egy lehetőséget:

A opció: Előre elkészített Co-op Translator GitHub App telepítése (Microsoft belső használatra)

Nyisd meg a Co-op Translator GitHub App oldalát.
Kattints az Install gombra, majd válaszd ki azt a fiókot vagy szervezetet, ahol a cél repository található.
Válaszd az Only select repositories lehetőséget, majd jelöld ki a cél repositoryt (pl. PhiCookBook). Kattints az Install gombra. Előfordulhat, hogy hitelesítened kell magad.
App hitelesítő adatok beszerzése (belső folyamat szükséges): Ahhoz, hogy a workflow az app nevében tudjon hitelesíteni, két információra lesz szükséged, amit a Co-op Translator csapat biztosít:
- App ID: A Co-op Translator app egyedi azonosítója. Az App ID: 1164076.
- Private Key: Meg kell szerezned a .pem privát kulcsfájl teljes tartalmát a karbantartótól. Ezt a kulcsot kezeld jelszóként, és tartsd biztonságban!
Folytasd a 2. lépéssel.

B opció: Saját egyedi GitHub App használata

Ha szeretnéd, létrehozhatsz és konfigurálhatsz saját GitHub Appot is. Biztosítsd, hogy olvasási és írási jogosultsága legyen a Contents és Pull requests-hez. Szükséged lesz az App ID-ra és a generált Private Key-re.

2. lépés: Repository titkos adatok konfigurálása

A GitHub App hitelesítő adatokat és az AI szolgáltatás hitelesítő adatokat titkosított secretsként kell hozzáadnod a repository beállításaihoz.

Nyisd meg a cél GitHub repositoryt (pl. PhiCookBook).
Menj a Settings > Secrets and variables > Actions menüponthoz.
A Repository secrets alatt kattints a New repository secret gombra minden egyes titkos adatnál az alábbiak közül.

Szükséges titkos adatok (GitHub App hitelesítéshez):

Secret Name	Leírás	Forrás
`GH_APP_ID`	A GitHub App azonosítója (1. lépésből).	GitHub App beállítások
`GH_APP_PRIVATE_KEY`	A letöltött `.pem` fájl teljes tartalma	`.pem` fájl (1. lépésből)

AI szolgáltatás titkos adatok (Add meg az összeset, ami releváns):

Secret Name	Leírás	Forrás
`AZURE_AI_SERVICE_API_KEY`	Azure AI Service kulcs (Computer Vision)	Azure AI Foundry
`AZURE_AI_SERVICE_ENDPOINT`	Azure AI Service endpoint (Computer Vision)	Azure AI Foundry
`AZURE_OPENAI_API_KEY`	Azure OpenAI szolgáltatás kulcsa	Azure AI Foundry
`AZURE_OPENAI_ENDPOINT`	Azure OpenAI szolgáltatás endpointja	Azure AI Foundry
`AZURE_OPENAI_MODEL_NAME`	Azure OpenAI modell neve	Azure AI Foundry
`AZURE_OPENAI_CHAT_DEPLOYMENT_NAME`	Azure OpenAI deployment neve	Azure AI Foundry
`AZURE_OPENAI_API_VERSION`	Azure OpenAI API verziója	Azure AI Foundry
`OPENAI_API_KEY`	OpenAI API kulcs	OpenAI Platform
`OPENAI_ORG_ID`	OpenAI szervezet azonosítója	OpenAI Platform
`OPENAI_CHAT_MODEL_ID`	OpenAI modell azonosítója	OpenAI Platform
`OPENAI_BASE_URL`	Egyedi OpenAI API Base URL	OpenAI Platform

Enter environment variable name

3. lépés: Workflow fájl létrehozása

Végül hozd létre a YAML fájlt, amely definiálja az automatizált workflow-t.

A repository gyökérkönyvtárában hozd létre a .github/workflows/ könyvtárat, ha még nem létezik.
A .github/workflows/ mappában hozz létre egy co-op-translator.yml nevű fájlt.
Illeszd be az alábbi tartalmat a co-op-translator.yml fájlba.

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 Credentials
          AZURE_AI_SERVICE_API_KEY: $
          AZURE_AI_SERVICE_ENDPOINT: $

          # Azure OpenAI Credentials
          AZURE_OPENAI_API_KEY: $
          AZURE_OPENAI_ENDPOINT: $
          AZURE_OPENAI_MODEL_NAME: $
          AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: $
          AZURE_OPENAI_API_VERSION: $

          # OpenAI Credentials
          OPENAI_API_KEY: $
          OPENAI_ORG_ID: $
          OPENAI_CHAT_MODEL_ID: $
          OPENAI_BASE_URL: $
        run: |
          # =====================================================================
          # IMPORTANT: Set your target languages here (REQUIRED CONFIGURATION)
          # =====================================================================
          # Example: Translate to Spanish, French, German. Add -y to auto-confirm.
          translate -l "es fr de" -y  # <--- MODIFY THIS LINE with your desired languages

      - name: Authenticate GitHub App
        id: generate_token
        uses: tibdex/github-app-token@v1
        with:
          app_id: $
          private_key: $

      - name: Create Pull Request with translations
        uses: peter-evans/create-pull-request@v5
        with:
          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.

            ### 📋 Changes included
            - Translated contents are available in the `translations/` directory
            - Translated images are available in the `translated_images/` directory

            ---
            🌐 Automatically generated by the [Co-op Translator](https://github.com/Azure/co-op-translator) GitHub Action.
          branch: update-translations
          base: main
          labels: translation, automated-pr
          delete-branch: true
          add-paths: |
            translations/
            translated_images/

Workflow testreszabása:
- [!IMPORTANT] Cél nyelvek: A Run Co-op Translator lépésben FELTÉTLENÜL ellenőrizd és módosítsd a nyelvi kódok listáját a translate -l "..." -y parancsban, hogy megfeleljen a projekted igényeinek. Az itt szereplő példa (ar de es...) csak minta, cseréld le vagy egészítsd ki.
- Trigger (on:): Jelenleg minden main branchre történő push esetén fut le. Nagy repositoryknál érdemes paths: szűrőt beállítani (lásd a YAML-ban a kommentelt példát), hogy csak releváns fájlok (pl. forrás dokumentáció) módosításakor fusson, így spórolhatsz a runner percekkel.
- PR részletek: Szükség esetén testreszabhatod a commit-message, title, body, branch nevét és a labels-t a Create Pull Request lépésben.

Hitelesítő adatok kezelése és megújítása

Biztonság: Az érzékeny hitelesítő adatokat (API kulcsok, privát kulcsok) mindig GitHub Actions titkos adatként tárold. Soha ne tedd ki őket a workflow fájlban vagy a repository kódban.
[!IMPORTANT] Kulcs megújítás (Microsoft belső felhasználók): Az Azure OpenAI kulcsot a Microsofton belül előfordulhat, hogy kötelezően meg kell újítani (pl. 5 havonta). Frissítsd a megfelelő GitHub titkos adatokat (AZURE_OPENAI_... kulcsok) lejárat előtt, hogy elkerüld a workflow hibákat.

A workflow futtatása

[!WARNING]
GitHub-hosted Runner időkorlát:
A GitHub által biztosított futtatók, mint az ubuntu-latest, maximum 6 óráig futtathatók.
Nagy dokumentációs repositoryknál, ha a fordítási folyamat 6 óránál tovább tart, a workflow automatikusan megszakad.
Ennek elkerülésére:

Használj saját futtatót (nincs időkorlát)

Csökkentsd a futtatott nyelvek számát egy-egy futásnál

Ha a co-op-translator.yml fájlt beolvasztod a main branchbe (vagy abba a branchbe, amit a on: triggerben megadtál), a workflow automatikusan lefut, amikor változásokat pusholsz abba a branchbe (és megfelel a paths szűrőnek, ha beállítottad).

Ha új vagy frissített fordítások készülnek, az action automatikusan létrehoz egy Pull Requestet a változtatásokkal, amit át tudsz nézni és be tudsz olvasztani.

Jogi nyilatkozat: Ez a dokumentum az AI fordítási szolgáltatás, a Co-op Translator segítségével készült. Bár törekszünk a pontosságra, kérjük, vegye figyelembe, hogy az automatikus fordítások hibákat vagy pontatlanságokat tartalmazhatnak. Az eredeti dokumentum eredeti nyelvén tekintendő hiteles forrásnak. Kritikus információk esetén javasoljuk a professzionális, emberi fordítást. Nem vállalunk felelősséget a fordítás használatából eredő félreértésekért vagy félreértelmezésekért.

This site is open source. Improve this page.