← Zpět na 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.

Nemusíte překládat vše znovu: jak funguje delta překlad v CI

By Robert M

Nemusíte překládat vše znovu: jak funguje delta překlad v CI

Jakmile máte automatizovaný překlad zapojený do vašeho CI pipeline, rychle se objeví přirozená otázka: překládá se pokaždé celý lokalizační soubor, když někdo provede změnu?

Bez delta režimu ano. Každý push, který zasáhne váš zdrojový lokalizační soubor, odešle celý soubor do API, každý klíč, každý řetězec, ať už se změnil nebo ne. Pro malý projekt na začátku je to v pořádku. Pro zralý projekt se stovkami překladových klíčů ve 10 nebo 20 jazycích však plýtváte tokeny na řetězce, které se od posledního běhu nezměnily, a dostáváte zpět identický výstup.

Delta překlad toto řeší. Místo odesílání celého souboru akce porovná váš aktuální zdrojový soubor s uloženou základnou, identifikuje pouze klíče, které byly přidány nebo upraveny, a odešle pouze tyto do API. Výstup pro nezměněné klíče se bere ze stávajících přeložených souborů. Spotřeba tokenů klesá na úroveň skutečné vykonané práce.

Jak funguje základna

Když delta režim běží poprvé, nebo když vynutíte úplné obnovení, akce přeloží celý zdrojový soubor a uloží jeho plochou JSON reprezentaci jako základní soubor ve vašem repozitáři. Při následných bězích akce načte tuto základnu, porovná ji s aktuálním zdrojovým souborem a vytvoří payload obsahující pouze změněné klíče.

Pro JSON lokalizační soubory je základna uložena jako .polylingo-baseline.json ve vašem adresáři s zprávami. Pro YAML lokalizační soubory je to .polylingo-yaml-baseline.json ve vašem adresáři locales. Pro Laravel PHP lang soubory je to .polylingo-laravel-php-baseline.json v adresáři lang.

Základna je commitována spolu s vašimi přeloženými soubory, takže cestuje s repozitářem. Každý vývojář, který repozitář klonuje, získá stejnou základnu, ze které pipeline pracuje.

Co se počítá jako změna

Diff pracuje s plochou reprezentací klíčů vašeho zdrojového souboru. Vnořené struktury jsou před porovnáním zploštěny do klíčů s tečkovou notací:

{
  "nav.home": "Domů",
  "nav.about": "O nás",
  "hero.title": "Vítejte na naší platformě",
  "hero.cta": "Začněte"
}

Klíč je zahrnut do delta payloadu, pokud:

  • Existuje v aktuálním zdrojovém souboru, ale ne v základně (nový klíč)
  • Existuje v obou, ale hodnota se změnila (upravený klíč) Klíče, které jsou v základně, ale ne v aktuálním zdrojovém souboru (smazané klíče), jsou automaticky odstraněny z přeložených výstupních souborů. Klíče, které jsou v obou identické, jsou zcela přeskočeny a jejich stávající překlady zůstávají na místě.

Jak to vypadá v praxi

Řekněme, že máte projekt Next.js se 200 překladovými klíči v messages/en.json, již přeloženými do 12 jazyků. Vývojář aktualizuje text v sekci hero a přidá dva nové klíče pro oznámení funkce. To jsou 4 změněné klíče z 200.

Bez delta režimu pipeline posílá všech 200 klíčů vynásobených 12 jazyky při každém pushi. S delta režimem posílá 4 klíče. Spotřeba tokenů pro tento běh je přibližně 2 % toho, co by stála úplná překlad. Pipeline je také rychlejší, protože je méně dat k odeslání a méně čekání.

Během měsíce pravidelného vývoje se úspora výrazně kumuluje. Většina pushů zasahuje jen několik řetězců. Úplná pře-translation nastává pouze při přidání nového jazyka nebo explicitním resetování základny.

Tři PolyLingo GitHub Actions

Delta režim je dostupný ve všech třech PolyLingo překladových akcích. Každá je postavena pro specifický typ obsahu a strukturu projektu.

translateAction — JSON a Markdown

Původní akce. Zpracovává ploché JSON lokalizační soubory ve stylu next-intl a i18next, s volitelným průchodem Markdown dokumentace přes async jobs API pro větší soubory.

- 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 základna: messages/.polylingo-baseline.json

github.com/UsePolyLingo/translateAction — Zobrazit na Marketplace

translate-action-yaml — YAML lokalizační soubory

