← Tilbage 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 behøver ikke at oversætte alt igen: hvordan deltaoversættelse fungerer i CI

By Robert M

Du behøver ikke at oversætte alt igen: hvordan delta-oversættelse fungerer i CI

Når du har automatiseret oversættelse integreret i din CI-pipeline, opstår der hurtigt et naturligt spørgsmål: oversætter den hele lokaliseringsfilen hver gang, nogen pusher en ændring?

Uden delta-tilstand, ja. Hver push, der berører din kilde-lokaliseringsfil, sender hele filen til API'en, hver nøgle, hver streng, uanset om den er ændret eller ej. For et lille projekt i starten er det fint. For et modent projekt med hundredvis af oversættelsesnøgler på tværs af 10 eller 20 sprog, brænder du tokens af på strenge, der ikke har ændret sig siden sidste kørsel, og får tilbage identisk output som en "fordel".

Delta-oversættelse løser dette. I stedet for at sende hele filen sammenligner handlingen din nuværende kildefil med en gemt baseline, identificerer kun de nøgler, der er tilføjet eller ændret, og sender kun dem til API'en. Outputtet for uændrede nøgler tages fra de eksisterende oversatte filer. Tokenforbruget falder til at matche det faktiske arbejde, der udføres.

Hvordan baseline fungerer

Når delta-tilstand kører første gang, eller når du tvinger en fuld opdatering, oversætter handlingen den komplette kildefil og gemmer en flad JSON-repræsentation af den som en baseline-fil i dit repository. Ved efterfølgende kørsel loader handlingen den baseline, sammenligner den med den aktuelle kildefil og bygger en payload, der kun indeholder de ændrede nøgler.

For JSON lokaliseringsfiler gemmes baselinen som .polylingo-baseline.json i din messages-mappe. For YAML lokaliseringsfiler er det .polylingo-yaml-baseline.json i din locales-mappe. For Laravel PHP lang-filer er det .polylingo-laravel-php-baseline.json i din lang-mappe.

Baselinen committes sammen med dine oversatte filer, så den følger med repositoryet. Enhver udvikler, der kloner repoet, får den samme baseline, som pipelinen arbejder ud fra.

Hvad tæller som en ændring

Diffen opererer på den flade nøgle-repræsentation af din kildefil. Indlejrede strukturer flades ud til dot-notation nøgler før sammenligning:

{
  "nav.home": "Hjem",
  "nav.about": "Om os",
  "hero.title": "Velkommen til vores platform",
  "hero.cta": "Kom i gang"
}

En nøgle inkluderes i delta-payloaden, hvis:

  • Den findes i den aktuelle kildefil, men ikke i baselinen (ny nøgle)
  • Den findes i begge, men værdien er ændret (ændret nøgle) Nøgler, der findes i baselinen, men ikke i den aktuelle kildefil (slettede nøgler), fjernes automatisk fra de oversatte outputfiler. Nøgler, der er identiske i begge, springes helt over, og deres eksisterende oversættelser forbliver på plads.

Hvordan det ser ud i praksis

Lad os sige, at du har et Next.js-projekt med 200 oversættelsesnøgler i messages/en.json, allerede oversat til 12 sprog. En udvikler opdaterer hero-sektionens tekst og tilføjer to nye nøgler til en funktionsmeddelelse. Det er 4 ændrede nøgler ud af 200.

Uden delta-tilstand sender pipelinen alle 200 nøgler ganget med 12 sprog ved hver push. Med delta-tilstand sendes 4 nøgler. Tokenforbruget for den kørsel er cirka 2 % af, hvad en fuld oversættelse ville koste. Pipelinen er også hurtigere, fordi der er mindre at sende og mindre at vente på.

Over en måned med regelmæssig udvikling akkumuleres besparelsen betydeligt. De fleste pushes berører kun en håndfuld strenge. Fuld genoversættelse sker kun, når du tilføjer et nyt sprog eller eksplicit nulstiller baselinen.

De tre PolyLingo GitHub Actions

Delta-tilstand er tilgængelig på alle tre PolyLingo oversættelsesactions. Hver er bygget til en specifik indholdstype og projektstruktur.

translateAction — JSON og Markdown

Den oprindelige action. Håndterer flade JSON lokaliseringsfiler i next-intl og i18next stil, med en valgfri Markdown dokumentationspas 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 baseline: messages/.polylingo-baseline.json

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

translate-action-yaml — YAML lokaliseringsfiler

