# gt: General Translation CLI tool: Guida rapida
URL: https://generaltranslation.com/it/docs/cli/quickstart.mdx
---

title: Guida rapida
description: Scopri cosa fa la CLI di General Translation, quando usarla e come tradurre il tuo primo progetto.
related:
  links:
    - /docs/cli/guides/generating-translations
    - /docs/cli/guides/configuring
    - /docs/cli/guides/managing-translations
    - /docs/cli/guides/using-auto-jsx

---

La CLI di General Translation (`gt`) configura l'internazionalizzazione e traduce il tuo progetto dalla riga di comando.

Funziona con [`gt-react`, `gt-next` e `gt-react-native`](/docs/react/overview), con librerie i18n di terze parti come `next-intl` e `i18next`, e con file standalone come JSON, YAML, Markdown e MDX.

## Cosa fa la CLI [#what-it-does]

La CLI ti offre accesso diretto a:

* **Configurazione iniziale** per installare le dipendenze, integrare il tuo framework e creare un `gt.config.json`.
* **Traduzione** per inviare i contenuti sorgente all'API di General Translation e salvare i risultati nella tua base di codice o sul CDN.
* **Componenti di base per la CI** per caricare, accodare e scaricare le traduzioni in diverse fasi della pipeline.
* **Convalida** per verificare la presenza di errori di traduzione nel progetto senza chiamare l'API.

## Quando usare la CLI [#when-to-use]

Usa la CLI quando vuoi:

* Configurare un nuovo progetto per la traduzione con una procedura guidata.
* Tradurre il tuo progetto come parte di una pipeline di build o CI.
* Tradurre file di contenuto indipendenti senza aggiungere una libreria del framework.
* Tenere le traduzioni sotto controllo di versione insieme ai contenuti sorgente.

## Guida rapida [#quickstart]

Installa `gt`, configura il progetto ed esegui la prima traduzione. È necessario disporre di un progetto esistente con un `package.json` e Node.js installato.

### 1. Installa `gt`

Installa la CLI come dipendenza di sviluppo.

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install gt --save-dev
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

### 2. Configura il tuo progetto

Esegui la procedura guidata di setup per rilevare il framework, creare un `gt.config.json` e generare le credenziali quando il setup selezionato le richiede.

```bash
npx gt init
```

In un monorepo, esegui il comando dall&#39;app che vuoi localizzare. La procedura guidata si interrompe senza modificare i file quando la esegui dalla radice dell&#39;area di lavoro.

<Callout type="warn">
  [`gt init`](/docs/cli/reference/commands/init) è una procedura guidata interattiva e richiede un terminale. In CI o in un&#39;altra shell non interattiva potrebbe restare in attesa di input, non superare la convalida o terminare in anticipo senza creare `gt.config.json` né scrivere le credenziali. Per questi ambienti, usa [Configurazione non interattiva per CI](#ci-setup).
</Callout>

La procedura guidata imposta la tua impostazione regionale predefinita e le impostazioni regionali di destinazione, sceglie dove archiviare le traduzioni e, quando la configurazione selezionata richiede credenziali, può scrivere la tua chiave API e l&#39;ID progetto in `.env.local`. Consulta [Configurare la CLI](/docs/cli/guides/configuring) per configurare tutto nel dettaglio, oppure [`gt init`](/docs/cli/reference/commands/init) per la sintassi completa del comando.

*Nota: ora dovresti avere un `gt.config.json` nella radice del progetto. Se la procedura guidata ha generato le credenziali, `.env.local` contiene `GT_API_KEY` e `GT_PROJECT_ID`. La configurazione Vite locale inclusa non usa credenziali, quindi aggiungile nel passaggio successivo prima di tradurre.*

### 3. Aggiungi la tua chiave API di produzione

Il comando [`translate`](/docs/cli/reference/commands/translate) richiede una chiave API di produzione e un ID progetto. La procedura guidata può generarli per te, oppure puoi crearli nella pagina [API Keys](https://generaltranslation.com/dashboard). Impostali come variabili d&#39;ambiente, in modo che la CLI possa leggerli.

```bash title=".env.local"
GT_API_KEY=your-api-key
GT_PROJECT_ID=your-project-id
```

*Nota: imposta la tua chiave API come variabile d&#39;ambiente: non aggiungerla mai a `gt.config.json`.*

### 4. Traduci il tuo progetto

Esegui il comando [`translate`](/docs/cli/reference/commands/translate) per tradurre tutti i file configurati in `gt.config.json`, insieme a eventuali componenti inline [`<T>`](/docs/react/reference/components/t) e alle voci del dizionario nel codice sorgente.

```bash
npx gt translate
```

Le traduzioni vengono salvate nella tua base di codice, pronte per il commit. Esegui questo comando nella tua pipeline CI prima della build di produzione. Consulta [Generating translations](/docs/cli/guides/generating-translations) per il workflow completo.

## Configurazione non interattiva per CI [#ci-setup]

La procedura guidata di setup richiede un terminale interattivo, quindi non può essere eseguita in CI o in altri ambienti non interattivi. Configura tutto manualmente: esegui il commit di un `gt.config.json`, fornisci le credenziali come variabili d&#39;ambiente ed esegui [`translate`](/docs/cli/reference/commands/translate) con tale configurazione.

### 1. Aggiungi un `gt.config.json`

Scrivi il file manualmente ed esegui il commit, così la CLI saprà cosa tradurre. Una configurazione minima imposta l&#39;impostazione regionale sorgente e quelle di destinazione, oltre a una voce `files`, in modo che [`translate`](/docs/cli/reference/commands/translate) abbia qualcosa su cui lavorare. La voce `gt` qui sotto memorizza localmente, nel percorso indicato, le traduzioni del framework (da `gt-next`, `gt-react` o `gt-react-native`).

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

Per tradurre invece file autonomi, aggiungi un tipo di file come `json` o `mdx` con un pattern `include` al posto della voce `gt` (o accanto a essa). Consulta [Configurare la CLI](/docs/cli/guides/configuring) per le opzioni relative a file e archiviazione, e il [riferimento della configurazione](/docs/cli/reference/config) per tutti i campi.

### 2. Imposta le tue credenziali

Imposta la tua chiave API di produzione e l&#39;ID progetto come variabili d&#39;ambiente nelle impostazioni dei secret del tuo provider CI, non in un file versionato. Creali nella pagina [API Keys](https://generaltranslation.com/dashboard).

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

### 3. Esegui il comando translate

Esegui [`translate`](/docs/cli/reference/commands/translate) prima della build di produzione. Passa `--config` per specificare il file di configurazione.

```bash
npx gt translate --config gt.config.json
```
## Next steps

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