← Tillbaka till 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 inte översätta allt igen: hur deltaöversättning fungerar i CI

By Robert M

Du behöver inte översätta allt på nytt: hur delta-översättning fungerar i CI

När du har automatiserad översättning kopplad till din CI-pipeline uppstår snabbt en naturlig fråga: översätts hela lokaliseringsfilen varje gång någon gör en push?

Utan delta-läge, ja. Varje push som påverkar din källfil för lokaliseringsfilen skickar hela filen till API:et, varje nyckel, varje sträng, oavsett om den ändrats eller inte. För ett litet projekt i början är det okej. För ett moget projekt med hundratals översättningsnycklar på 10 eller 20 språk bränner du tokens på strängar som inte ändrats sedan senaste körningen och får tillbaka identisk output för det privilegiet.

Delta-översättning löser detta. Istället för att skicka hela filen jämför Action din nuvarande källfil mot en lagrad baslinje, identifierar bara de nycklar som lagts till eller ändrats och skickar bara dessa till API:et. Output för oförändrade nycklar tas från de befintliga översatta filerna. Tokenanvändningen sjunker för att matcha det faktiska arbetet som görs.

Hur baslinjen fungerar

När delta-läget körs första gången, eller när du tvingar en full uppdatering, översätter Action hela källfilen och lagrar en platt JSON-representation av den som en baslinjefil i ditt repository. Vid efterföljande körningar laddar Action den baslinjen, jämför den med den aktuella källfilen och bygger en payload som bara innehåller de ändrade nycklarna.

För JSON-lokaliseringsfiler lagras baslinjen som .polylingo-baseline.json i din meddelandekatalog. För YAML-lokaliseringsfiler är det .polylingo-yaml-baseline.json i din lokaliseringskatalog. För Laravel PHP lang-filer är det .polylingo-laravel-php-baseline.json i din lang-katalog.

Baslinjen committas tillsammans med dina översatta filer så att den följer med repositoryt. Varje utvecklare som klonar repot får samma baslinje som pipelinen arbetar från.

Vad räknas som en ändring

Diffen arbetar på den platta nyckelrepresentationen av din källfil. Inbäddade strukturer plattas ut till punktnotation-nycklar innan jämförelse:

{
  "nav.home": "Hem",
  "nav.about": "Om oss",
  "hero.title": "Välkommen till vår plattform",
  "hero.cta": "Kom igång"
}

En nyckel inkluderas i delta-payloaden om:

  • Den finns i den aktuella källfilen men inte i baslinjen (ny nyckel)
  • Den finns i båda men värdet har ändrats (modifierad nyckel) Nycklar som finns i baslinjen men inte i den aktuella källfilen (borttagna nycklar) tas automatiskt bort från de översatta outputfilerna. Nycklar som är identiska i båda hoppas helt över och deras befintliga översättningar lämnas kvar.

Hur detta ser ut i praktiken

Säg att du har ett Next.js-projekt med 200 översättningsnycklar i messages/en.json, redan översatta till 12 språk. En utvecklare uppdaterar texten i hero-sektionen och lägger till två nya nycklar för ett funktionsmeddelande. Det är 4 ändrade nycklar av 200.

Utan delta-läge skickar pipelinen alla 200 nycklar multiplicerat med 12 språk vid varje push. Med delta-läge skickas 4 nycklar. Tokenanvändningen för den körningen är ungefär 2% av vad en fullständig översättning skulle kosta. Pipelinen är också snabbare eftersom det är mindre att skicka och mindre att vänta på.

Under en månad av regelbunden utveckling ackumuleras besparingen betydligt. De flesta pushar påverkar bara några få strängar. Fullständig re-översättning sker bara när du lägger till ett nytt språk eller explicit återställer baslinjen.

De tre PolyLingo GitHub Actions

Delta-läget finns tillgängligt i alla tre PolyLingo-översättningsactions. Var och en är byggd för en specifik innehållstyp och projektstruktur.

translateAction — JSON och Markdown

Den ursprungliga Action. Hanterar platta JSON-lokaliseringsfiler i next-intl och i18next-stil, med en valfri Markdown-dokumentationspass via async jobs API för 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): synkronisera översättningar"

Delta-baslinje: messages/.polylingo-baseline.json

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

translate-action-yaml — YAML-lokaliseringsfiler

