co-op-translator

Bruke Co-op Translator GitHub Action (Organisasjonsveiledning)

Målgruppe: Denne veiledningen er for interne Microsoft-brukere eller team som har tilgang til nødvendige legitimasjoner for den forhåndsbygde Co-op Translator GitHub-appen eller kan opprette sin egen tilpassede GitHub-app.

Automatiser oversettelsen av dokumentasjonen i ditt repository enkelt med Co-op Translator GitHub Action. Denne veiledningen viser deg hvordan du setter opp actionen slik at den automatisk oppretter pull requests med oppdaterte oversettelser hver gang kilde-Markdown-filer eller bilder endres.

[!IMPORTANT]

Velg riktig veiledning:

Denne veiledningen beskriver oppsett med GitHub App ID og en privat nøkkel. Du trenger vanligvis denne “Organisasjonsveiledningen” hvis: GITHUB_TOKEN-tillatelsene er begrenset: Organisasjonen eller repository-innstillingene dine begrenser standardtillatelsene som gis til GITHUB_TOKEN. Spesielt hvis GITHUB_TOKEN ikke har nødvendige write-tillatelser (som contents: write eller pull-requests: write), vil workflowen i Offentlig oppsettveiledning feile på grunn av manglende tillatelser. Ved å bruke en dedikert GitHub-app med eksplisitte tillatelser unngår du denne begrensningen.

Hvis dette ikke gjelder deg:

Hvis standard GITHUB_TOKEN har tilstrekkelige tillatelser i ditt repository (dvs. du ikke er blokkert av organisasjonsbegrensninger), bruk Offentlig oppsettveiledning med GITHUB_TOKEN. Den offentlige veiledningen krever ikke at du skaffer eller håndterer App ID-er eller private nøkler, og bruker kun standard GITHUB_TOKEN og repository-tillatelser.

Forutsetninger

Før du konfigurerer GitHub Action, må du sørge for at du har nødvendige AI-tjenestelegitimasjoner klare.

1. Påkrevd: AI Language Model-legitimasjon Du trenger legitimasjon for minst én støttet språkmodell:

Azure OpenAI: Krever Endpoint, API-nøkkel, modell-/deploymentsnavn, API-versjon.
OpenAI: Krever API-nøkkel, (valgfritt: Org ID, Base URL, Modell-ID).
Se Støttede modeller og tjenester for detaljer.
Oppsettveiledning: Sett opp Azure OpenAI.

2. Valgfritt: Computer Vision-legitimasjon (for bildeoversettelse)

Kun nødvendig hvis du skal oversette tekst i bilder.
Azure Computer Vision: Krever Endpoint og Subscription Key.
Hvis ikke oppgitt, kjører actionen i kun Markdown-modus.
Oppsettveiledning: Sett opp Azure Computer Vision.

Oppsett og konfigurasjon

Følg disse stegene for å konfigurere Co-op Translator GitHub Action i ditt repository:

Steg 1: Installer og konfigurer GitHub App-autentisering

Workflowen bruker GitHub App-autentisering for å samhandle sikkert med repositoryet ditt (f.eks. opprette pull requests) på dine vegne. Velg ett alternativ:

Alternativ A: Installer forhåndsbygd Co-op Translator GitHub App (for intern Microsoft-bruk)

Gå til Co-op Translator GitHub App-siden.
Velg Install og velg kontoen eller organisasjonen der repositoryet ditt ligger.
Velg Only select repositories og velg repositoryet ditt (f.eks. PhiCookBook). Klikk Install. Du kan bli bedt om å autentisere.
Skaff app-legitimasjon (intern prosess kreves): For at workflowen skal kunne autentisere som appen, trenger du to opplysninger fra Co-op Translator-teamet:
- App ID: Den unike identifikatoren for Co-op Translator-appen. App ID er: 1164076.
- Privat nøkkel: Du må skaffe hele innholdet i .pem-filen med privat nøkkel fra kontaktpersonen for vedlikehold. Behandle denne nøkkelen som et passord og hold den sikker.
Gå videre til Steg 2.

Alternativ B: Bruk din egen tilpassede GitHub App

Hvis du ønsker det, kan du opprette og konfigurere din egen GitHub App. Sørg for at den har lese- og skrivetilgang til Contents og Pull requests. Du trenger App ID og en generert privat nøkkel.

Steg 2: Konfigurer repository-secrets

Du må legge til GitHub App-legitimasjon og AI-tjenestelegitimasjon som krypterte secrets i repository-innstillingene.

Gå til repositoryet ditt (f.eks. PhiCookBook).
Gå til Settings > Secrets and variables > Actions.
Under Repository secrets, klikk New repository secret for hver secret som er listet opp nedenfor.

Påkrevde secrets (for GitHub App-autentisering):

Secret Name	Beskrivelse	Kilde til verdi
`GH_APP_ID`	App ID for GitHub App (fra Steg 1).	GitHub App-innstillinger
`GH_APP_PRIVATE_KEY`	Hele innholdet i den nedlastede `.pem`-filen.	`.pem`-fil (fra Steg 1)

