← Terug naar blog
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.

Je hoeft niet alles opnieuw te vertalen: hoe delta-vertaling werkt in CI

By Robert M

Je hoeft niet alles opnieuw te vertalen: hoe delta-vertaling werkt in CI

Zodra je geautomatiseerde vertaling hebt geïntegreerd in je CI-pijplijn, komt er snel een natuurlijke vraag op: wordt het hele locale-bestand elke keer opnieuw vertaald wanneer iemand een wijziging doorvoert?

Zonder delta-modus, ja. Elke push die je bronlocale-bestand aanraakt, stuurt het hele bestand naar de API, elke sleutel, elke string, of deze nu veranderd is of niet. Voor een klein project in een vroeg stadium is dat prima. Voor een volwassen project met honderden vertalingssleutels in 10 of 20 talen, verbruik je tokens voor strings die sinds de laatste run niet veranderd zijn en krijg je identieke output terug als 'beloning'.

Delta-vertaling lost dit op. In plaats van het volledige bestand te sturen, vergelijkt de Action je huidige bronbestand met een opgeslagen basislijn, identificeert alleen de sleutels die zijn toegevoegd of gewijzigd, en stuurt alleen die naar de API. De output voor ongewijzigde sleutels wordt genomen uit de bestaande vertaalde bestanden. Het tokengebruik daalt om overeen te komen met het werk dat daadwerkelijk gedaan wordt.

Hoe de basislijn werkt

Wanneer de delta-modus voor het eerst draait, of wanneer je een volledige verversing forceert, vertaalt de Action het complete bronbestand en slaat een platte JSON-weergave ervan op als een basislijnbestand in je repository. Bij volgende runs laadt de Action die basislijn, vergelijkt deze met het huidige bronbestand, en bouwt een payload die alleen de gewijzigde sleutels bevat.

Voor JSON locale-bestanden wordt de basislijn opgeslagen als .polylingo-baseline.json in je messages-directory. Voor YAML locale-bestanden is het .polylingo-yaml-baseline.json in je locales-directory. Voor Laravel PHP lang-bestanden is het .polylingo-laravel-php-baseline.json in je lang-directory.

De basislijn wordt gecommit samen met je vertaalde bestanden zodat het meereist met de repository. Elke ontwikkelaar die de repo kloont, krijgt dezelfde basislijn waar de pijplijn mee werkt.

Wat telt als een wijziging

De diff werkt op de afgevlakte sleutelrepresentatie van je bronbestand. Geneste structuren worden afgevlakt naar dot-notatie sleutels voor vergelijking:

{
  "nav.home": "Home",
  "nav.about": "Over ons",
  "hero.title": "Welkom op ons platform",
  "hero.cta": "Begin nu"
}

Een sleutel wordt opgenomen in de delta-payload als:

  • Het bestaat in het huidige bronbestand maar niet in de basislijn (nieuwe sleutel)
  • Het bestaat in beide maar de waarde is veranderd (gewijzigde sleutel) Sleutels die in de basislijn bestaan maar niet in het huidige bronbestand (verwijderde sleutels) worden automatisch verwijderd uit de vertaalde outputbestanden. Sleutels die identiek zijn in beide worden volledig overgeslagen en hun bestaande vertalingen blijven staan.

Hoe dit er in de praktijk uitziet

Stel je hebt een Next.js-project met 200 vertalingssleutels in messages/en.json, al vertaald in 12 talen. Een ontwikkelaar werkt de hero-sectie bij en voegt twee nieuwe sleutels toe voor een feature-aankondiging. Dat zijn 4 gewijzigde sleutels van de 200.

Zonder delta-modus stuurt de pijplijn alle 200 sleutels vermenigvuldigd over 12 talen bij elke push. Met delta-modus stuurt het 4 sleutels. Het tokengebruik voor die run is ongeveer 2% van wat een volledige vertaling zou kosten. De pijplijn is ook sneller omdat er minder te versturen en minder om op te wachten is.

Over een maand van reguliere ontwikkeling stapelt de besparing zich flink op. De meeste pushes raken slechts een handvol strings aan. Volledige hervertaling gebeurt alleen als je een nieuwe taal toevoegt of expliciet de basislijn reset.

De drie PolyLingo GitHub Actions

Delta-modus is beschikbaar in alle drie PolyLingo vertaal-Actions. Elk is gebouwd voor een specifiek contenttype en projectstructuur.

translateAction — JSON en Markdown

De originele Action. Behandelt platte JSON locale-bestanden in de next-intl en i18next stijl, met een optionele Markdown documentatie-run via de async jobs API voor grotere bestanden.

- 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 basislijn: messages/.polylingo-baseline.json

github.com/UsePolyLingo/translateAction — Bekijk op Marketplace

translate-action-yaml — YAML locale-bestanden