För projekt som använder inbäddade YAML-lokaliseringsfiler: Rails i18n, Vue i18n och andra ramverk som använder YAML-formatet. Action hanterar Rails-konventionen med en rotlokaliseringsnyckel automatiskt — en.yml har en rot-nyckel en:, och varje utdatafil får rätt mål-lokaliseringsnyckel (fr:, de: etc).

Eftersom PolyLingo API arbetar med JSON nativt, plattar Action ut inbäddad YAML till punktnotation JSON innan den skickas, översätter, återuppbygger sedan den inbäddade strukturen och skriver giltig YAML-output. En v1-varning att känna till: nycklar som naturligt innehåller punkter stöds inte, eftersom de kolliderar med punktnotationens plattningsmetod.

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

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

translate-action-laravel — Laravel lang-filer

För Laravel-projekt som använder antingen JSON-översättningsfiler (lang/en.json, som stöder både inbäddade och platta strukturer i Laravel 9+ stil) eller PHP-array lang-filer (lang/en/*.php). Action upptäcker automatiskt vilket format ditt projekt använder via php_format: auto — den kollar först efter lang/en.json och faller tillbaka till PHP-arrayfiler om den inte finns.

För PHP-filer anropar den PHP CLI för att läsa källfiler och serialiserar den översatta outputen tillbaka till giltig PHP-arraysyntax i JavaScript, utan ytterligare beroenden. GitHub-hostade ubuntu-latest runners inkluderar PHP 8.x som standard så ingen extra installationssteg behövs. PHP 7.4 eller senare krävs.

En v1-varning: nycklar som innehåller punkter stöds inte i PHP-läge på grund av punktnotationens plattningsstrategi.

- 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-baslinje: lang/.polylingo-laravel-json-baseline.json eller lang/.polylingo-laravel-php-baseline.json beroende på format.

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

PR-läge vs commit-läge

Alla tre Actions stödjer två utdata-lägen.

Commit-läge (commit: true) skriver de översatta filerna och committar dem direkt till den aktuella branchen. Enkel setup, bra för team som behandlar översättning som en automatiserad process som inte behöver granskning.

PR-läge (open_pr: true) skapar en ny branch (polylingo/yaml-<sha>, polylingo/laravel-<sha> etc), skriver de översatta filerna där och öppnar en pull request mot din basbranch. Bättre för team som vill ha en manuell granskningssteg innan översatt innehåll slås ihop, eller för projekt där översättningskvalitet direkt påverkar användarupplevelsen.

När båda är satta vinner PR-läget.

PR-läget kräver pull-requests: write i dina workflow-behörigheter:

permissions:
  contents: write
  pull-requests: write

Tvinga full uppdatering

Delta-läget jämför mot den lagrade baslinjen. Om du vill översätta allt på nytt oavsett vad baslinjen visar, sätt delta: false. Detta uppdaterar också baslinjen för att matcha den aktuella källfilen, så efterföljande delta-körningar startar från det nya tillståndet.

En full uppdatering är användbar när du lägger till ett nytt målspråk, när du vill ta till dig förbättringar i översättningskvalitet i en ny modellversion, eller när baslinjen har glidit från verkligheten av någon anledning.

- 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 uppdatering, uppdaterar baslinjen
    commit: true

Utdata för efterföljande steg

Alla tre Actions exponerar samma utdata så att du kan använda dem i efterföljande workflow-steg:

- 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: Logga översättningsstatistik
  run: |
    echo "Översatta lokaler: ${{ steps.translate.outputs.locales_translated }}"
    echo "Ändrade filer: ${{ steps.translate.outputs.files_changed }}"
    echo "Använda tokens: ${{ steps.translate.outputs.tokens_used }}"

Varje körning skriver också en sammanfattningstabell till GitHub Actions steg-sammanfattningen så att du kan se tokenanvändning och översättningsresultat utan att behöva gräva i loggar.

Kom igång

Alla tre Actions finns tillgängliga på GitHub Marketplace. Du behöver en PolyLingo API-nyckel, tillgänglig gratis på usepolylingo.com. Gratisnivån inkluderar 50 000 tokens per månad. Med delta-läget aktiverat kommer de flesta projekt att hålla sig väl inom detta vid rutinmässiga utvecklingspushar.

Lägg till din API-nyckel som en repository-hemlighet (POLYLINGO_API_KEY) och lägg in relevant Action i ditt workflow. Första körningen gör en fullständig översättning och sätter baslinjen. Varje körning efter det översätter bara det som ändrats.