Tradotto con l’IA di Lara Translate
Ti occupi della localizzazione per tanti clienti o prodotti. Il developer rilascia una nuova build. Qualcuno esporta i file delle stringhe aggiornati. Ti arrivano nella casella di posta. Apri un ticket, assegni un linguista, aspetti che ti restituiscano i file, controlli la terminologia e li mandi agli sviluppatori perché li reimportino. Tre giorni dopo, il testo di partenza è già cambiato. Ricomincia da capo.
Non è un problema di flusso di lavoro che puoi risolvere assumendo più in fretta. È un problema strutturale: la localizzazione è fuori dal processo di build, quindi rimane sempre indietro. Con Lara CLI, la rimetti dentro. La traduzione viene eseguita automaticamente a ogni push, rispettando i tuoi glossari e le tue memorie di traduzione, e i file tradotti vengono committati di nuovo nel repository senza che nessuno li tocchi. Ecco come funziona e cosa puoi configurare per mantenere la qualità su larga scala.
|
TL;DR
|
Risposta breve
Lara CLI è un’interfaccia a riga di comando che integra Lara Translate direttamente nel processo di build dello sviluppo. La usi per automatizzare le traduzioni, applicare i glossari e le memorie di traduzione e mantenere i file localizzati sincronizzati con il codice sorgente, senza doverli passare a mano a ogni rilascio.
Perché è importante: se la localizzazione non fa parte della pipeline di build, a ogni rilascio si crea un collo di bottiglia. Esporti i file a mano, li controlli separatamente e poi li reimporti. La terminologia cambia. Si dimenticano delle stringhe. Quando aggiungi una nuova lingua di destinazione, il carico di lavoro non si riduce, ma aumenta. Lara CLI elimina completamente il lavoro manuale e ti dà le opzioni di configurazione che ti servono per mantenere alta la qualità senza dover seguire ogni singolo lavoro.
Cos’è Lara CLI e cosa fa
Lara CLI è un’interfaccia a riga di comando per Lara Translate, distribuita come pacchetto npm. La puoi eseguire dal terminale o da un runner CI/CD e si connette direttamente all’API di Lara Translate per tradurre i file di localizzazione in modo programmatico. Lo strumento riconosce automaticamente il formato del file dall’estensione e supporta JSON, PO, TypeScript, componenti single-file Vue i18n, Markdown/MDX e Android XML.
Tutta la configurazione del progetto sta in un unico file: lara.yaml. Lo carichi nel repository insieme al codice sorgente, così ogni modifica alla configurazione viene tracciata, tutti i membri del team lavorano con le stesse impostazioni e non c’è una dashboard di localizzazione separata da gestire o a cui accedere. Per un localization manager, questo è il cambiamento più importante: le tue regole terminologiche, le tue istruzioni sul tono, l’ambito dei file: li definisci una volta sola e vengono applicati automaticamente a ogni esecuzione.
La configurazione di lara.yaml: cosa controlli tu
Il file lara.yaml ha una struttura gerarchica chiara. Se la capisci, puoi sfruttarla al massimo come localization manager. Le impostazioni si applicano a cascata dal livello del progetto fino alle singole chiavi e quelle più specifiche hanno sempre la priorità su quelle più generiche.
Per il controllo qualità, le tre sezioni più importanti sono project.instruction, memories e glossaries.
project.instruction è dove definisci il contesto generale per ogni lavoro di traduzione di questo progetto: pubblico, settore, tono, registro e regole per ciò che non va tradotto. Si applica a tutti i file, a meno che non venga sovrascritta. Pensala come al brief che daresti a un traduttore all’inizio di un incarico: lo scrivi una volta e si applica automaticamente a ogni traduzione.
memories collega uno o più ID di Translation Memory del tuo account Lara. Le traduzioni approvate vengono riutilizzate automaticamente. È qui che la coerenza fa la differenza: più lavori esegui, più la tua TM si arricchisce e meno traduzioni nuove servono a ogni nuova versione.
glossaries collega uno o più ID di glossario. In ogni lavoro, i nomi dei prodotti, le etichette delle funzionalità, i termini del brand e il vocabolario specifico del settore vengono applicati senza che tu debba controllarli manualmente. Definisci i termini una volta sola su Lara Translate, indichi l’ID del glossario in lara.yaml, e vengono applicati a tutti i file in ogni esecuzione.
Ereditarietà delle istruzioni: livello progetto, file e chiave
Questa è la funzionalità più utile se sei un localization manager o un LSP che gestisce tanti tipi di contenuti. Nel file di configurazione lara.yaml ci sono tre livelli di istruzioni e ogni livello ha la priorità su quello superiore.
Le istruzioni a livello di progetto si applicano a tutto il progetto. Le istruzioni a livello di file si applicano a un percorso specifico e hanno la priorità sull’impostazione del progetto per quel file. Le istruzioni a livello di chiave si applicano a chiavi specifiche all’interno di un file e hanno la priorità su entrambi i livelli. Ecco come appare una configurazione reale che usa tutti e tre i livelli:
In questo esempio, l’app medica usa il tono formale in tutto il testo. Il file di onboarding lo sovrascrive con un tono più informale, perché il pubblico e il contesto sono diversi. Le chiavi dei pulsanti nel file di onboarding ricevono in più un limite di caratteri. In tutti i file, le chiavi dei messaggi di errore tornano al tono formale, indipendentemente dall’impostazione del file principale.
Se gestisci più clienti in un unico repository o in configurazioni diverse, con questo modello di ereditarietà non ti servono pipeline separate per i vari tipi di contenuto. Un solo lara.yaml è sufficiente per esprimere tutti i tuoi requisiti di qualità, anche i più complessi.
Proteggi le chiavi che non vanno tradotte
Nella sezione files ci sono due impostazioni che ti danno il controllo diretto su quali chiavi la CLI modifica.
lockedKeys protegge le chiavi che hanno già una traduzione dalla sovrascrittura. Nelle esecuzioni successive la CLI le salta, il che è utile per le stringhe che hai controllato e approvato manualmente, o per le chiavi che contengono valori non traducibili come ID, URL o stringhe di configurazione.
ignoredKeys esclude del tutto le chiavi dal lavoro di traduzione. La CLI le salta, lascia intatti i file per quelle chiavi e non le conta nel conteggio dei caratteri. Usala per le chiavi interne, per le stringhe solo per lo sviluppo o per qualsiasi contenuto che non deve mai passare per la traduzione automatica.
Come eseguire un lavoro di traduzione
Una volta che hai configurato lara.yaml, per tradurre ti basta una sola riga:
La CLI legge lara.yaml, chiama l’API di Lara Translate e scrive i file tradotti in base ai pattern di inclusione configurati. La struttura originale dei file viene mantenuta. Puoi anche eseguire traduzioni ad hoc dalla riga di comando per singoli file o stringhe di testo usando i flag:
I flag --memory e --glossary nel comando ad hoc accettano gli stessi ID che usi in lara.yaml, così hai a disposizione le tue risorse terminologiche sia che esegui lavori automatizzati sia che fai traduzioni una tantum dal terminale.
Gestire le memorie di traduzione dalla CLI
Lara CLI include tutti i comandi per gestire le memorie di traduzione. Puoi elencarle, crearle, aggiornarle ed eliminarle direttamente dal terminale, e puoi importare file TMX in una memoria esistente:
Se sei un LSP e vuoi trasferire le tue TM esistenti in Lara Translate, il comando di importazione TMX supporta il formato di consegna più comune. Dopo l’importazione, puoi usare l’ID della memoria in qualsiasi configurazione lara.yaml nei tuoi progetti per i clienti.
Automatizzare con GitHub Actions
Con l’integrazione con GitHub Actions, il cerchio si chiude. Invece di dover eseguire manualmente lara-cli translate dopo ogni push degli sviluppatori, il workflow lo fa automaticamente e commita i file tradotti nel repository.
Per configurare tutto, ti servono tre cose: le credenziali API di Lara salvate come GitHub Secrets (LARA_ACCESS_KEY_ID e LARA_ACCESS_KEY_SECRET), i permessi di scrittura abilitati per il workflow, e un file lara.yaml già presente nel repository (generato localmente con lara-cli init e pushato). Poi crei un file di workflow in .github/workflows/translate.yml:
Una volta fatto questo, a ogni push su main viene eseguita una traduzione. I file aggiornati vengono committati automaticamente. Non devi esportare, inviare via email, reimportare o controllare la consegna dei file. Il tuo ruolo di localization manager non è più gestire le consegne, ma la configurazione: definisci le istruzioni, aggiorni i glossari, controlli la qualità della TM e decidi quali chiavi bloccare o ignorare. È proprio qui che conta davvero la tua esperienza nella localizzazione.
Come iniziare
Ti servono Node.js 16 o versioni successive e pnpm. Installa Lara CLI a livello globale:
Crea un file .env nella cartella del tuo progetto con le tue credenziali API di Lara:
Poi esegui l’inizializzazione interattiva per generare il tuo lara.yaml:
Il comando init rileva le tue cartelle di localizzazione e ti guida nella configurazione. Se conosci già gli ID delle tue risorse, puoi eseguirlo anche con --non-interactive e passare direttamente i glossari e le memorie come flag. Carica il file lara.yaml generato nel tuo repository. Da lì, esegui lara-cli translate in locale o configura il workflow GitHub Actions per automatizzare tutte le esecuzioni successive.
La configurazione della chiave API, l’elenco completo dei comandi e i dettagli della configurazione sono nella documentazione di Lara CLI.
Automatizza il tuo flusso di lavoro di localizzazione con Lara CLI
Integra Lara Translate direttamente nella tua pipeline di build. Definisci le tue regole di qualità una volta sola in lara.yaml e lascia che la CLI si occupi di ogni esecuzione.
Grazie per aver letto 💜
Come ringraziamento, ecco un coupon speciale solo per te: IREADLARA26.
Riscattalo e ottieni il 10% di sconto su Lara PRO per 6 mesi.
Se hai già un account Lara, accedi qui per applicare il tuo coupon. Se non usi ancora Lara Translate, iscriviti qui e attiva il tuo sconto.
Domande frequenti
Devo per forza essere uno sviluppatore per usare Lara CLI?
Ti servono Node.js e pnpm installati e un po’ di pratica nell’eseguire comandi da terminale. Configurarlo è semplice: installi il pacchetto, aggiungi le credenziali a un file .env ed esegui lara-cli init per generare la configurazione. La maggior parte del lavoro di configurazione, cioè definire le istruzioni, collegare i glossari e le memorie di traduzione e decidere quali file includere, è di natura editoriale e linguistica, più che tecnica. Se lavori come localization manager insieme a un team di sviluppo, di solito gli sviluppatori si occupano dell’integrazione CI/CD e tu ti occupi del contenuto della configurazione di lara.yaml.
Quali formati di file supporta Lara CLI?
Lara CLI supporta JSON, PO (gettext), TypeScript, componenti single-file Vue i18n, Markdown/MDX e Android XML. Il formato viene riconosciuto automaticamente in base all’estensione del file, quindi non devi indicarlo a mano. Puoi includere più formati in un unico lara.yaml aggiungendo sezioni per i diversi formati sotto la chiave files. Trovi la documentazione completa sui formati, con guide specifiche per ciascuno, nella documentazione di Lara CLI.
Posso usare più glossari e memorie di traduzione in un unico progetto?
Sì. Nelle sezioni glossaries e memories di lara.yaml puoi inserire degli elenchi, quindi puoi indicare più ID per ciascuna. Durante il lavoro di traduzione vengono applicati tutti i glossari collegati. Se sei un LSP e gestisci più clienti con risorse terminologiche diverse, puoi tenere su Lara Translate glossari specifici per ogni cliente e indicare quelli giusti nella configurazione di ogni progetto. Se fai traduzioni ad hoc dalla riga di comando, puoi anche passare direttamente gli ID dei glossari e delle memorie come flag, senza dover modificare il lara.yaml.
Qual è la differenza tra lockedKeys e ignoredKeys?
lockedKeys fa in modo che le chiavi che hanno già una traduzione non vengano sovrascritte. Nelle esecuzioni successive la CLI le salta, il che è utile per le stringhe che hai controllato e approvato manualmente. ignoredKeys esclude invece le chiavi del tutto dal lavoro, quindi non vengono mai inviate all’API e non compaiono nell’output. Usa lockedKeys per le traduzioni approvate che vuoi mantenere. Usa ignoredKeys per le stringhe interne, le chiavi placeholder o qualsiasi cosa non debba mai essere tradotta.
La CLI è gratuita?
Puoi installare e usare lo strumento CLI gratuitamente. Quando la usi, le traduzioni vengono elaborate con il tuo abbonamento standard all’API di Lara Translate o con la tua quota pay-as-you-go. Non paghi niente in più per usare la CLI. Per autenticarti ti serve un account Lara con le credenziali API. Puoi generarle dalla sezione API della dashboard del tuo account Lara.
In questo articolo parliamo di
- Cos’è Lara CLI e perché è importante soprattutto per i localization manager e gli LSP, non solo per gli sviluppatori
- La configurazione di lara.yaml e il sistema di ereditarietà delle istruzioni a tre livelli (progetto, file, chiave) che ti permette di controllare la qualità senza revisioni manuali per ogni lavoro
- Glossari, memorie di traduzione, lockedKeys e ignoredKeys come strumenti principali per controllare la qualità dell’output su larga scala
- Comandi per la gestione della memoria di traduzione, tra cui l’importazione di file TMX per migrare le risorse esistenti
- Integrazione con GitHub Actions con la configurazione completa del workflow per la traduzione e il commit automatici a ogni push
- Come iniziare: installazione, credenziali, init e prima esecuzione
Hai uno strumento, una risorsa o un’idea utile che potrebbe migliorare uno dei nostri articoli? Inviaci il tuo suggerimento
Saremo felici di dargli un’occhiata e di valutare se pubblicarlo, così da arricchire i contenuti per i nostri lettori! ✍️
Articoli utili
- Introduzione a Lara CLI: documentazione completa
- Panoramica della configurazione di Lara CLI
- Guida all’integrazione con GitHub Actions
- Come funzionano i glossari in Lara Translate
