Automatizzare la localizzazione in CI/CD: guida per sviluppatori a Lara CLI

Tradotto con l’IA di Lara Translate

La maggior parte dei team di sviluppo automatizza build, test e deployment senza pensarci due volte. Poi arriva la localizzazione: le stringhe vengono esportate manualmente, inviate ai traduttori via e-mail, revisionate in un foglio di calcolo e reimportate giorni dopo. Quando i file tradotti tornano, il testo di origine è cambiato di nuovo.

Non si tratta di un problema di persone. È un problema di pipeline. E la soluzione è semplice: integrare la traduzione nello stesso flusso di lavoro automatizzato che già utilizzi per tutto il resto.

Lara CLI è l’interfaccia a riga di comando di Lara Translate. Si connette direttamente all’API di Lara Translate dal terminale o dal runner CI, consentendoti di avviare i lavori di traduzione a livello di programmazione, gestire le versioni della configurazione di localizzazione insieme al codice e distribuire sui mercati internazionali senza interrompere la cadenza di rilascio.

Perché la localizzazione manuale compromette il CI/CD

In genere, il ciclo di localizzazione manuale si svolge così: uno sviluppatore completa una funzionalità, esporta i file di stringhe aggiornati, li invia via e-mail o li carica per il team di localizzazione, attende la restituzione dei file tradotti, quindi li reimporta e li ridistribuisce. In un team che effettua rilasci più volte alla settimana, questo ciclo comporta un ritardo di 2–5 giorni per ogni rilascio. (I lavori di traduzione nelle varie lingue di destinazione possono essere eseguiti in parallelo, ma la pipeline rimane bloccata fino al completamento del ciclo.)

Gli effetti cumulativi sono peggiori del ritardo iniziale. Quando traduttori diversi gestiscono lotti diversi, si verificano discrepanze terminologiche. Le stringhe vengono duplicate perché non esiste una memoria di traduzione condivisa. Inoltre, quando si aggiunge una terza o quarta lingua di destinazione, il carico di lavoro non aumenta in modo lineare. Si moltiplica.

L’automazione della localizzazione nella pipeline CI/CD elimina tutti questi problemi. La traduzione viene eseguita a ogni push, riutilizza automaticamente le traduzioni precedentemente approvate e applica la terminologia tramite glossari, il tutto senza alcun intervento manuale.

Cos’è Lara CLI e a cosa serve?

Lara CLI è un’interfaccia a riga di comando che rende disponibili le funzionalità di traduzione di Lara Translate come comandi da terminale. Puoi utilizzarla localmente durante lo sviluppo o come fase in qualsiasi runner CI/CD.

Le funzionalità principali rilevanti per l’integrazione nella pipeline sono:

• Tradurre file di localizzazione dalla riga di comando e in CI/CD
• Utilizzare --context e --instructions per definire l’output (tono, registro, regole do-not-translate, vincoli dell’interfaccia utente)
• Allegare un glossario per garantire una terminologia coerente in ogni progetto
• Utilizzare le memorie di traduzione per riutilizzare automaticamente gli output precedentemente approvati
• Supporto di più formati di file i18n e rilevamento automatico del parser in base all’estensione del file

Tutto è gestito da un unico file di configurazione (lara.yaml) che risiede nel vostro repository. Nessuna dashboard a cui accedere, nessun file da caricare manualmente.

Installa Lara CLI in meno di un minuto

Lara CLI viene distribuito come pacchetto npm. Puoi utilizzare npm, pnpm o yarn, a seconda di quale strumento utilizzi già nel tuo progetto. Per un’installazione globale (consigliata per la maggior parte dei casi d’uso):

# npm
npm install -g @translated/lara-cli

# pnpm
pnpm install -g @translated/lara-cli

# yarn
yarn global add @translated/lara-cli

Per un’installazione locale nel progetto:

# npm
npm install --save-dev @translated/lara-cli
npx lara --version

# pnpm
pnpm install --save-dev @translated/lara-cli
npx lara --version

La guida completa alla configurazione è disponibile nella documentazione relativa alla configurazione e all’installazione di Lara CLI.

Configurazione as-code: il file lara.yaml

Lara CLI viene gestito da un file lara.yaml che si trova nella directory principale del repository. In questo file si definiscono le impostazioni linguistiche, i percorsi dei file, la memoria di traduzione, il glossario e le istruzioni a livello di progetto. L’intera configurazione della localizzazione è sottoposta a controllo di versione insieme al codice.

Ecco un esempio di configurazione completa:

# Schema version for backward compatibility
version: "1.0.0"

