# gt: General Translation CLI tool: gt translate URL: https://generaltranslation.com/it/docs/cli/reference/commands/translate.mdx --- title: gt translate description: Traduce un progetto tramite l'API di General Translation. Riferimento API per il comando gt translate. --- Traduce il tuo progetto. Legge `gt.config.json` per trovare i file, analizza il codice sorgente per individuare contenuti inline quando usi una libreria del framework, include il dizionario e salva le traduzioni nella base di codice o sul CDN. Questo è il comando principale per usare l'API di General Translation. Eseguilo in CI prima di una build di produzione. Per il flusso di lavoro completo, vedi [Generazione delle traduzioni](/docs/cli/guides/generating-translations). Dietro le quinte, `translate` esegue stage e download in un unico passaggio; per eseguire queste operazioni separatamente, usa [`gt stage`](/docs/cli/reference/commands/stage), [`gt upload`](/docs/cli/reference/commands/upload), [`gt enqueue`](/docs/cli/reference/commands/enqueue) e [`gt download`](/docs/cli/reference/commands/download). *Nota: solo per uso in produzione. Imposta una `GT_API_KEY` di produzione e `GT_PROJECT_ID` come variabili d'ambiente e non archiviare mai la tua chiave API in `gt.config.json`.* ```bash npx gt translate ``` ## Come funziona [#how-it-works] 1. Legge `gt.config.json` per determinare le impostazioni regionali di destinazione, i file da tradurre e i relativi percorsi di output. 2. Per i progetti `gt-next`, `gt-react`, `gt-react-native` e `gt-tanstack-start`, analizza i pattern glob in `src` per individuare contenuti inline — componenti [``](/docs/react/reference/components/t) e chiamate a [`useGT`](/docs/react/reference/hooks/use-gt) — e include il file del dizionario. 3. Rileva automaticamente da `package.json` una libreria i18n di terze parti — `next-intl` o `i18next` (con supporto per `i18next-icu`) — e ne traduce i file JSON rispettandone la sintassi. 4. Mette in stage il contenuto raccolto e scarica i risultati in un solo passaggio. Internamente, equivale a eseguire prima [`gt stage`](/docs/cli/reference/commands/stage) e poi [`gt download`](/docs/cli/reference/commands/download); usa i comandi separati per eseguire queste operazioni distintamente. 5. Salva le traduzioni nella tua base di codice e sulla CDN quando è impostato `--publish` o la chiave di configurazione [`publish`](/docs/cli/reference/config#publish). Per impostazione predefinita, la CLI non sovrascrive le modifiche alle traduzioni locali a meno che il contenuto sorgente non sia cambiato. Usa `--force` per tradurre di nuovo tutto, oppure `--force-download` per riscaricare senza ritradurre. ## Flag [#flags] | Parametro | Descrizione | Tipo | Facoltativo | Predefinito | | ---------------------------- | ---------------------------------------------------------------------------------------------------- | ---------- | ----------- | ------------------ | | `--api-key ` | Chiave API di produzione. | `string` | Sì | `GT_API_KEY` | | `--project-id ` | ID progetto. | `string` | Sì | `GT_PROJECT_ID` | | `--version-id ` | ID versione per l'esecuzione. | `string` | Sì | hash del contenuto | | `-c, --config ` | Percorso del file di configurazione. | `string` | Sì | `gt.config.json` | | `--default-locale ` | Impostazione regionale sorgente del progetto. | `string` | Sì | `en` | | `--locales ` | Impostazioni regionali di destinazione aggiuntive, aggiunte ai `locales` di configurazione. | `string[]` | Sì | — | | `--timeout ` | Timeout di attesa della traduzione, in secondi. | `number` | Sì | `900` | | `--dry-run` | Analizza e valida senza chiamare l'API. | `boolean` | Sì | `false` | | `--force` | Ritraduce tutti i contenuti, sovrascrivendo le traduzioni esistenti. | `boolean` | Sì | `false` | | `--force-download` | Riscarica tutte le traduzioni, sovrascrivendo le modifiche locali. | `boolean` | Sì | `false` | | `--save-local` | Salva le modifiche locali prima dell'accodamento. | `boolean` | Sì | `false` | | `--publish` | Pubblica le traduzioni sulla CDN. | `boolean` | Sì | `false` | | `--enable-branching` | Abilita il tracciamento basato sui branch. | `boolean` | Sì | `false` | | `--branch ` | Nome del branch da usare al posto del rilevamento automatico. | `string` | Sì | — | | `--disable-branch-detection` | Usa solo il branch specificato, senza rilevare le relazioni. | `boolean` | Sì | `false` | | `--remote-name ` | Remote Git usato per rilevare il branch. | `string` | Sì | `origin` | | `--omit-config-ids` | Non scrivere `_versionId` o `_branchId` in `gt.config.json`. | `boolean` | Sì | — | | `--tag [value]` | Etichetta l'esecuzione; se non viene fornito alcun valore, viene risolto automaticamente da Git. | `string` | Sì | — | | `-m, --message ` | Messaggio associato al tag di traduzione. | `string` | Sì | — | ### Flag di scansione dei file sorgente [#source] Si applicano durante la scansione del codice sorgente nei progetti `gt-next`, `gt-react`, `gt-react-native` e `gt-tanstack-start`. | Parameter | Description | Type | Optional | Default | | ------------------------------- | --------------------------------------------------------------------- | ---------- | -------- | ---------------------------------------- | | `--src ` | Pattern glob per i file sorgente. | `string[]` | Sì | glob `src`, `app`, `pages`, `components` | | `--dictionary ` | Percorso del file del dizionario. | `string` | Sì | — | | `--tsconfig, --jsconfig ` | Percorso di un file di configurazione TS o JS. | `string` | Sì | Rilevato automaticamente | | `--inline` | Include contenuti inline come `` e `useGT`. | `boolean` | Sì | `true` | | `--ignore-errors` | Ignora gli errori rilevati durante la scansione dei contenuti inline. | `boolean` | Sì | `false` | ### Flag sperimentali [#experimental] | Parametro | Descrizione | Tipo | Facoltativo | Predefinito | | ----------------------------------------- | ------------------------------------------------------------------------------ | --------- | ----------- | ----------- | | `--experimental-localize-static-urls` | Localizza gli URL nei file `md`/`mdx` tradotti. | `boolean` | Sì | `false` | | `--experimental-hide-default-locale` | Nasconde l'impostazione regionale predefinita nei percorsi localizzati. | `boolean` | Sì | `false` | | `--experimental-flatten-json-files` | Appiattisce i file JSON in un unico file. | `boolean` | Sì | `false` | | `--experimental-localize-static-imports` | Localizza gli import statici nei file `md`/`mdx` tradotti. | `boolean` | Sì | `false` | | `--experimental-localize-relative-assets` | Riscrive gli URL delle risorse immagine relative nei file `md`/`mdx` tradotti. | `boolean` | Sì | `false` | | `--experimental-clear-locale-dirs` | Svuota le directory delle impostazioni regionali prima del download. | `boolean` | Sì | `false` | ## Esempio [#example] ```bash # Traduci usando gt.config.json, leggendo GT_API_KEY e GT_PROJECT_ID dall'ambiente npx gt translate # Analizza e valida il progetto senza chiamare l'API npx gt translate --dry-run # Salva le traduzioni localmente e pubblicale sul CDN per il caricamento a runtime npx gt translate --publish # Etichetta l'esecuzione per identificarla facilmente nel dashboard npx gt translate --tag v2.1.0 -m "Added checkout page translations" ``` ## Altre note [#notes] * **Sorgenti dei contenuti:** la CLI analizza `src`, `app`, `pages` e `components` per impostazione predefinita. Puoi modificare questo comportamento con `--src` o con la chiave di configurazione [`src`](/docs/cli/reference/config#src). * **Dizionario:** quando `--dictionary` non è impostato, la CLI cerca `dictionary.[json|ts|js]` in `./src` e `./`. * **Sovrascrittura:** `--force` sovrascrive tutte le traduzioni esistenti e addebita le nuove; `--force-download` sovrascrive le modifiche locali con le traduzioni più recenti senza tradurre di nuovo. * **Tagging:** il tagging non è bloccante — se la creazione del tag non riesce, l'esecuzione continua. Passa `--tag` senza valore per usare l'hash del commit git corrente e il relativo messaggio. * **Pubblicazione:** abilita la CDN nelle impostazioni del progetto prima di usare `--publish`. Se la CDN non è abilitata, l'esecuzione traduce correttamente ma la fase di pubblicazione non va a buon fine e mostra un avviso. * **Branching:** passa `--enable-branching` per tenere traccia delle traduzioni per branch git. Vedi [Monitoraggio delle traduzioni per branch](/docs/cli/guides/branching). * **Sicurezza:** non archiviare mai la tua chiave API in `gt.config.json`. La CLI legge automaticamente `GT_API_KEY` e `GT_PROJECT_ID` dall'ambiente.