# gt: General Translation CLI tool: Configurazione della CLI
URL: https://generaltranslation.com/it/docs/cli/guides/configuring.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Come impostare un file gt.config.json di General Translation con le impostazioni regionali, i file e le opzioni di archiviazione.

La CLI legge un file `gt.config.json` alla radice del tuo progetto per decidere cosa tradurre e dove salvare i risultati. Questa guida mostra come creare e modificare quel file.

*Nota: questa guida illustra le opzioni di configurazione più comuni. Per ogni campo disponibile, consulta il [riferimento della configurazione](/docs/cli/reference/config).*

## Crea il file di configurazione [#create]

Puoi creare `gt.config.json` in tre modi. Scegli quello più adatto al tuo workflow.

### a) Esegui la procedura guidata di configurazione completa

Esegui [`gt init`](/docs/cli/reference/commands/init) per rilevare il framework, configurare i file e, facoltativamente, eseguire il provisioning di un progetto e di una chiave di runtime di sviluppo. La procedura guidata ti fa accedere quando un passaggio lo richiede. Passa i [flag](/docs/cli/reference/commands/init#flags) per rispondere alle sue domande, oppure eseguila in modalità headless.

```bash
npx gt init
```

In un monorepo, esegui il comando dall'app che vuoi localizzare, non dalla radice dell'area di lavoro. Per le app React con Vite, la procedura guidata installa `gt-react`, configura [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) prima del punto di ingresso esistente dell'app e imposta il caricamento locale delle traduzioni o tramite CDN.

### b) Configurare senza il passaggio di configurazione di React

Esegui [`gt configure`](/docs/cli/reference/commands/configure) per creare o aggiornare `gt.config.json` senza la riscrittura sperimentale del framework React. Il resto del flusso di configurazione è identico a quello della procedura guidata completa: può generare i loader, installare la CLI, richiedere il login e predisporre le credenziali di sviluppo.

```bash
npx gt configure
```

### c) Scrivilo a mano

Crea tu stesso il file e aggiungi il riferimento `$schema` per la convalida e il completamento automatico nell'editor.

```json title="gt.config.json"
{
  "$schema": "https://assets.gtx.dev/config-schema.json",
  "defaultLocale": "en",
  "locales": ["fr", "es"]
}
```

## Imposta le impostazioni regionali [#locales]

Imposta `defaultLocale` sulla lingua in cui sono scritti i contenuti sorgente ed elenca le lingue di destinazione in `locales`.

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es", "ja"]
}
```

Entrambi usano codici locale standard come `en`, `en-US` o `zh`. Consulta [impostazioni regionali supportate](/docs/platform/dashboard/reference/supported-locales) per l'elenco completo.

Per usare un alias personalizzato per un'impostazione regionale — ad esempio `cn` invece di `zh` — aggiungi una voce `customMapping` che punti al codice ufficiale. Usa poi l'alias ovunque indichi quell'impostazione regionale in `defaultLocale` o `locales`.

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["cn", "fr"],
  "customMapping": {
    "cn": { "code": "zh" }
  }
}
```

## Scegli quali file tradurre [#files]

