Tradurre
Come tradurre il tuo progetto
Utilizzo
Eseguilo nella pipeline CI prima di eseguire la build della tua app per la produzione.
npx gtx-cli translateNota: Questo comando richiede una chiave API di produzione. Richiedine una sulla piattaforma.
Panoramica
Il comando gtx-cli translate traduce il tuo progetto.
Scorre l’albero dei file del progetto e traduce qualsiasi contenuto racchiuso in un componente <T>
o che utilizza le funzioni useGT.
Inoltre, include il contenuto dal file di dizionario (se presente).
Questo comando è il metodo principale per usare la General Translation API e i servizi correlati.
Solo per l’uso in produzione!
Questo comando è pensato per le build di produzione e non va usato in sviluppo.
Prima di eseguirlo, assicurati di trovarti sul branch che verrà usato per la produzione.
Ricorda anche di impostare la chiave API di produzione (GT_API_KEY) e l’ID del progetto (GT_PROJECT_ID) nelle variabili d’ambiente.
Utilizzo
Ci sono 3 modi per usare il comando translate. I metodi 1 e 2 richiedono una chiave API di produzione:
Ti consigliamo di eseguire la procedura guidata di configurazione npx gtx-cli configure per impostare il progetto prima di eseguire il comando translate.
In base a come è configurato il tuo progetto, il comportamento del comando translate può variare.
Metodo 1: Tradurre i file JSON del tuo progetto.
Se utilizzi altre librerie i18n come next-intl, react-i18next o next-i18next, puoi usare questo metodo per tradurre i file JSON del tuo progetto.
Le traduzioni verranno salvate automaticamente nella tua codebase.
Per utilizzare lo strumento CLI per tradurre i file JSON del tuo progetto, modifica il file gt.config.json per includere json nella proprietà files.
Consulta la documentazione di configurazione della CLI per maggiori dettagli.
npx gtx-cli translateLo strumento CLI rileverà automaticamente la tua libreria i18n leggendo il file package.json e tradurrà i file JSON rispettando la sintassi della tua libreria i18n.
Metodo 2: Tradurre il progetto GT
Se il tuo progetto utilizza gt-next o gt-react, puoi usare questo metodo per generare le traduzioni del tuo progetto.
npx gtx-cli translatePer impostazione predefinita, le traduzioni vengono salvate sul CDN di GT.
Se invece vuoi salvarle nel tuo codebase, aggiungi la proprietà gt all’oggetto files nel file gt.config.json.
gt-next e gt-react supportano sia la distribuzione delle traduzioni in locale sia l’uso del CDN pubblico di General Translation.
Consigliamo di usare il CDN per ridurre la latenza, migliorare le prestazioni e ridurre le dimensioni del bundle.
Consulta la documentazione di configurazione della CLI per ulteriori dettagli.
Metodo 3: valida i componenti <T> e il file del dizionario del tuo progetto.
Questo metodo è utile per validare i componenti <T> e il file del dizionario del tuo progetto.
In questo modo ti assicuri che il progetto sia configurato correttamente e che le traduzioni siano valide e accurate.
Non verranno generate traduzioni se si utilizza il flag --dry-run.
npx gtx-cli translate --dry-runFlag
| Parameter | Descrizione | Tipo | Opzionale | Predefinito |
|---|---|---|---|---|
--api-key | Specifica una chiave API di produzione | string | true | |
--project-id | Specifica l’ID del progetto | string | true | |
--version-id | Specifica un ID di versione (per impostazione predefinita, un hash del contenuto) | string | true | |
--config <path> | Specifica il percorso al file di configurazione di GT | string | true | "gt.config.json" |
--tsconfig, --jsconfig <path> | Specifica il percorso al file di configurazione TS o JS | string | true | |
--src <paths> | Elenco, separato da spazi, di pattern glob per individuare i file sorgente. Deve essere relativo alla directory root. | [string] | true | [ 'src/**/*.{js,jsx,ts,tsx}', 'app/**/*.{js,jsx,ts,tsx}', 'pages/**/*.{js,jsx,ts,tsx}', 'components/**/*.{js,jsx,ts,tsx}', ] |
--dictionary <path> | Specifica il percorso al file del dizionario | string | true | |
--inline | Includi i tag <T> inline oltre al dizionario | boolean | true | true |
--timeout | Timeout della richiesta di traduzione in secondi | number | true | 600 |
--new, --locales <locales> | Locali in cui tradurre il progetto | [string] | true | |
--default-locale <locale> | Locale sorgente del progetto | string | true | en |
--ignore-errors | Ignora gli errori e forza la traduzione per il contenuto valido | flag | true | false |
--dry-run | Esegui il comando in modalità simulata | flag | true | false |
--force | Forza una ritraduzione del progetto | flag | true | false |
--force-download | Forza il download di tutte le traduzioni del progetto | flag | true | false |
Tutti questi parametri sono opzionali.
Non aggiungere la tua chiave API al file gt.config.json!
Impostala invece come variabile d’ambiente. La CLI leggerà automaticamente GT_API_KEY se presente.
Ci sono alcuni parametri chiave:
| Parameter | Descrizione |
|---|---|
--dry-run | Questo flag fa sì che la CLI analizzi e convaldi il progetto, ma non comunichi con le API di GT. Utile per convalidare la codebase. |
--api-key | A meno che non si usi --dry-run, è necessario fornire una chiave API di produzione. |
--project-id | Allo stesso modo, a meno che non si usi --dry-run, è necessario fornire un ID progetto. |
--new, --locales <locales> | Locali in cui tradurre il progetto. Verranno aggiunte alle locali specificate nel file gt.config.json. |
--force | Questo flag forza una ritraduzione del progetto e sovrascrive tutte le traduzioni esistenti. |
--force-download | Questo flag forza il download di tutte le traduzioni e sovrascrive eventuali modifiche apportate localmente alle traduzioni. |
File di configurazione
Al primo avvio della CLI, verrà creato un file gt.config.json nella directory radice del progetto.
Questo file contiene metadati sul progetto utilizzati per tradurre i contenuti.
Maggiori dettagli sul file gt.config.json sono disponibili qui.
Consigli importanti
Origini dei contenuti
Il comando translate cerca ricorsivamente i contenuti traducibili nel tuo progetto.
Per impostazione predefinita, esamina le seguenti directory:
./src./app./pages./components
Puoi specificare directory alternative da includere nella ricerca utilizzando il flag --src,
oppure modificando la proprietà src nel file gt.config.json.
Sovrascrivere le traduzioni
Per impostazione predefinita, la CLI non sovrascrive le modifiche apportate localmente alle traduzioni, a meno che il contenuto sorgente non sia cambiato.
Se desideri ritradurre contenuti del progetto già tradotti, puoi usare il flag --force.
L'uso di --force sovrascriverà tutte le traduzioni esistenti e non manterrà le modifiche apportate localmente.
Se hai già scaricato le traduzioni più recenti del progetto e desideri riscaricarle, puoi usare il flag --force-download.
L'uso di --force-download sovrascriverà le modifiche apportate localmente e scaricherà le traduzioni più recenti. Non eseguirà alcuna nuova traduzione dei contenuti.
File del dizionario
Il comando translate rileva automaticamente il file del dizionario nel tuo progetto.
Per impostazione predefinita, cerca un file chiamato dictionary.[json|ts|js] nelle seguenti directory:
./src./
Puoi specificare un file di dizionario alternativo usando il flag --dictionary oppure modificando la proprietà dictionary nel file gt.config.json.
Come valuti questa guida?