← Powrót do bloga
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.

Nie musisz tłumaczyć wszystkiego od nowa: jak działa tłumaczenie delta w CI

By Robert M

Nie musisz tłumaczyć wszystkiego od nowa: jak działa tłumaczenie delta w CI

Gdy masz już zautomatyzowane tłumaczenie podłączone do swojego pipeline CI, szybko pojawia się naturalne pytanie: czy za każdym razem, gdy ktoś wprowadza zmianę, cały plik lokalizacji jest tłumaczony od nowa?

Bez trybu delta, tak. Każde wypchnięcie, które dotyka pliku źródłowego lokalizacji, wysyła cały plik do API, każdy klucz, każdy ciąg znaków, niezależnie od tego, czy się zmienił, czy nie. Dla małego projektu na wczesnym etapie to w porządku. Dla dojrzałego projektu z setkami kluczy tłumaczeń w 10 lub 20 językach, marnujesz tokeny na ciągi, które nie zmieniły się od ostatniego uruchomienia, i otrzymujesz identyczny wynik w zamian.

Tłumaczenie delta rozwiązuje ten problem. Zamiast wysyłać cały plik, Action porównuje aktualny plik źródłowy z zapisaną linią bazową, identyfikuje tylko klucze, które zostały dodane lub zmodyfikowane, i wysyła tylko je do API. Wynik dla niezmienionych kluczy jest pobierany z istniejących przetłumaczonych plików. Zużycie tokenów spada, aby odpowiadać faktycznej wykonanej pracy.

Jak działa linia bazowa

Gdy tryb delta uruchamia się po raz pierwszy lub gdy wymusisz pełne odświeżenie, Action tłumaczy cały plik źródłowy i zapisuje jego spłaszczoną reprezentację JSON jako plik linii bazowej w twoim repozytorium. Przy kolejnych uruchomieniach Action ładuje tę linię bazową, porównuje ją z aktualnym plikiem źródłowym i buduje ładunek zawierający tylko zmienione klucze.

Dla plików lokalizacji JSON linia bazowa jest zapisywana jako .polylingo-baseline.json w katalogu wiadomości. Dla plików lokalizacji YAML jest to .polylingo-yaml-baseline.json w katalogu lokalizacji. Dla plików lang PHP Laravel jest to .polylingo-laravel-php-baseline.json w katalogu lang.

Linia bazowa jest zatwierdzana razem z przetłumaczonymi plikami, więc podróżuje razem z repozytorium. Każdy deweloper, który klonuje repo, otrzymuje tę samą linię bazową, na której pracuje pipeline.

Co liczy się jako zmiana

Diff działa na spłaszczonej reprezentacji kluczy twojego pliku źródłowego. Zagnieżdżone struktury są spłaszczane do kluczy w notacji kropkowej przed porównaniem:

{
  "nav.home": "Strona główna",
  "nav.about": "O nas",
  "hero.title": "Witamy na naszej platformie",
  "hero.cta": "Zacznij"
}

Klucz jest uwzględniany w ładunku delta, jeśli:

  • Istnieje w aktualnym pliku źródłowym, ale nie w linii bazowej (nowy klucz)
  • Istnieje w obu, ale wartość się zmieniła (zmodyfikowany klucz) Klucze, które istnieją w linii bazowej, ale nie w aktualnym pliku źródłowym (usunięte klucze), są automatycznie usuwane z przetłumaczonych plików wyjściowych. Klucze identyczne w obu są całkowicie pomijane, a ich istniejące tłumaczenia pozostają na miejscu.

Jak to wygląda w praktyce

Załóżmy, że masz projekt Next.js z 200 kluczami tłumaczeń w messages/en.json, już przetłumaczonymi na 12 języków. Deweloper aktualizuje tekst sekcji hero i dodaje dwa nowe klucze dla ogłoszenia funkcji. To 4 zmienione klucze na 200.

Bez trybu delta pipeline wysyła wszystkie 200 kluczy pomnożone przez 12 języków przy każdym pushu. Z trybem delta wysyła 4 klucze. Zużycie tokenów dla tego uruchomienia to około 2% kosztu pełnego tłumaczenia. Pipeline jest też szybszy, ponieważ jest mniej do wysłania i mniej do czekania.

W ciągu miesiąca regularnego rozwoju oszczędności kumulują się znacząco. Większość pushów dotyczy tylko kilku ciągów. Pełne ponowne tłumaczenie następuje tylko wtedy, gdy dodasz nowy język lub wyraźnie zresetujesz linię bazową.

Trzy PolyLingo GitHub Actions

Tryb delta jest dostępny we wszystkich trzech PolyLingo Actions do tłumaczeń. Każdy jest zbudowany dla konkretnego typu treści i struktury projektu.

translateAction — JSON i Markdown

Oryginalna Action. Obsługuje płaskie pliki lokalizacji JSON w stylu next-intl i i18next, z opcjonalnym przejściem dokumentacji Markdown przez asynchroniczne API zadań dla większych plików.

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

Linia bazowa delta: messages/.polylingo-baseline.json

github.com/UsePolyLingo/translateAction — Zobacz na Marketplace

translate-action-yaml — pliki lokalizacji YAML

