# gt: General Translation CLI tool: Translate
URL: https://generaltranslation.com/it/docs/cli/translate.mdx
---
title: Translate
description: Come tradurre il tuo progetto
---
## Utilizzo
```bash
npx gt translate
```
**Importante:** Eseguilo nella pipeline CI **prima** di generare la build di produzione dell'app.
## Panoramica
Il comando `gt translate` traduce il tuo progetto leggendo il file `gt.config.json` per determinare quali file tradurre.
Se utilizzi [`gt-next`](/docs/next), [`gt-react`](/docs/react) o [`gt-react-native`](/docs/react-native), cercherà anche nel codice sorgente del progetto i contenuti inline (come i componenti `` e gli hook `useGT`) e genererà i file di traduzione necessari.
Inoltre, include i contenuti del file del dizionario (se fornito).
Questo comando è il modo principale per utilizzare l'API di General Translation e i servizi correlati.
**Solo per l'uso in produzione:**
Questo comando è pensato per le build di produzione e **non deve essere usato in fase di sviluppo**.
Prima di eseguire questo comando, assicurati di trovarti sul branch che verrà usato per la produzione.
Imposta la chiave API di produzione (`GT_API_KEY`) e l'ID del progetto (`GT_PROJECT_ID`) come variabili d'ambiente.
**Nota:** È richiesta una chiave API di produzione. Puoi ottenerne una gratuitamente su [generaltranslation.com](https://generaltranslation.com/dashboard), oppure eseguire l'[assistente di configurazione](/docs/cli/init) per generarne una.
### Traduci il tuo progetto [#translate]
```bash
npx gt translate
```
Il comando `translate` legge il file `gt.config.json` per determinare quali file tradurre, cerca nel codice sorgente del progetto i contenuti traducibili e genera i file di traduzione necessari.
Le traduzioni vengono salvate automaticamente nella tua base di codice.
Per maggiori dettagli, consulta la [documentazione di configurazione](/docs/cli/reference/config#files).
{/* These links point to our own SDK docs intentionally — we want to show how our CLI handles these libraries, not link to the external library sites */}
**Rilevamento automatico:** Se usi [`next-intl`](/docs/next), [`react-i18next`](/docs/react), oppure
[`next-i18next`](/docs/react-native), lo strumento CLI rileverà automaticamente
la libreria i18n leggendo il file `package.json` e tradurrà i file
JSON rispettando la sintassi della libreria i18n.
### Convalida senza tradurre [#validate]
```bash
npx gt translate --dry-run
```
Se stai usando [`gt-next`](/docs/next), [`gt-react`](/docs/react), o [`gt-react-native`](/docs/react-native), puoi usarlo per convalidare i componenti `` e il file del dizionario del tuo progetto senza generare traduzioni.
***
## Flag
| Parametro | Descrizione | Tipo | Predefinito |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
| `--api-key` | Specifica una chiave API di production | `string` | |
| `--project-id` | Specifica l'ID del progetto | `string` | |
| `--version-id` | Specifica un ID versione (per impostazione predefinita, un hash del contenuto) | `string` | |
| `--config ` | Specifica il percorso del config file di GT | `string` | `"gt.config.json"` |
| `--tsconfig, --jsconfig ` | Specifica il percorso del config file TS o JS | `string` | |
| `--src ` | Pattern glob separati da spazi per i file di origine (relativi alla root) | `[string]` | `['src/**/*.{js,jsx,ts,tsx}', 'app/**/*.{js,jsx,ts,tsx}', 'pages/**/*.{js,jsx,ts,tsx}', 'components/**/*.{js,jsx,ts,tsx}']` |
| `--dictionary ` | Specifica il percorso del file del dizionario | `string` | |
| `--inline` | Include i tag `` inline oltre al dizionario | `boolean` | `true` |
| `--timeout` | Timeout della richiesta di traduzione, in secondi | `number` | `900` |
| `--new, --locales ` | Impostazioni regionali in cui tradurre (aggiunte alle locales di `gt.config.json`) | `[string]` | |
| `--default-locale ` | L'impostazione regionale di origine del progetto | `string` | `en` |
| `--ignore-errors` | Ignora gli errori e forza la traduzione dei contenuti validi | `flag` | `false` |
| `--dry-run` | Convalida senza tradurre | `flag` | `false` |
| `--force` | Forza la ritraduzione di tutto il contenuto | `flag` | `false` |
| `--force-download` | Forza il download di tutte le traduzioni | `flag` | `false` |
| `--save-local` | Rileva e salva le modifiche locali prima di accodare le traduzioni | `flag` | `false` |
| `--enable-branching` | Abilita la ramificazione per il progetto | `flag` | `false` |
| `--branch ` | Specifica un nome branch personalizzato per le traduzioni | `string` | |
| `--disable-branch-detection` | Disabilita il rilevamento automatico del branch | `flag` | `false` |
| `--tag [value]` | Etichetta questa esecuzione di traduzione (si risolve automaticamente da git se non viene fornito alcun valore) | `string` | |
| `-m, --message ` | Messaggio da allegare per etichettare la traduzione | `string` | |
| `--publish` | Pubblica le traduzioni sul CDN dopo la traduzione | `flag` | `false` |
| `--remote-name ` | Specifica un nome remote personalizzato per il rilevamento del branch | `string` | `"origin"` |
**Sicurezza:** Non aggiungere la tua chiave API al file `gt.config.json`. Impostala invece come variabile d'ambiente. La CLI legge automaticamente `GT_API_KEY` se è impostata.
### Flag principali
| Flag | Descrizione |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--dry-run` | Analizza e convalida il tuo progetto senza comunicare con l'API di GT. Utile per convalidare la tua base di codice. |
| `--force` | Ritraduci tutto il contenuto, sovrascrivendo le traduzioni esistenti. Tutte le modifiche locali andranno perse. Ti verranno addebitate le nuove traduzioni. |
| `--force-download` | Scarica di nuovo tutte le traduzioni, sovrascrivendo le modifiche locali. Non ritraduce. |
| `--save-local` | Rileva e salva le local edits nei file di traduzione prima dell'accodamento. Vedi [`save-local`](/docs/cli/save-local). |
| `--enable-branching` | Tieni traccia delle traduzioni separatamente per ciascun branch Git. Vedi [ramificazione](/docs/cli/branching). |
| `--tag` | Etichetta un'esecuzione di traduzione con un identificatore leggibile per il monitoraggio delle versioni. Vedi [tagging](#tagging). |
| `-m, --message` | Aggiunge un messaggio descrittivo a un'etichetta di traduzione. Vedi [tagging](#tagging). |
| `--publish` | Pubblica le traduzioni sul CDN per il caricamento a runtime. Vedi [pubblicazione sul CDN](#publishing-to-the-cdn). |
### File di configurazione
Quando esegui la CLI per la prima volta, proverà a creare un file `gt.config.json` nella cartella root del progetto. Per saperne di più sulla configurazione, leggi [qui](/docs/cli/reference/config).
## Suggerimenti importanti
### Origine dei contenuti
Il comando `translate` cerca ricorsivamente i contenuti traducibili nel tuo progetto.
Per impostazione predefinita, cerca nelle seguenti directory:
* `./src`
* `./app`
* `./pages`
* `./components`
Puoi specificare directory alternative in cui effettuare la ricerca usando il flag `--src`,
oppure modificando la proprietà `src` nel file [`gt.config.json`](/docs/cli/reference/config).
### Sovrascrivere le traduzioni
Per impostazione predefinita, la CLI non sovrascrive le modifiche locali alle traduzioni, a meno che il contenuto sorgente non sia cambiato.
Per ritradurre contenuti già tradotti, usa `--force`.
**Attenzione:** `--force` **sovrascriverà tutte le traduzioni esistenti e ne genererà di nuove**. Tutte le modifiche locali andranno perse. Ti verranno addebitate le nuove traduzioni.
Per scaricare di nuovo le traduzioni senza ritradurre, usa `--force-download`.
**Attenzione:** `--force-download` sovrascriverà le modifiche locali alle traduzioni e scaricherà le traduzioni più recenti. Non ritradurrà alcun contenuto.
### Tagging [#tagging]
Usa i flag `--tag` e `-m` per etichettare le esecuzioni di traduzione con identificatori comprensibili, così da semplificare il tracciamento e l'identificazione delle versioni nel dashboard.
#### Tag con un identificatore personalizzato
```bash
npx gt translate --tag v2.1.0
```
#### Aggiungi un tag con un identificatore e un messaggio personalizzati
```bash
npx gt translate --tag v2.1.0 -m "Aggiunte traduzioni della pagina di checkout"
```
#### Tag automatico da git
Passa `--tag` senza un valore per usare automaticamente l'hash del commit git corrente come ID del tag e il messaggio del commit come messaggio del tag:
```bash
npx gt translate --tag
```
Puoi sostituire il messaggio di commit con uno personalizzato:
```bash
npx gt translate --tag -m "Release 2.1 translations"
```
#### Tag solo per il messaggio
Se passi `-m` senza `--tag`, viene generato automaticamente un tag a partire dall'hash del commit git corrente (o da un identificatore casuale se non ti trovi in un repository git):
```bash
npx gt translate -m "Weekly translation update"
```
Il tagging non è bloccante: se la creazione dei tag non va a buon fine, l'esecuzione della traduzione continua normalmente.
### Pubblicazione sul CDN [#publishing-to-the-cdn]
Per impostazione predefinita, `gt translate` salva localmente i file di traduzione nella tua base di codice. Usa il flag `--publish` per pubblicare le traduzioni anche sul CDN di General Translation, così da consentire il caricamento delle traduzioni a runtime senza dover includere i file nell'app.
```bash
npx gt translate --publish
```
È utile per i progetti `gt-next` che caricano le traduzioni dalla CDN a runtime anziché da file locali.
**La CDN deve essere abilitata:** prima di usare `--publish`, abilita la CDN nelle impostazioni del progetto su [generaltranslation.com/dashboard](https://generaltranslation.com/dashboard). Se la CDN non è abilitata, il comando tradurrà correttamente ma la pubblicazione non andrà a buon fine e verrà mostrato un avviso.
Puoi combinare `--publish` con l'output in file locali: le traduzioni verranno salvate localmente *e* pubblicate sulla CDN:
```bash
npx gt translate --publish
```
### File del dizionario
Il comando `translate` rileva automaticamente il file del dizionario nel tuo progetto.
Per impostazione predefinita, cerca un file denominato `dictionary.[json|ts|js]` in:
* `./src`
* `./`
Puoi specificare un file del dizionario diverso con il flag `--dictionary` oppure modificando la proprietà `dictionary` nel file [`gt.config.json`](/docs/cli/reference/config).