# Project-wide translation guidance
project:
  instruction: "B2B SaaS product. Technical UI strings for a developer audience. Keep placeholders and product names unchanged."

# Language configuration
locales:
  source: en
  target:
    - de
    - fr
    - es
    - ja

# Translation memory configuration
memories:
  - mem_your_tm_id

# Glossary configuration
glossaries:
  - gls_your_glossary_id

# File path and processing rules (format auto-detected by section)
files:
  json:
    include:
      - "src/locales/[locale].json"
  po:
    include:
      - "src/locales/[locale].po"

Alcuni aspetti di questa configurazione degni di nota:

• project.instruction — il controllo con la massima efficacia. Utilizzatelo per definire il pubblico, il tono, i vincoli dell’interfaccia utente e i termini non traducibili. Per impostazione predefinita, si applica a tutti i file.
• memories — riutilizza automaticamente le traduzioni precedentemente approvate, riducendo sia i costi che i tempi di consegna. Consulta la documentazione sulla memoria di traduzione.
• Glossari — collegano coppie di termini predefinite in modo che i nomi dei prodotti, le etichette delle funzionalità e i termini dei marchi rimangano coerenti in ogni progetto. Scopri come funzionano i glossari in Lara Translate.
• File: puoi includere più formati in un unico progetto. Lara CLI seleziona il parser corretto in base all’estensione del file e alla sezione del formato che configuri.

Poiché questo file viene committato su Git, tutti i membri del team lavorano con le stesse impostazioni, le modifiche alla configurazione sono tracciabili nelle pull request e l’onboarding di un nuovo progetto consiste semplicemente nel clonare il repository.

Come impostare le credenziali in modo sicuro (in locale e in CI)

In locale, Lara CLI può leggere le credenziali da un file .env nella directory del progetto:

LARA_ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
LARA_ACCESS_KEY_SECRET=<YOUR_ACCESS_KEY_SECRET>

In CI, è necessario passare queste credenziali come segreti o variabili protette; non vanno mai hardcoded in lara.yaml né committate su git.

Vedi: Configurazione e installazione di Lara CLI e Configurazione della chiave API.

Come eseguire un job di traduzione

Una volta configurato il file lara.yaml, per eseguire un job di traduzione del progetto è sufficiente un unico comando:

lara-cli translate

Lara CLI legge il file lara.yaml, chiama l’API di Lara Translate e scrive i file tradotti in base ai pattern di inclusione configurati. La struttura originale viene mantenuta. Non è necessaria alcuna gestione manuale dei file.

Se desiderate una traduzione ad hoc dalla riga di comando (testo o singolo file), potete anche utilizzare il comando translate con opzioni:

lara translate --text "Hello, world!" --source en-US --target fr-FR

Consulta tutti i comandi disponibili nella guida di riferimento ai comandi di Lara CLI.

Come integrare Lara CLI in GitHub Actions

Il vero vantaggio di Lara CLI risiede nell’integrazione nella pipeline. Ecco un workflow completo di GitHub Actions che esegue automaticamente la traduzione ogni volta che vengono effettuate modifiche ai file delle localizzazioni di origine:

name: Localization

on:
  push:
    paths:
      - 'src/locales/en.json'
      - 'src/locales/en.po'

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Lara CLI
        run: npm install -g @translated/lara-cli

      - name: Run translation
        run: lara-cli translate
        env:
          LARA_ACCESS_KEY_ID: ${{ secrets.LARA_ACCESS_KEY_ID }}
          LARA_ACCESS_KEY_SECRET: ${{ secrets.LARA_ACCESS_KEY_SECRET }}

      - name: Commit translated files
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add src/locales/
          git commit -m "chore: auto-translate strings [skip ci]" || echo "No changes"
          git push

Alcune note su questo workflow:

• Il filtro paths garantisce che il job di traduzione venga eseguito solo quando le stringhe di origine cambiano effettivamente, e non a ogni push.
• Memorizza le credenziali come segreti di GitHub Actions (ad esempio LARA_ACCESS_KEY_ID e LARA_ACCESS_KEY_SECRET) in Settings > Secrets and variables > Actions.
• Il passaggio di commit utilizza || echo "No changes" in modo che il workflow non abbia esito negativo quando la memoria di traduzione copre già tutte le stringhe e non vi sono nuove stringhe da committare.
• Il tag [skip ci] impedisce che l’auto-commit attivi un’ulteriore esecuzione del workflow.
• Alternativa: aprire una pull request anziché eseguire direttamente il commit. Alcuni team preferiscono che i file tradotti vengano inseriti in una PR separata, in modo da poter esaminare e approvare ciò che viene unito prima che raggiunga il branch principale. A tal fine, sostituire la fase di commit con una chiamata gh pr create o utilizzare un’azione della community come peter-evans/create-pull-request. Il comando di traduzione rimane identico: cambia solo la fase di consegna.