For projekter, der bruger indlejrede YAML lokaliseringsfiler: Rails i18n, Vue i18n og enhver anden ramme, der bruger YAML-formatet. Action håndterer Rails-konventionen med en rod-lokaliseringsnøgle automatisk — en.yml har en en: rodnøgle, og hver outputfil får den korrekte mål-lokaliseringsnøgle (fr:, de: osv).

Da PolyLingo API arbejder med JSON som standard, flader action indlejret YAML ud til dot-notation JSON før afsendelse, oversætter, og rekonstruerer derefter den indlejrede struktur og skriver gyldig YAML-output. En v1-advarsel værd at kende: nøgler, der naturligt indeholder prikker, understøttes ikke, da de konflikter med dot-notation fladningen.

- 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 baseline: config/locales/.polylingo-yaml-baseline.json

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

translate-action-laravel — Laravel lang filer

For Laravel projekter, der bruger enten JSON oversættelsesfiler (lang/en.json, understøtter både indlejrede og flade strukturer i Laravel 9+ stil) eller PHP array lang filer (lang/en/*.php). Action opdager automatisk, hvilket format dit projekt bruger via php_format: auto — den tjekker først for lang/en.json og falder tilbage til PHP array filer, hvis ikke fundet.

For PHP filer bruger den PHP CLI til at læse kildefiler og serialiserer oversat output tilbage til gyldig PHP array-syntaks i JavaScript, uden yderligere afhængigheder. GitHub-hostede ubuntu-latest runners inkluderer PHP 8.x som standard, så der er ikke behov for ekstra opsætning. PHP 7.4 eller nyere kræves.

En v1-advarsel: nøgler, der indeholder prikker, understøttes ikke i PHP-tilstand på grund af dot-notation fladningsstrategien.

- 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 baseline: lang/.polylingo-laravel-json-baseline.json eller lang/.polylingo-laravel-php-baseline.json afhængigt af format.

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

PR-tilstand vs commit-tilstand

Alle tre actions understøtter to output-tilstande.

Commit-tilstand (commit: true) skriver de oversatte filer og committer dem direkte til den aktuelle gren. Simpel opsætning, godt for teams, der behandler oversættelse som en automatiseret proces, der ikke behøver gennemgang.

PR-tilstand (open_pr: true) opretter en ny gren (polylingo/yaml-<sha>, polylingo/laravel-<sha> osv.), skriver de oversatte filer der, og åbner en pull request mod din basegren. Bedre for teams, der ønsker et menneskeligt review trin, før oversat indhold merges, eller for projekter hvor oversættelseskvalitet direkte påvirker brugeroplevelsen.

Når begge er sat, vinder PR-tilstand.

PR-tilstand kræver pull-requests: write i dine workflow-tilladelser:

permissions:
  contents: write
  pull-requests: write

Tving en fuld opdatering

Delta-tilstand sammenligner med den gemte baseline. Hvis du vil oversætte alt igen uanset hvad baselinen viser, sæt delta: false. Dette opdaterer også baselinen til at matche den aktuelle kildefil, så efterfølgende delta-kørsler starter fra den nye tilstand.

En fuld opdatering er nyttig, når du tilføjer et nyt målsprog, når du vil hente forbedringer i oversættelseskvalitet i en ny modelversion, eller når baselinen af en eller anden grund er drejet væk fra virkeligheden.

- 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  # fuld opdatering, opdaterer baseline
    commit: true

Output til efterfølgende trin

Alle tre actions eksponerer de samme outputs, så du kan bruge dem i efterfølgende workflow-trin:

- 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: Log translation stats
  run: |
    echo "Locales translated: ${{ steps.translate.outputs.locales_translated }}"
    echo "Files changed: ${{ steps.translate.outputs.files_changed }}"
    echo "Tokens used: ${{ steps.translate.outputs.tokens_used }}"

Hver kørsel skriver også en opsummeringstabel til GitHub Actions step summary, så du kan se tokenforbrug og oversættelsesresultater uden at skulle gennemse logs.

Kom godt i gang

Alle tre actions er tilgængelige på GitHub Marketplace. Du skal bruge en PolyLingo API-nøgle, som er gratis tilgængelig på usepolylingo.com. Det gratis niveau inkluderer 50.000 tokens pr. måned. Med delta-tilstand aktiveret vil de fleste projekter holde sig godt inden for dette ved rutinemæssige udviklingspush.

Tilføj din API-nøgle som et repository secret (POLYLINGO_API_KEY) og indsæt den relevante action i dit workflow. Første kørsel laver en fuld oversættelse og sætter baseline. Hver kørsel efter det oversætter kun det, der er ændret.