Aggiungi un oggetto `files` con una chiave per ogni tipo di file che vuoi tradurre. La maggior parte dei tipi prevede un array `include` di pattern glob che usano il segnaposto `[locale]` per individuare i file sorgente e salvare quelli tradotti. I [catalog `.xcstrings`](/docs/cli/reference/formats/xcstrings-files) sono l'eccezione, perché ogni impostazione regionale è memorizzata in un unico file che viene aggiornato in-place.

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "json": {
      "include": ["locales/[locale]/**/*.json"]
    },
    "mdx": {
      "include": ["content/docs/[locale]/**/*.mdx"]
    }
  }
}
```

La CLI sostituisce `[locale]` con `defaultLocale` quando cerca i file sorgente e con ciascun codice di destinazione quando salva le traduzioni. Le opzioni specifiche di ciascun tipo sono documentate in [Formati di file](/docs/cli/reference/formats/gt-jsx-files), mentre i criteri di corrispondenza avanzati sono documentati in [`include`](/docs/cli/reference/config#files).

## Scegli dove salvare le traduzioni [#storage]

Se usi `gt-next`, `gt-react` o `gt-react-native`, scegli come distribuire le traduzioni.

* **Salva localmente** per includere le traduzioni nel bundle della tua app. Aggiungi una voce `gt` con un percorso `output` che includa `[locale]`.
* **Pubblica sulla CDN** per caricare le traduzioni a runtime invece di includerle nel bundle. Imposta `publish` su `true`.

```json title="gt.config.json"
{
  "files": {
    "gt": {
      "output": "public/i18n/[locale].json"
    }
  }
}
```

(Vedi [pubblicazione CDN](/docs/cli/reference/config#cdn-publishing) per gestire la pubblicazione a livello globale, per file o per comando).

## Aggiungi le tue credenziali [#credentials]

### a) Accedi per lavorare in locale con la CLI

1. Esegui [`gt login`](/docs/cli/reference/commands/login) e approva l'accesso nel browser. Usa [`gt whoami`](/docs/cli/reference/commands/whoami) per verificare l'account e [`gt logout`](/docs/cli/reference/commands/logout) per disconnetterti.
2. Associa la tua app a un progetto impostando [`projectId`](/docs/cli/reference/config#project-id) nel file `gt.config.json` esistente, oppure imposta `GT_PROJECT_ID`. Il login da solo non seleziona né crea un progetto. Usa [`gt init`](/docs/cli/reference/commands/init) se preferisci una selezione o creazione guidata anziché un'associazione manuale.
3. Esegui [`gt translate`](/docs/cli/reference/commands/translate). Il tuo account deve disporre dell'autorizzazione per ciascuna operazione richiesta.

Gli SDK non leggono il login salvato della CLI: configura separatamente le credenziali di runtime.

### b) Usa una chiave esplicita per la CI

Esegui il commit della configurazione e fornisci `GT_API_KEY` tramite le impostazioni dei segreti del tuo provider CI. Imposta l'ID progetto nella configurazione o nell'ambiente. Il login, anche con `--no-browser`, richiede l'approvazione di una persona. In modalità headless, [`gt init`](/docs/cli/reference/commands/init) viene eseguito senza interazione solo se i flag rispondono a tutte le domande e non è necessario effettuare l'accesso.

```bash
GT_API_KEY=your-api-key
GT_PROJECT_ID=your-project-id
```

Crea una [chiave di progetto personalizzata](/docs/platform/dashboard/reference/api-keys#create-project-keys) oppure usa [`gt api-key create`](/docs/cli/reference/commands/api-key-create) con autorizzazioni esplicite. Concedi le autorizzazioni necessarie per l'intero workflow: lettura/download dei file, scrittura/caricamento dei file e accodamento delle traduzioni, oltre all'accesso al contesto, se utilizzato. Una chiave di runtime di sola generazione non è sufficiente per la pipeline di traduzione. Non salvare mai le chiavi API in `gt.config.json`: la normale validazione delle impostazioni della CLI le rifiuta.

### Precedenza delle credenziali e file di ambiente

I comandi ospitati usano prima `--api-key`, poi una `GT_API_KEY` non vuota e infine, se non viene fornita esplicitamente alcuna chiave degli strumenti, il login salvato. Se una chiave esplicita non è valida o non ha permessi sufficienti, non si ripiega mai sul login. `GT_DEV_API_KEY` e le relative varianti con prefisso pubblico sono impostazioni di runtime, non credenziali di gestione della CLI. Per usare il login, rimuovi le chiavi degli strumenti indesiderate sia dall'ambiente del processo sia dai file env caricati: il login non le rimuove automaticamente.

All'avvio, l'eseguibile carica `.env`, poi `.env.local` con override e infine `.env.production` con override. Gli ultimi due file possono sovrascrivere una chiave già esportata. Per l'associazione del progetto e i controlli sui conflitti, consulta [`projectId`](/docs/cli/reference/config#project-id).

### Chiavi di runtime per lo sviluppo

[`gt init`](/docs/cli/reference/commands/init) può generare una chiave con il solo permesso `project:translations:generate` nel file `.env.local` (escluso dal controllo di versione), usando i nomi delle variabili previsti dal tuo framework. Non sostituisce `GT_API_KEY`. (Per la configurazione del runtime, consulta [Credenziali di Next.js](/docs/react/nextjs/config#credentials)).

<Callout type="warn">
  Non includere mai chiavi API nei bundle distribuiti su browser o dispositivi mobili, nemmeno quelle di sola generazione. (Consulta [Protezioni dei file di init](/docs/cli/reference/commands/init#notes)).
</Callout>

## Next steps

- /docs/cli/guides/generating-translations
- /docs/cli/guides/managing-translations
- /docs/cli/guides/using-auto-jsx
- /docs/cli/guides/branching

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.