Per GitLab CI, si applica la stessa logica: installare la CLI, autenticarsi tramite variabili di ambiente ed eseguire il comando lara-cli translate in un job che si attiva in caso di modifiche ai file delle localizzazioni.

Equivalente GitLab CI

translate:
  stage: localize
  image: node:20
  only:
    changes:
      - src/locales/en.json
      - src/locales/en.po
  script:
    - npm install -g @translated/lara-cli
    - lara-cli translate
  variables:
    LARA_ACCESS_KEY_ID: $LARA_ACCESS_KEY_ID
    LARA_ACCESS_KEY_SECRET: $LARA_ACCESS_KEY_SECRET
  artifacts:
    paths:
      - src/locales/

L’esempio precedente utilizza npm. Puoi sostituire con pnpm (pnpm install -g @translated/lara-cli) o yarn (yarn global add @translated/lara-cli) se il tuo progetto utilizza questi strumenti.

Formati di file supportati per le pipeline di localizzazione

Lara CLI supporta diversi formati di file per l’internazionalizzazione e seleziona automaticamente il parser corretto in base all’estensione del file. La tabella seguente elenca i formati esplicitamente documentati per Lara CLI:

Per l’elenco ufficiale dei comandi CLI e per capire come funziona il rilevamento del formato, consulta Introduzione a Lara CLI.

In che modo la memoria di traduzione e i glossari riducono il lavoro manuale

Due funzionalità rendono la localizzazione automatizzata non solo veloce, ma anche affidabile su larga scala.

La memoria di traduzione memorizza ogni segmento di traduzione approvato. Quando Lara CLI elabora un progetto, può riutilizzare automaticamente le traduzioni precedentemente approvate. Se ti è mai capitato di dover tradurre lo stesso messaggio di errore o la stessa etichetta dell’interfaccia utente in più release, la memoria di traduzione elimina completamente questa necessità. Paghi per tradurre una stringa una sola volta e in ogni lavoro futuro viene riutilizzato il risultato approvato. Inoltre, garantisce che le formulazioni approvate non vengano mai modificate senza l’intervento umano. Scopri come funzionano le memorie di traduzione nell’API.

I glossari impongono l’uso di coppie di termini obbligatorie in ogni lavoro di traduzione. Senza un glossario, lo stesso termine tecnico potrebbe essere tradotto in tre modi diversi in tre release differenti. Definisci ciascun termine una sola volta nel glossario, lo associ alla configurazione del tuo progetto e ogni lavoro lo rispetta, indipendentemente dal numero di lingue in cui pubblichi. Scopri come configurare e gestire i glossari.

Insieme, queste due funzionalità fanno sì che, man mano che la pipeline matura, la percentuale di stringhe che richiedono una revisione umana si riduca costantemente. Il modello gestisce le nuove stringhe. La memoria gestisce tutto ciò che è già stato approvato.

Sicurezza e protezione dei dati nelle pipeline CI/CD automatizzate

Spesso, le pipeline di traduzione automatizzate gestiscono contenuti di origine non ancora pubblici: nomi di funzionalità non ancora rilasciati, stringhe di strumenti interni, bozze di documentazione, testi proprietari. Una delle preoccupazioni più comuni quando si adotta la traduzione basata sull’IA è se tali contenuti finiscano in un set di dati di addestramento pubblico. Lara Translate è progettato proprio per evitare che ciò accada.

• Tutte le operazioni di elaborazione e archiviazione avvengono all’interno dell’UE. Lara Translate è pienamente conforme al GDPR.
• La modalità Incognito disabilita l’apprendimento dal vostro contenuto, pertanto nulla di ciò che viene elaborato nella vostra pipeline viene utilizzato per migliorare il modello.
• Le credenziali devono essere sempre passate come segreti o variabili protette e mai hardcoded nei file di configurazione sottoposti a controllo di versione.
• Per i team aziendali, le sedi di trattamento dei dati e i subincaricati sono completamente documentati.

Perché la localizzazione automatizzata è importante per i team di sviluppo