AI-tjeneste-secrets (legg til ALLE som gjelder ut fra forutsetningene dine):

Secret Name	Beskrivelse	Kilde til verdi
`AZURE_AI_SERVICE_API_KEY`	Nøkkel for Azure AI Service (Computer Vision)	Azure AI Foundry
`AZURE_AI_SERVICE_ENDPOINT`	Endpoint for Azure AI Service (Computer Vision)	Azure AI Foundry
`AZURE_OPENAI_API_KEY`	Nøkkel for Azure OpenAI-tjeneste	Azure AI Foundry
`AZURE_OPENAI_ENDPOINT`	Endpoint for Azure OpenAI-tjeneste	Azure AI Foundry
`AZURE_OPENAI_MODEL_NAME`	Ditt Azure OpenAI-modellnavn	Azure AI Foundry
`AZURE_OPENAI_CHAT_DEPLOYMENT_NAME`	Ditt Azure OpenAI deployment-navn	Azure AI Foundry
`AZURE_OPENAI_API_VERSION`	API-versjon for Azure OpenAI	Azure AI Foundry
`OPENAI_API_KEY`	API-nøkkel for OpenAI	OpenAI Platform
`OPENAI_ORG_ID`	OpenAI-organisasjons-ID	OpenAI Platform
`OPENAI_CHAT_MODEL_ID`	Spesifikk OpenAI-modell-ID	OpenAI Platform
`OPENAI_BASE_URL`	Tilpasset OpenAI API Base URL	OpenAI Platform

Skriv inn miljøvariabelnavn

Steg 3: Opprett workflow-filen

Til slutt, opprett YAML-filen som definerer den automatiserte workflowen.

I rotmappen til repositoryet ditt, opprett .github/workflows/-mappen hvis den ikke finnes.
Inne i .github/workflows/, opprett en fil som heter co-op-translator.yml.
Lim inn følgende innhold i 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 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/

Tilpass workflowen:
- [!IMPORTANT] Mål-språk: I steget Run Co-op Translator må du gå gjennom og endre listen over språk-koder i translate -l "..." -y-kommandoen slik at den passer til prosjektets behov. Eksempellisten (ar de es...) må byttes ut eller tilpasses.
- Trigger (on:): Nåværende trigger kjører på hver push til main. For store repositories, vurder å legge til en paths:-filter (se kommentert eksempel i YAML) for å kun kjøre workflowen når relevante filer (f.eks. kilde-dokumentasjon) endres, for å spare runner-minutter.
- PR-detaljer: Tilpass commit-message, title, body, branch-navn og labels i steget Create Pull Request om nødvendig.

Håndtering og fornyelse av legitimasjon

Sikkerhet: Oppbevar alltid sensitive legitimasjoner (API-nøkler, private nøkler) som GitHub Actions-secrets. Aldri eksponer dem i workflow-filen eller repository-koden.
[!IMPORTANT] Nøkkelfornyelse (interne Microsoft-brukere): Vær oppmerksom på at Azure OpenAI-nøkkelen brukt internt i Microsoft kan ha obligatorisk fornyelsespolicy (f.eks. hver 5. måned). Sørg for å oppdatere de tilhørende GitHub-secrets (AZURE_OPENAI_...-nøkler) før de utløper for å unngå feil i workflowen.

Kjøre workflowen

[!WARNING]
Tidsbegrensning for GitHub-hosted runner:
GitHub-hostede runnere som ubuntu-latest har en maksimal kjøretid på 6 timer.
For store dokumentasjons-repositories, hvis oversettelsesprosessen tar mer enn 6 timer, vil workflowen automatisk bli avbrutt.
For å unngå dette, vurder:

Å bruke en self-hosted runner (ingen tidsbegrensning)

Å redusere antall mål-språk per kjøring

Når co-op-translator.yml-filen er merget inn i hovedgrenen (eller grenen spesifisert i on:-triggeren), vil workflowen automatisk kjøres hver gang det pushes endringer til den grenen (og matcher paths-filteret, hvis konfigurert).

Hvis det genereres eller oppdateres oversettelser, vil actionen automatisk opprette en Pull Request med endringene, klar for gjennomgang og merging.

Ansvarsfraskrivelse: Dette dokumentet er oversatt ved hjelp av AI-oversettelsestjenesten Co-op Translator. Selv om vi tilstreber nøyaktighet, må du være oppmerksom på at automatiske oversettelser kan inneholde feil eller unøyaktigheter. Det originale dokumentet på sitt opprinnelige språk bør anses som den autoritative kilden. For kritisk informasjon anbefales profesjonell menneskelig oversettelse. Vi er ikke ansvarlige for eventuelle misforståelser eller feiltolkninger som oppstår ved bruk av denne oversettelsen.

This site is open source. Improve this page.