# gt: General Translation CLI tool: gt translate URL: https://generaltranslation.com/it/docs/cli/reference/commands/translate.mdx Docs index: https://generaltranslation.com/llms.txt 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` mette in stage e scarica 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). Le animazioni Lottie devono essere sottoposte a stage prima di un download successivo, poiché l'elaborazione del loro layout è asincrona. *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`, `gt-tanstack-start` e `gt-vue`, analizza i pattern glob in `src` per individuare contenuti inline. Questo include i componenti [``](/docs/react/reference/components/t) e le chiamate a [`useGT`](/docs/react/reference/hooks/use-gt) della famiglia React, insieme ai template Vue e alle chiamate a [`t()`](/docs/vue/reference/functions/t) a livello di modulo, 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 con [`gt stage`](/docs/cli/reference/commands/stage): carica i sorgenti, facoltativamente rileva e salva le modifiche locali quando è impostato `--save-local` o [`options.saveLocal: true`](/docs/cli/reference/config#save-local), quindi mette in coda i job di traduzione. Poiché l'elaborazione del layout di Lottie è asincrona, un progetto con file `.lottie` termina prima di questo passaggio quando `stageTranslations` è `false`, senza caricare o mettere nulla in coda, e ti indirizza al flusso separato. 5. Scarica i risultati con [`gt download`](/docs/cli/reference/commands/download). Usa i comandi separati per eseguire staging e download distintamente. 6. 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 sincronizza le modifiche alle traduzioni locali prima di avviare nuovo lavoro. Usa `--save-local` per sincronizzarle, `--force` per ritradurre 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 ` | Accettato ma senza effetto; consulta la nota seguente. | `string` | Sì | — | | `-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, --no-save-local` | Abilita o disabilita il salvataggio delle 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ì | — | | `--branch ` | Nome del branch da usare al posto del rilevamento automatico. Implica `--enable-branching`. | `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`, `gt-tanstack-start` e `gt-vue`. | Parameter | Description | Type | facoltativo | Default | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------- | ---------------------------- | | `--src ` | Pattern glob per i file sorgente. | `string[]` | Sì | Glob specifici del framework | | `--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 [``](/docs/react/reference/components/t) e [`useGT`](/docs/react/reference/hooks/use-gt). | `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 usa valori predefiniti specifici per framework. I progetti della famiglia React analizzano `src`, `app`, `pages` e `components`; i progetti Vue coprono anche i file `.vue` nella radice e le directory convenzionali di Vue e Nuxt. 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 `./`. * **Modifiche locali:** la sincronizzazione delle modifiche locali è disattivata per impostazione predefinita. Passa `--save-local` per una singola esecuzione oppure imposta [`options.saveLocal`](/docs/cli/reference/config#save-local) su `true`. * **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. * **Lottie:** traduci le animazioni con [`gt stage`](/docs/cli/reference/commands/stage), quindi esegui nuovamente [`gt download`](/docs/cli/reference/commands/download) finché ogni impostazione regionale non è pronta. Vedi il [riferimento al formato Lottie](/docs/cli/reference/formats/lottie-files). * **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, oppure passa `--branch `, che abilita il branching autonomamente. Quando nessuno dei due flag è impostato, la CLI ricorre a `branchOptions.enabled` in `gt.config.json` e, se non è impostato, lo disabilita. Vedi [Monitoraggio delle traduzioni per branch](/docs/cli/guides/branching). * **`--version-id` non ha effetto.** Il flag viene analizzato, ma non viene letto da nulla: gli ID versione sono hash dei contenuti per file e i comandi che necessitano di una versione a livello di esecuzione leggono `_versionId` da `gt.config.json`. Imposta invece [`_versionId`](/docs/cli/reference/config) lì. * **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. ### Cronologia delle versioni | Versione | Modifiche | | -------- | --------------------------------------------------------------------------------------------------------------------------- | | `2.20.3` | Le modifiche locali sono diventate opt-in; `--save-local` abilita lo step. | | `2.16.1` | Le modifiche locali vengono salvate per impostazione predefinita; `--no-save-local` consente di disattivare questa opzione. | ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.