← Tilbake til bloggen
A git diff view showing a locale file with three changed keys highlighted, and only those three keys being sent to the translation API below.

Du trenger ikke å oversette alt på nytt: hvordan delta-oversettelse fungerer i CI

By Robert M

Du trenger ikke å oversette alt på nytt: hvordan delta-oversettelse fungerer i CI

Når du har automatisert oversettelse koblet til CI-pipelinen din, dukker det raskt opp et naturlig spørsmål: oversettes hele lokaliseringsfilen på nytt hver gang noen gjør en endring?

Uten delta-modus, ja. Hver push som berører kildefilen din for lokaliseringsdata sender hele filen til API-en, hver nøkkel, hver streng, enten den har endret seg eller ikke. For et lite prosjekt tidlig i utviklingen er det greit. For et modent prosjekt med hundrevis av oversettingsnøkler på tvers av 10 eller 20 språk, bruker du opp tokens på strenger som ikke har endret seg siden forrige kjøring, og får tilbake identisk output som "belønning".

Delta-oversettelse løser dette. I stedet for å sende hele filen, sammenligner Action den nåværende kildefilen med en lagret basislinje, identifiserer bare nøklene som er lagt til eller endret, og sender bare disse til API-en. Output for uendrede nøkler hentes fra de eksisterende oversatte filene. Token-bruken reduseres for å matche det faktiske arbeidet som gjøres.

Hvordan basislinjen fungerer

Når delta-modus kjører for første gang, eller når du tvinger en full oppdatering, oversetter Action hele kildefilen og lagrer en flat JSON-representasjon av den som en basislinjefil i depotet ditt. Ved påfølgende kjøringer laster Action denne basislinjen, sammenligner den med den nåværende kildefilen, og bygger en payload som bare inneholder de endrede nøklene.

For JSON lokaliseringsfiler lagres basislinjen som .polylingo-baseline.json i meldingsmappen din. For YAML lokaliseringsfiler er det .polylingo-yaml-baseline.json i lokaliseringsmappen din. For Laravel PHP lang-filer er det .polylingo-laravel-php-baseline.json i lang-mappen din.

Basislinjen blir committet sammen med de oversatte filene slik at den følger med depotet. Enhver utvikler som kloner repoet får samme basislinje som pipelinen jobber ut fra.

Hva som teller som en endring

Diffen opererer på den flatlagte nøkkelrepresentasjonen av kildefilen din. Nestede strukturer flatlegges til punktnotasjon-nøkler før sammenligning:

{
  "nav.home": "Hjem",
  "nav.about": "Om oss",
  "hero.title": "Velkommen til vår plattform",
  "hero.cta": "Kom i gang"
}

En nøkkel inkluderes i delta-payloaden hvis:

  • Den finnes i den nåværende kildefilen, men ikke i basislinjen (ny nøkkel)
  • Den finnes i begge, men verdien har endret seg (endret nøkkel) Nøkler som finnes i basislinjen, men ikke i den nåværende kildefilen (slettede nøkler) fjernes automatisk fra de oversatte output-filene. Nøkler som er identiske i begge blir helt hoppet over, og deres eksisterende oversettelser blir beholdt.

Hvordan dette ser ut i praksis

Si at du har et Next.js-prosjekt med 200 oversettingsnøkler i messages/en.json, allerede oversatt til 12 språk. En utvikler oppdaterer teksten i hero-seksjonen og legger til to nye nøkler for en funksjonsannonse. Det er 4 endrede nøkler av 200.

Uten delta-modus sender pipelinen alle 200 nøkler multiplisert over 12 språk ved hver push. Med delta-modus sender den 4 nøkler. Token-bruken for den kjøringen er omtrent 2 % av hva en full oversettelse ville kostet. Pipelinen er også raskere fordi det er mindre å sende og mindre å vente på.

Over en måned med vanlig utvikling akkumuleres besparelsen betydelig. De fleste pushes berører bare noen få strenger. Full re-oversettelse skjer bare når du legger til et nytt språk eller eksplisitt tilbakestiller basislinjen.

De tre PolyLingo GitHub Actions

Delta-modus er tilgjengelig i alle tre PolyLingo oversettelses-Actions. Hver er bygget for en spesifikk innholdstype og prosjektstruktur.

translateAction — JSON og Markdown

Den originale Action. Håndterer flate JSON lokaliseringsfiler i next-intl og i18next-stil, med en valgfri Markdown dokumentasjonsrunde via async jobs API for større filer.

- uses: UsePolyLingo/translate-action@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    source_file: messages/en.json
    locales: fr,de,es,ja,zh
    delta: true
    commit: true
    commit_message: "chore(i18n): sync translations"

Delta basislinje: messages/.polylingo-baseline.json

github.com/UsePolyLingo/translateAction — Se på Marketplace

translate-action-yaml — YAML lokaliseringsfiler

For prosjekter som bruker nestede YAML lokaliseringsfiler: Rails i18n, Vue i18n, og andre rammeverk som bruker YAML-formatet. Action håndterer Rails-konvensjonen med en rotlokaliseringsnøkkel automatisk — en.yml har en en: rot-nøkkel, og hver utdatafil får riktig mål-lokaliseringsnøkkel (fr:, de: osv).

