← Torna al 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.

Non è necessario tradurre tutto di nuovo: come funziona la traduzione delta in CI

By Robert M

Non è necessario ritrasmettere tutto: come funziona la traduzione delta in CI

Una volta che hai integrato la traduzione automatica nella tua pipeline CI, sorge rapidamente una domanda naturale: viene ritrasmesso l'intero file locale ogni volta che qualcuno effettua una modifica?

Senza la modalità delta, sì. Ogni push che tocca il file locale sorgente invia tutto al'API, ogni chiave, ogni stringa, che sia cambiata o meno. Per un progetto piccolo all'inizio va bene. Per un progetto maturo con centinaia di chiavi di traduzione in 10 o 20 lingue, stai consumando token su stringhe che non sono cambiate dall'ultima esecuzione e ricevendo in cambio output identici.

La traduzione delta risolve questo problema. Invece di inviare il file completo, l'Action confronta il file sorgente attuale con una baseline memorizzata, identifica solo le chiavi aggiunte o modificate e invia solo quelle all'API. L'output per le chiavi non modificate viene preso dai file tradotti esistenti. L'uso dei token diminuisce per corrispondere al lavoro effettivamente svolto.

Come funziona la baseline

Quando la modalità delta viene eseguita per la prima volta, o quando forzi un aggiornamento completo, l'Action traduce il file sorgente completo e memorizza una rappresentazione JSON piatta come file baseline nel tuo repository. Alle esecuzioni successive, l'Action carica quella baseline, la confronta con il file sorgente attuale e costruisce un payload contenente solo le chiavi modificate.

Per i file locale JSON la baseline è memorizzata come .polylingo-baseline.json nella tua directory dei messaggi. Per i file locale YAML è .polylingo-yaml-baseline.json nella directory dei locali. Per i file lang PHP Laravel è .polylingo-laravel-php-baseline.json nella directory lang.

La baseline viene committata insieme ai file tradotti così viaggia con il repository. Qualsiasi sviluppatore che clona il repo ottiene la stessa baseline da cui lavora la pipeline.

Cosa conta come modifica

Il diff opera sulla rappresentazione piatta delle chiavi del file sorgente. Le strutture annidate vengono appiattite in chiavi con notazione a punti prima del confronto:

{
  "nav.home": "Home",
  "nav.about": "Chi siamo",
  "hero.title": "Benvenuto sulla nostra piattaforma",
  "hero.cta": "Inizia"
}

Una chiave è inclusa nel payload delta se:

  • Esiste nel file sorgente attuale ma non nella baseline (chiave nuova)
  • Esiste in entrambi ma il valore è cambiato (chiave modificata) Le chiavi che esistono nella baseline ma non nel file sorgente attuale (chiavi eliminate) vengono rimosse automaticamente dai file di output tradotti. Le chiavi identiche in entrambi vengono saltate completamente e le traduzioni esistenti rimangono al loro posto.

Come appare nella pratica

Supponiamo che tu abbia un progetto Next.js con 200 chiavi di traduzione in messages/en.json, già tradotte in 12 lingue. Uno sviluppatore aggiorna il testo della sezione hero e aggiunge due nuove chiavi per un annuncio di funzionalità. Sono 4 chiavi modificate su 200.

Senza la modalità delta, la pipeline invia tutte le 200 chiavi moltiplicate per 12 lingue ad ogni push. Con la modalità delta invia 4 chiavi. L'uso dei token per quella esecuzione è circa il 2% di quanto costerebbe una traduzione completa. La pipeline è anche più veloce perché c'è meno da inviare e meno da aspettare.

In un mese di sviluppo regolare, il risparmio si accumula significativamente. La maggior parte dei push tocca solo poche stringhe. La ritrasmissione completa avviene solo quando aggiungi una nuova lingua o resetti esplicitamente la baseline.

I tre PolyLingo GitHub Actions

La modalità delta è disponibile in tutti e tre i PolyLingo translation Actions. Ognuno è costruito per un tipo specifico di contenuto e struttura di progetto.

translateAction — JSON e Markdown

L'Action originale. Gestisce file locale JSON piatti nello stile next-intl e i18next, con un passaggio opzionale di documentazione Markdown tramite l'API async jobs per file più grandi.

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

Baseline delta: messages/.polylingo-baseline.json

github.com/UsePolyLingo/translateAction — Visualizza su Marketplace

translate-action-yaml — File locale YAML

Per progetti che usano file locale YAML annidati: Rails i18n, Vue i18n e qualsiasi altro framework che usa il formato YAML. L'Action gestisce automaticamente la convenzione Rails di una chiave locale root — en.yml ha una chiave root en:, e ogni file di output ottiene la corretta chiave locale di destinazione (fr:, de: ecc).