Dla projektów używających zagnieżdżonych plików lokalizacji YAML: Rails i18n, Vue i18n i innych frameworków używających formatu YAML. Action automatycznie obsługuje konwencję Rails z kluczem root lokalizacji — en.yml ma klucz root en:, a każdy plik wyjściowy otrzymuje właściwy docelowy klucz lokalizacji (fr:, de: itd).

Ponieważ API PolyLingo działa natywnie z JSON, Action spłaszcza zagnieżdżony YAML do JSON w notacji kropkowej przed wysłaniem, tłumaczy, a następnie rekonstruuje zagnieżdżoną strukturę i zapisuje poprawny YAML. Jedna uwaga do wersji v1: klucze zawierające naturalnie kropki nie są obsługiwane, ponieważ kolidują z metodą spłaszczania notacji kropkowej.

- 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

Linia bazowa delta: config/locales/.polylingo-yaml-baseline.json

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

translate-action-laravel — pliki lang Laravel

Dla projektów Laravel używających plików tłumaczeń JSON (lang/en.json, obsługujących zarówno zagnieżdżone, jak i płaskie struktury w stylu Laravel 9+) lub plików lang tablic PHP (lang/en/*.php). Action automatycznie wykrywa, którego formatu używa twój projekt przez php_format: auto — najpierw sprawdza lang/en.json, a jeśli go nie ma, przechodzi do plików tablic PHP.

Dla plików PHP wywołuje CLI PHP, aby odczytać pliki źródłowe i serializuje przetłumaczony output z powrotem do poprawnej składni tablic PHP w JavaScript, bez dodatkowych zależności. GitHub-hostowane runner'y ubuntu-latest domyślnie zawierają PHP 8.x, więc nie jest potrzebny dodatkowy krok konfiguracji. Wymagane jest PHP 7.4 lub nowsze.

Jedna uwaga do wersji v1: klucze zawierające kropki nie są obsługiwane w trybie PHP z powodu strategii spłaszczania notacji kropkowej.

- 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

Linia bazowa delta: lang/.polylingo-laravel-json-baseline.json lub lang/.polylingo-laravel-php-baseline.json w zależności od formatu.

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

Tryb PR vs tryb commit

Wszystkie trzy Actions obsługują dwa tryby wyjścia.

Tryb commit (commit: true) zapisuje przetłumaczone pliki i commitują je bezpośrednio do bieżącej gałęzi. Prosta konfiguracja, dobra dla zespołów, które traktują tłumaczenie jako zautomatyzowany proces, który nie wymaga przeglądu.

Tryb PR (open_pr: true) tworzy nową gałąź (polylingo/yaml-<sha>, polylingo/laravel-<sha> itd.), zapisuje tam przetłumaczone pliki i otwiera pull request do twojej gałęzi bazowej. Lepszy dla zespołów, które chcą mieć etap przeglądu przez człowieka przed scaleniem przetłumaczonej zawartości, lub dla projektów, gdzie jakość tłumaczenia bezpośrednio wpływa na doświadczenie użytkownika.

Gdy oba są ustawione, tryb PR ma pierwszeństwo.

Tryb PR wymaga pull-requests: write w uprawnieniach workflow:

permissions:
  contents: write
  pull-requests: write

Wymuszanie pełnego odświeżenia

Tryb delta porównuje z zapisaną linią bazową. Jeśli chcesz przetłumaczyć wszystko od nowa niezależnie od tego, co pokazuje linia bazowa, ustaw delta: false. To także aktualizuje linię bazową, aby odpowiadała aktualnemu plikowi źródłowemu, więc kolejne uruchomienia delta zaczynają od nowego stanu.

Pełne odświeżenie jest przydatne, gdy dodajesz nowy język docelowy, gdy chcesz uwzględnić poprawki jakości tłumaczenia w nowej wersji modelu, lub gdy linia bazowa z jakiegoś powodu odbiega od rzeczywistości.

- 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  # pełne odświeżenie, aktualizuje linię bazową
    commit: true

Wyjścia dla kolejnych kroków

Wszystkie trzy Actions udostępniają te same wyjścia, abyś mógł ich używać w kolejnych krokach 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: Zaloguj statystyki tłumaczenia
  run: |
    echo "Przetłumaczone lokalizacje: ${{ steps.translate.outputs.locales_translated }}"
    echo "Zmodyfikowane pliki: ${{ steps.translate.outputs.files_changed }}"
    echo "Zużyte tokeny: ${{ steps.translate.outputs.tokens_used }}"

Każde uruchomienie zapisuje także tabelę podsumowującą do podsumowania kroku GitHub Actions, dzięki czemu możesz zobaczyć zużycie tokenów i wyniki tłumaczenia bez przeszukiwania logów.

Rozpoczęcie pracy

Wszystkie trzy Actions są dostępne na GitHub Marketplace. Będziesz potrzebować klucza API PolyLingo, dostępnego bezpłatnie na usepolylingo.com. Darmowy poziom obejmuje 50 000 tokenów miesięcznie. Z włączonym trybem delta większość projektów pozostanie znacznie poniżej tego limitu podczas rutynowych pushów deweloperskich.

Dodaj swój klucz API jako sekret repozytorium (POLYLINGO_API_KEY) i umieść odpowiednią Action w swoim workflow. Pierwsze uruchomienie wykonuje pełne tłumaczenie i ustawia linię bazową. Każde kolejne tłumaczy tylko to, co się zmieniło.