Voor projecten die geneste YAML locale-bestanden gebruiken: Rails i18n, Vue i18n, en elk ander framework dat het YAML-formaat gebruikt. De Action behandelt automatisch de Rails-conventie van een root locale key — en.yml heeft een en: root key, en elk outputbestand krijgt de juiste doel-locale key (fr:, de: etc).

Omdat de PolyLingo API native met JSON werkt, vlakt de Action geneste YAML af naar dot-notatie JSON voor verzending, vertaalt, bouwt dan de geneste structuur weer op en schrijft geldige YAML output. Een v1 caveat om te weten: sleutels die van nature punten bevatten worden niet ondersteund, omdat ze conflicteren met de dot-notatie afvlakking.

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

github.com/UsePolyLingo/translate-action-yaml — Bekijk op Marketplace

translate-action-laravel — Laravel lang-bestanden

Voor Laravel-projecten die JSON vertaalbestanden gebruiken (lang/en.json, ondersteunt zowel geneste als platte structuren in Laravel 9+ stijl) of PHP array lang-bestanden (lang/en/*.php). De Action detecteert automatisch welk formaat je project gebruikt via php_format: auto — het controleert eerst op lang/en.json en valt terug op PHP array-bestanden als die niet gevonden worden.

Voor PHP-bestanden roept het de PHP CLI aan om bronbestanden te lezen en serialiseert vertaalde output terug naar geldige PHP array-syntaxis in JavaScript, zonder extra afhankelijkheden. GitHub-gehoste ubuntu-latest runners bevatten standaard PHP 8.x dus geen extra setup stap nodig. PHP 7.4 of later is vereist.

Een v1 caveat: sleutels met punten worden niet ondersteund in PHP-modus vanwege de dot-notatie afvlakking.

- 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 basislijn: lang/.polylingo-laravel-json-baseline.json of lang/.polylingo-laravel-php-baseline.json afhankelijk van het formaat.

github.com/UsePolyLingo/translate-action-laravel — Bekijk op Marketplace

PR-modus vs commit-modus

Alle drie Actions ondersteunen twee output-modi.

Commit-modus (commit: true) schrijft de vertaalde bestanden en commit ze direct naar de huidige branch. Eenvoudige setup, goed voor teams die vertaling als een geautomatiseerd proces zien dat geen review nodig heeft.

PR-modus (open_pr: true) maakt een nieuwe branch aan (polylingo/yaml-<sha>, polylingo/laravel-<sha> etc), schrijft de vertaalde bestanden daar, en opent een pull request naar je basisbranch. Beter voor teams die een menselijke review stap willen voordat vertaalde content wordt gemerged, of voor projecten waar vertaalkwaliteit direct de gebruikerservaring beïnvloedt.

Wanneer beide zijn ingesteld, wint PR-modus.

PR-modus vereist pull-requests: write in je workflow permissies:

permissions:
  contents: write
  pull-requests: write

Een volledige verversing forceren

Delta-modus vergelijkt met de opgeslagen basislijn. Als je alles opnieuw wilt vertalen ongeacht wat de basislijn toont, zet delta: false. Dit werkt ook de basislijn bij om overeen te komen met het huidige bronbestand, zodat volgende delta-runs starten vanuit de nieuwe staat.

Een volledige verversing is nuttig wanneer je een nieuwe doeltaal toevoegt, wanneer je vertaalkwaliteitsverbeteringen in een nieuw model wilt oppikken, of wanneer de basislijn om welke reden dan ook is afgeweken van de werkelijkheid.

- 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  # volledige verversing, werkt basislijn bij
    commit: true

Outputs voor downstream stappen

Alle drie Actions bieden dezelfde outputs zodat je ze kunt gebruiken in volgende workflow-stappen:

- 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 vertaalstatistieken
  run: |
    echo "Vertaalde talen: ${{ steps.translate.outputs.locales_translated }}"
    echo "Gewijzigde bestanden: ${{ steps.translate.outputs.files_changed }}"
    echo "Gebruikte tokens: ${{ steps.translate.outputs.tokens_used }}"

Elke run schrijft ook een samenvattingstabel naar de GitHub Actions stap-samenvatting zodat je tokengebruik en vertaalresultaten kunt zien zonder door logs te hoeven zoeken.

Aan de slag

Alle drie Actions zijn beschikbaar op de GitHub Marketplace. Je hebt een PolyLingo API-sleutel nodig, gratis beschikbaar op usepolylingo.com. Het gratis niveau bevat 50.000 tokens per maand. Met delta-modus ingeschakeld blijven de meeste projecten ruim binnen die limiet bij routine-ontwikkelingspushes.

Voeg je API-sleutel toe als een repository secret (POLYLINGO_API_KEY) en voeg de relevante Action toe aan je workflow. De eerste run doet een volledige vertaling en zet de basislijn. Elke run daarna vertaalt alleen wat veranderd is.