Siden PolyLingo API fungerer med JSON nativt, flater Action ut nestet YAML til dot-notasjon JSON før sending, oversetter, bygger så opp den nestede strukturen igjen og skriver gyldig YAML-output. En v1 caveat verdt å vite: nøkler som naturlig inneholder punktum støttes ikke, da de kolliderer med dot-notasjon-utflatningen.

- uses: UsePolyLingo/translate-action-yaml@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    locales_dir: config/locales
    source_file: config/locales/en.yml
    locales: fr,de,es,ja
    delta: true
    commit: true

Delta basislinje: config/locales/.polylingo-yaml-baseline.json

github.com/UsePolyLingo/translate-action-yaml — Se på Marketplace

translate-action-laravel — Laravel lang-filer

For Laravel-prosjekter som bruker enten JSON oversettelsesfiler (lang/en.json, støtter både nestede og flate strukturer i Laravel 9+ stil) eller PHP array lang-filer (lang/en/*.php). Action oppdager automatisk hvilket format prosjektet ditt bruker via php_format: auto — den sjekker først for lang/en.json og faller tilbake til PHP array-filer hvis ikke funnet.

For PHP-filer kjører den PHP CLI for å lese kildefiler og serialiserer oversatt output tilbake til gyldig PHP array-syntaks i JavaScript, uten ekstra avhengigheter. GitHub-hostede ubuntu-latest runners inkluderer PHP 8.x som standard, så ingen ekstra oppsett trengs. PHP 7.4 eller nyere kreves.

En v1 caveat: nøkler som inneholder punktum støttes ikke i PHP-modus på grunn av dot-notasjon-utflatningsstrategien.

- uses: UsePolyLingo/translate-action-laravel@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    lang_dir: lang
    source_locale: en
    locales: fr,de,es,pt,nl
    php_format: auto
    delta: true
    open_pr: true

Delta basislinje: lang/.polylingo-laravel-json-baseline.json eller lang/.polylingo-laravel-php-baseline.json avhengig av format.

github.com/UsePolyLingo/translate-action-laravel — Se på Marketplace

PR-modus vs commit-modus

Alle tre Actions støtter to output-moduser.

Commit-modus (commit: true) skriver de oversatte filene og committer dem direkte til den nåværende branchen. Enkel oppsett, bra for team som behandler oversettelse som en automatisert prosess som ikke trenger gjennomgang.

PR-modus (open_pr: true) lager en ny branch (polylingo/yaml-<sha>, polylingo/laravel-<sha> osv), skriver de oversatte filene der, og åpner en pull request mot basebranchen din. Bedre for team som ønsker et menneskelig gjennomgangstrinn før oversatt innhold merges, eller for prosjekter der oversettelseskvalitet direkte påvirker brukeropplevelsen.

Når begge er satt, vinner PR-modus.

PR-modus krever pull-requests: write i workflow-tillatelsene dine:

permissions:
  contents: write
  pull-requests: write

Tvinge full oppdatering

Delta-modus sammenligner med lagret basislinje. Hvis du vil oversette alt på nytt uansett hva basislinjen viser, sett delta: false. Dette oppdaterer også basislinjen for å matche den nåværende kildefilen, så påfølgende delta-kjøringer starter fra den nye tilstanden.

En full oppdatering er nyttig når du legger til et nytt målspråk, når du vil hente forbedringer i oversettelseskvalitet i en ny modellversjon, eller når basislinjen har drevet bort fra virkeligheten av en eller annen grunn.

- uses: UsePolyLingo/translate-action-yaml@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    locales_dir: config/locales
    locales: fr,de,es,ja,zh,ko,ar
    delta: false  # full oppdatering, oppdaterer basislinje
    commit: true

Outputs for downstream steps

Alle tre Actions eksponerer samme outputs slik at du kan bruke dem i påfølgende workflow-trinn:

- uses: UsePolyLingo/translate-action@v1
  id: translate
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    source_file: messages/en.json
    locales: fr,de,es
    delta: true
    commit: true

- name: Logg oversettelsesstatistikk
  run: |
    echo "Oversatte språk: ${{ steps.translate.outputs.locales_translated }}"
    echo "Endrede filer: ${{ steps.translate.outputs.files_changed }}"
    echo "Brukte tokens: ${{ steps.translate.outputs.tokens_used }}"

Hver kjøring skriver også en oppsummeringstabell til GitHub Actions steg-oppsummeringen slik at du kan se token-bruk og oversettelsesresultater uten å måtte lete i logger.

Komme i gang

Alle tre Actions er tilgjengelige på GitHub Marketplace. Du trenger en PolyLingo API-nøkkel, tilgjengelig gratis på usepolylingo.com. Gratisnivået inkluderer 50 000 tokens per måned. Med delta-modus aktivert vil de fleste prosjekter holde seg godt innenfor dette ved rutinemessige utviklingspush.

Legg til API-nøkkelen din som et repository secret (POLYLINGO_API_KEY) og legg til relevant Action i workflowen din. Første kjøring gjør en full oversettelse og setter basislinjen. Hver kjøring etter det oversetter bare det som har endret seg.