Pro projekty používající vnořené YAML lokalizační soubory: Rails i18n, Vue i18n a jakýkoli jiný framework používající YAML formát. Akce automaticky zpracovává Rails konvenci kořenového lokalizačního klíče — en.yml má kořenový klíč en:, a každý výstupní soubor dostane správný cílový lokalizační klíč (fr:, de: atd).

Protože PolyLingo API nativně pracuje s JSON, akce zplošťuje vnořený YAML do JSON s tečkovou notací před odesláním, překládá a pak rekonstruuje vnořenou strukturu a zapisuje platný YAML výstup. Jedna poznámka k verzi v1: klíče obsahující tečky nejsou podporovány, protože kolidují se zplošťováním tečkovou notací.

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

github.com/UsePolyLingo/translate-action-yaml — Zobrazit na Marketplace

translate-action-laravel — Laravel lang soubory

Pro Laravel projekty používající buď JSON překladové soubory (lang/en.json, podporující jak vnořené, tak ploché struktury ve stylu Laravel 9+), nebo PHP pole lang soubory (lang/en/*.php). Akce automaticky detekuje, jaký formát váš projekt používá pomocí php_format: auto — nejprve kontroluje lang/en.json a pokud nenajde, použije PHP pole soubory.

Pro PHP soubory používá PHP CLI ke čtení zdrojových souborů a serializuje přeložený výstup zpět do platné PHP pole syntaxe v JavaScriptu, bez dalších závislostí. GitHub-hostované ubuntu-latest běžící stroje obsahují PHP 8.x ve výchozím nastavení, takže není potřeba další nastavení. Vyžaduje PHP 7.4 nebo novější.

Jedna poznámka k verzi v1: klíče obsahující tečky nejsou v PHP režimu podporovány kvůli strategii zplošťování tečkovou notací.

- 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 základna: lang/.polylingo-laravel-json-baseline.json nebo lang/.polylingo-laravel-php-baseline.json podle formátu.

github.com/UsePolyLingo/translate-action-laravel — Zobrazit na Marketplace

PR režim vs commit režim

Všechny tři akce podporují dva výstupní režimy.

Commit režim (commit: true) zapisuje přeložené soubory a přímo je commitne do aktuální větve. Jednoduché nastavení, vhodné pro týmy, které považují překlad za automatizovaný proces, který nepotřebuje kontrolu.

PR režim (open_pr: true) vytvoří novou větev (polylingo/yaml-<sha>, polylingo/laravel-<sha> atd.), zapíše tam přeložené soubory a otevře pull request proti vaší základní větvi. Lepší pro týmy, které chtějí lidskou kontrolu před sloučením přeloženého obsahu, nebo pro projekty, kde kvalita překladu přímo ovlivňuje uživatelský zážitek.

Pokud jsou oba nastaveny, PR režim má přednost.

PR režim vyžaduje v oprávněních workflow pull-requests: write:

permissions:
  contents: write
  pull-requests: write

Vynucení úplného obnovení

Delta režim porovnává se uloženou základnou. Pokud chcete přeložit vše znovu bez ohledu na to, co základna ukazuje, nastavte delta: false. To také aktualizuje základnu tak, aby odpovídala aktuálnímu zdrojovému souboru, takže následné delta běhy začínají z nového stavu.

Úplné obnovení je užitečné, když přidáte nový cílový jazyk, chcete zachytit zlepšení kvality překladu v nové verzi modelu, nebo když základna z nějakého důvodu odchýlila od reality.

- 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  # úplné obnovení, aktualizuje základnu
    commit: true

Výstupy pro následující kroky

Všechny tři akce vystavují stejné výstupy, takže je můžete použít v následujících krocích workflow:

- 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 }}"

Každý běh také zapíše souhrnnou tabulku do shrnutí kroku GitHub Actions, takže můžete vidět využití tokenů a výsledky překladu bez nutnosti procházet logy.

Začínáme

Všechny tři akce jsou dostupné na GitHub Marketplace. Budete potřebovat PolyLingo API klíč, který je zdarma dostupný na usepolylingo.com. Bezplatný plán zahrnuje 50 000 tokenů měsíčně. S povoleným delta režimem většina projektů zůstane v tomto limitu při běžných vývojových pushech.

Přidejte svůj API klíč jako tajemství repozitáře (POLYLINGO_API_KEY) a vložte příslušnou akci do svého workflow. První běh provede úplný překlad a nastaví základnu. Každý další běh překládá pouze to, co se změnilo.