Poiché l'API PolyLingo funziona nativamente con JSON, l'Action appiattisce YAML annidato in JSON con notazione a punti prima di inviare, traduce, poi ricostruisce la struttura annidata e scrive output YAML valido. Una nota v1 da sapere: le chiavi che contengono punti naturalmente non sono supportate, poiché confliggono con l'appiattimento a notazione a punti.

- 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

Baseline delta: config/locales/.polylingo-yaml-baseline.json

github.com/UsePolyLingo/translate-action-yaml — Visualizza su Marketplace

translate-action-laravel — File lang Laravel

Per progetti Laravel che usano file di traduzione JSON (lang/en.json, supportando sia strutture annidate che piatte nello stile Laravel 9+) o file lang array PHP (lang/en/*.php). L'Action rileva automaticamente quale formato usa il tuo progetto tramite php_format: auto — controlla prima lang/en.json e ricade sui file array PHP se non trovato.

Per i file PHP esegue il CLI PHP per leggere i file sorgente e serializza l'output tradotto di nuovo in sintassi array PHP valida in JavaScript, senza dipendenze aggiuntive. I runner ubuntu-latest ospitati da GitHub includono PHP 8.x di default quindi non serve configurazione extra. È richiesto PHP 7.4 o superiore.

Una nota v1: le chiavi contenenti punti non sono supportate in modalità PHP a causa della strategia di appiattimento a notazione a punti.

- 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

Baseline delta: lang/.polylingo-laravel-json-baseline.json o lang/.polylingo-laravel-php-baseline.json a seconda del formato.

github.com/UsePolyLingo/translate-action-laravel — Visualizza su Marketplace

Modalità PR vs modalità commit

Tutti e tre gli Actions supportano due modalità di output.

Modalità Commit (commit: true) scrive i file tradotti e li committa direttamente nel branch corrente. Configurazione semplice, buona per team che trattano la traduzione come un processo automatizzato che non necessita di revisione.

Modalità PR (open_pr: true) crea un nuovo branch (polylingo/yaml-<sha>, polylingo/laravel-<sha> ecc), scrive i file tradotti lì e apre una pull request verso il branch base. Meglio per team che vogliono un passaggio di revisione umana prima che il contenuto tradotto venga unito, o per progetti dove la qualità della traduzione influisce direttamente sull'esperienza utente.

Quando entrambi sono impostati, la modalità PR ha la precedenza.

La modalità PR richiede pull-requests: write nei permessi del workflow:

permissions:
  contents: write
  pull-requests: write

Forzare un aggiornamento completo

La modalità delta confronta con la baseline memorizzata. Se vuoi ritrasmettere tutto indipendentemente da cosa mostra la baseline, imposta delta: false. Questo aggiorna anche la baseline per corrispondere al file sorgente attuale, così le esecuzioni delta successive partono dal nuovo stato.

Un aggiornamento completo è utile quando aggiungi una nuova lingua target, quando vuoi acquisire miglioramenti di qualità della traduzione in una nuova versione del modello, o quando la baseline si è discostata dalla realtà per qualsiasi motivo.

- 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  # aggiornamento completo, aggiorna baseline
    commit: true

Output per i passaggi downstream

Tutti e tre gli Actions espongono gli stessi output così puoi usarli nei passaggi successivi del 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 delle statistiche di traduzione
  run: |
    echo "Lingue tradotte: ${{ steps.translate.outputs.locales_translated }}"
    echo "File modificati: ${{ steps.translate.outputs.files_changed }}"
    echo "Token usati: ${{ steps.translate.outputs.tokens_used }}"

Ogni esecuzione scrive anche una tabella riepilogativa nel sommario del passaggio GitHub Actions così puoi vedere l'uso dei token e i risultati della traduzione senza dover cercare nei log.

Iniziare

Tutti e tre gli Actions sono disponibili su GitHub Marketplace. Avrai bisogno di una chiave API PolyLingo, disponibile gratuitamente su usepolylingo.com. Il piano gratuito include 50.000 token al mese. Con la modalità delta abilitata, la maggior parte dei progetti rimarrà ben entro questo limite durante i push di sviluppo di routine.

Aggiungi la tua chiave API come secret del repository (POLYLINGO_API_KEY) e inserisci l'Action rilevante nel tuo workflow. La prima esecuzione fa una traduzione completa e imposta la baseline. Ogni esecuzione successiva traduce solo ciò che è cambiato.