La localizzazione è l’ultimo collo di bottiglia manuale nelle pipeline di rilascio altrimenti automatizzate, e ogni giorno in cui rimane manuale è un giorno in cui gli utenti internazionali devono attendere più a lungo per ricevere gli aggiornamenti. Lara CLI trasforma la traduzione in una fase della pipeline ripetibile e controllata dal versioning, che viene eseguita a ogni push, proprio come avviene per il linting o il testing. Per i team che effettuano il rilascio in più mercati, questa non è una funzionalità di comodità. È un prerequisito per una velocità di rilascio sostenibile.

Il vantaggio secondario è la coerenza della qualità. La traduzione con intervento umano è ancora preziosa per i contenuti ad alto rischio, ma per le stringhe dell’interfaccia utente, i messaggi di errore e la documentazione, la traduzione automatizzata supportata da glossari e memoria di traduzione può offrire prestazioni superiori rispetto ai flussi di lavoro manuali ad hoc. Quando è necessaria un’ulteriore verifica, è disponibile la revisione umana in aggiunta alla traduzione AI.

Siete pronti a eliminare il collo di bottiglia della localizzazione dalla vostra pipeline? Installa Lara CLI, aggiungi il tuo lara.yaml al tuo repository e il tuo prossimo push verrà rilasciato con le traduzioni già pronte. La guida rapida ti illustra l’installazione e il tuo primo progetto.

Domande frequenti

Lara CLI funziona con qualsiasi piattaforma CI/CD?
Sì. Lara CLI funziona in qualsiasi ambiente in cui sia installato Node.js. Funziona con GitHub Actions, GitLab CI, CircleCI, Bitbucket Pipelines, Jenkins e qualsiasi altro runner. Gli esempi in questo articolo utilizzano GitHub Actions e GitLab CI, ma i comandi sono identici indipendentemente dalla piattaforma.

Quali formati di file supporta Lara CLI?
Lara CLI supporta diversi formati di internazionalizzazione e rileva automaticamente il parser in base all’estensione del file: JSON, PO, TS, componenti i18n a file singolo per Vue, Markdown/MDX e Android XML. Consultare Introduzione a Lara CLI per l’elenco aggiornato.

Come posso proteggere le mie credenziali in una pipeline CI?
Passa le tue credenziali come segreti di ambiente e non le hardcode mai in lara.yaml. In GitHub Actions, memorizza LARA_ACCESS_KEY_ID e LARA_ACCESS_KEY_SECRET in Settings > Secrets and variables > Actions. In GitLab CI, utilizzate le variabili CI/CD protette.

I miei contenuti di origine verranno utilizzati per addestrare il modello?
No, se abiliti la Modalità Incognito. Con la Modalità Incognito attiva, Lara Translate non apprende dal vostro contenuto. Questa è l’impostazione consigliata per le pipeline che elaborano stringhe non rilasciate o proprietarie.

Posso comunque richiedere la revisione umana per contenuti ad alto rischio?
Sì. Lara Translate supporta la revisione umana in aggiunta alla traduzione AI. È possibile automatizzare la prima fase e indirizzare file o lingue specifici a un revisore umano quando il contenuto lo richiede.

La CLI supporta più lingue di destinazione in un unico job?
Sì. Definisci più locali di destinazione in lara.yaml sotto locales.target e potranno essere elaborati in un’unica esecuzione di Lara CLI. Ciò fa parte del supporto per la traduzione multilingue di Lara Translate.

Come posso controllare il tono e il comportamento della traduzione dalla CLI?
Utilizza le istruzioni a livello di progetto in lara.yaml (project.instruction) e, se necessario, aggiungi istruzioni a livello di file e di chiave. Per le traduzioni ad hoc, utilizzare i flag --context e --instructions. Consulta Panoramica della configurazione e Comandi.

Questo articolo tratta di:

Come automatizzare la localizzazione in una pipeline CI/CD utilizzando Lara CLI, l’interfaccia a riga di comando di Lara Translate. Tratta l’installazione, il file di configurazione lara.yaml, le credenziali e i segreti CI, un workflow completo per GitHub Actions, l’equivalente per GitLab CI, i formati di file supportati dalla CLI, l’integrazione della memoria di traduzione e del glossario, le impostazioni di sicurezza dei dati e le risposte alle domande più frequenti dei sviluppatori sull’automazione dell’i18n in pipeline CI/CD.

Risorse correlate di Lara Translate:

• Lara CLI: Introduzione e avvio rapido
• Lara CLI: configurazione e installazione
• Panoramica della configurazione
• Riferimento ai comandi CLI
• Funzionamento dei glossari in Lara Translate
• Memorie di traduzione nell’API
• Modalità di apprendimento vs. modalità Incognito
• Configurazione della chiave API
• Revisione umana in aggiunta alla traduzione AI
• Conformità al GDPR