# gt: General Translation CLI tool: gt init URL: https://generaltranslation.com/it/docs/cli/reference/commands/init.mdx Docs index: https://generaltranslation.com/llms.txt Description: Esegui la procedura guidata di configurazione di General Translation per impostare un progetto. Riferimento API per il comando gt init. `init` è il comando predefinito: se esegui `npx gt` senza specificare alcun comando, viene eseguito. La procedura guidata rileva il framework in uso e, a seconda del progetto, installa le dipendenze, configura il framework, crea un `gt.config.json` e genera le credenziali. Per una guida passo passo, consulta [Configurazione della CLI](/docs/cli/guides/configuring). ```bash npx gt init ``` ## Come funziona [#how-it-works] 1. Rileva il tuo framework. Per un progetto Next.js App Router o Mintlify, propone invece di collegare l'agente IA [Locadex](/docs/platform/locadex/quickstart). 2. Per un progetto basato su React, installa facoltativamente il runtime corrispondente e configura il framework (sperimentale). Le app Next.js App Router ricevono [`GTProvider`](/docs/react/reference/components/gt-provider) e `withGTConfig`. Le app Vite ricevono un bootstrap [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) che viene eseguito prima del punto di ingresso dell'app esistente. Le app TanStack Start ricevono `gt-tanstack-start`, `src/loadTranslations.ts`, [`gtMiddleware`](/docs/react/tanstack-start/reference/functions/gt-middleware) in `src/start.ts`, [`initializeGT`](/docs/react/tanstack-start/setup#initialize) in `src/router.tsx` e [`GTProvider`](/docs/react/reference/components/gt-provider) nella route radice. Nelle altre app React viene installata solo la libreria. 3. Determina le impostazioni regionali predefinite e di destinazione e crea o aggiorna `gt.config.json`. `--locales` sostituisce l'elenco delle impostazioni regionali configurato e `--file-formats` sostituisce i formati proposti dalla configurazione; gli altri formati e le impostazioni non correlate vengono mantenuti. Un file `gt.config.json` non valido interrompe la configurazione prima di qualsiasi modifica. Per l'archiviazione locale di Vite o TanStack Start, crea anche un file [`loadTranslations`](/docs/react/reference/functions/load-translations) e file vuoti per le impostazioni regionali di destinazione. 4. Installa `gt` come dipendenza di sviluppo quando il workflow configurato richiede un'installazione persistente della CLI. La configurazione del framework Vite non aggiunge `gt`; continua a eseguirlo con `npx gt`. 5. Facoltativamente, seleziona o crea un progetto e genera una chiave runtime di sviluppo in `.env.local`. La configurazione effettua l'accesso solo per questo passaggio, prima di modificare i file, e usa una chiave degli strumenti esplicita o un login salvato, se disponibili. Con l'archiviazione locale, le configurazioni di Vite e TanStack Start chiedono se abilitare le traduzioni di sviluppo in tempo reale (predefinito: no); se si rifiuta, vengono saltati l'accesso, l'individuazione del progetto e la creazione della chiave. *Nota: il passaggio di configurazione di React è sperimentale e potrebbe non funzionare per tutti i progetti. Verifica le modifiche apportate.* ### Selezione del progetto e credenziali di runtime Se è configurato un ID progetto, questo viene riutilizzato. In caso contrario, la procedura guidata elenca i [progetti accessibili](/docs/platform/openapi/reference/project/list-projects) tra cui scegliere oppure propone di crearne uno. Quando crei un progetto, scegli una Organization in cui disponi dell'autorizzazione a creare progetti. Se non ne è disponibile nessuna, crea una Organization nella Dashboard oppure chiedi l'accesso a un amministratore. In modalità interattiva, il nome del progetto corrisponde per impostazione predefinita al nome della directory dell'app; la creazione in modalità headless richiede `--project-name`. Il progetto viene creato con l'impostazione regionale sorgente selezionata. La selezione di un progetto esistente non richiede l'accesso alla creazione di progetti nella Organization. Il provisioning di una chiave richiede comunque l'autorizzazione in scrittura sulle chiavi e l'autorizzazione a delegare la generazione a runtime. Se una chiave degli strumenti specificata esplicitamente non è valida o non dispone di autorizzazioni sufficienti, non si ricorre mai al login come alternativa. Il provisioning crea una sola chiave denominata `Development key (gt init)` con il solo ambito `project:translations:generate`. Scrive l'ID progetto e la chiave di sviluppo senza mostrare il segreto né modificare un eventuale `GT_API_KEY` esistente. Questa chiave di runtime non autentica i successivi comandi di gestione della CLI; usa il tuo login oppure una chiave degli strumenti con un ambito dedicato. (Consulta [credenziali](/docs/cli/guides/configuring#credentials)). Se esistono già credenziali di runtime del framework per lo stesso progetto, il provisioning può essere saltato. Viene saltato anche nelle configurazioni solo lato server con un ID progetto e `GT_API_KEY`; i framework che traducono nel browser non considerano `GT_API_KEY` senza prefisso come chiave di runtime. Le variabili generate sono `GT_PROJECT_ID` e `GT_DEV_API_KEY`, con i seguenti prefissi per i framework che traducono nel browser: * Next.js (App Router e Pages Router): `NEXT_PUBLIC_` * Vite e TanStack Start: `VITE_` * Gatsby: `GATSBY_` * React: `REACT_APP_` * Redwood: `REDWOOD_ENV_` Le altre configurazioni usano variabili senza prefisso. Le chiavi di sviluppo sono destinate esclusivamente allo sviluppo locale; per le credenziali di produzione, consulta [credenziali di Next.js](/docs/react/nextjs/config#credentials). Non includere mai chiavi API nei bundle distribuiti per browser o dispositivi mobili. ## Flag [#flags] I flag forniscono in anticipo le risposte alle domande della procedura guidata, così durante l'esecuzione vengono poste solo quelle rimanenti. Gli stessi flag di configurazione e delle credenziali funzionano anche con [`gt configure`](/docs/cli/reference/commands/configure). ### Modalità di configurazione | Parametro | Descrizione | Tipo | Facoltativo | Predefinito | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------- | ---------------- | | `--no-interactive` | Non richiede mai input. Si interrompe prima di modificare i file ed elenca le opzioni ancora mancanti. Si attiva automaticamente quando stdin o stdout non è un terminale. | `boolean` | Sì | `false` | | `--json` | Scrive su stdout gli eventi di accesso, di passaggio di consegne e di risultato come righe JSON, e tutto il resto dell'output su stderr. Implica `--no-interactive`. | `boolean` | Sì | `false` | | `--defaults` | Accetta il valore consigliato per ogni scelta locale non già determinata da un flag o da `gt.config.json`. Non crea mai progetti né chiavi. | `boolean` | Sì | — | | `--no-defaults` | Non propone i valori predefiniti consigliati. | `boolean` | Sì | — | | `-c, --config ` | Percorso del file di configurazione. | `string` | Sì | `gt.config.json` | ### Configurazione | Parametro | Descrizione | Tipo | Opzionale | Predefinito | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | --------- | --------------------------------------------------------- | | `--src ` | Pattern glob per il codice sorgente dell'app. | `string[]` | Sì | [Specifico del framework](/docs/cli/reference/config#src) | | `--default-locale ` | Impostazione regionale predefinita, ad esempio `en`. | `string` | Sì | `en` con `--defaults` | | `--locales ` | Impostazioni regionali di destinazione, ad esempio `fr es`. Sostituisce l'elenco configurato. | `string[]` | Sì | — | | `--storage ` | Dove vengono archiviate le traduzioni del framework: `local` o `cdn`. `gt-vue` supporta solo `local`. | `string` | Sì | `local` con `--defaults` | | `--translations-dir ` | Directory per i file di traduzione locali. | `string` | Sì | Specifica del framework con `--defaults` | | `--file-formats ` | `json`, `md`, `mdx`, `ts`, `js`, `yaml` o `none`. Sostituisce la selezione configurata tra questi formati; gli altri formati configurati vengono mantenuti e viene mostrato un avviso. | `string[]` | Sì | `none` con `--defaults` nei progetti basati su framework | | `--file-patterns ` | Pattern `=` che includono `[locale]`, ad esempio `json=./locales/[locale]/*.json`. Seleziona anche il formato. | `string[]` | Sì | `./**/[locale]/*.` con `--defaults` | | `--package-manager ` | Package manager da usare per le installazioni: `npm`, `yarn_v1`, `yarn_v2`, `pnpm`, `bun` o `deno`. Per il rilevamento si usa il campo `packageManager` o `devEngines`, il lockfile o l'indicatore di area di lavoro riconosciuto più vicino, risalendo fino alla root Git. | `string` | Sì | Rilevato automaticamente | ### Progetto e credenziali di sviluppo | Parametro | Descrizione | Tipo | Facoltativo | Predefinito | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ----------- | ----------------------------------------------- | | `--dev-credentials` | Salva un ID progetto e una nuova chiave di sviluppo in `.env.local`. Usa `--no-dev-credentials` per saltare questo passaggio. | `boolean` | Sì | — | | `--live-translations` | Archiviazione locale Vite o TanStack Start: configura le traduzioni di sviluppo in tempo reale, creando una chiave di sviluppo. Usa `--no-live-translations` per saltare questo passaggio. | `boolean` | Sì | `false` con `--defaults` | | `--project-id ` | Progetto esistente da usare per le credenziali di sviluppo. | `string` | Sì | — | | `--create-project` | Crea un nuovo progetto per le credenziali di sviluppo. | `boolean` | Sì | `false` | | `--org-id ` | Organization proprietaria del nuovo progetto. Serve solo se hai accesso a più di una Organization. | `string` | Sì | — | | `--project-name ` | Nome del nuovo progetto. | `string` | Sì | Nome della directory dell'app, se richiesto | ### Configurazione del framework Questi flag si applicano solo a `gt init`. Nei progetti `gt-vue`, `gt init` accetta i flag di [`gt configure`](/docs/cli/reference/commands/configure) e salta la configurazione di React. | Parametro | Descrizione | Tipo | Facoltativo | Predefinito | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------- | ------------------------------------------ | | `--locadex` | Mintlify e Next.js App Router: affida la configurazione all'agente IA di Locadex tramite GitHub. Usa `--no-locadex` per eseguire la configurazione in locale. | `boolean` | Sì | `false` con `--defaults` | | `--react-setup` | Progetti React: installa la libreria e, per Next.js App Router, Vite o TanStack Start, ne aggiunge la configurazione (vedi [Come funziona](#how-it-works)). Usa `--no-react-setup` per lasciare invariato il codice sorgente dell'applicazione. | `boolean` | Sì | `true` con `--defaults` | | `--framework ` | Framework React per `--react-setup`. Ha la precedenza sul rilevamento automatico. | `string` | Sì | Rilevato automaticamente, con `--defaults` | | `--format` | Next.js App Router: formatta i file modificati durante la configurazione con il formattatore rilevato. Usa `--no-format` per saltare questo passaggio. | `boolean` | Sì | `true` con `--defaults` | ## Esecuzioni headless [#headless] Un'esecuzione non interattiva ricava ogni risposta dal relativo flag, poi da `gt.config.json` e infine dal valore consigliato, se è impostato `--defaults`. Se una risposta manca ancora, il comando termina prima di modificare i file ed elenca le opzioni da passare. Le credenziali di sviluppo non vengono mai create per impostazione predefinita. Per l'archiviazione locale con Vite e TanStack Start, passa `--live-translations` con un ID progetto oppure `--create-project --project-name `, oppure passa `--no-live-translations`. Per le altre configurazioni, usa `--dev-credentials` o `--no-dev-credentials`. Non combinare le famiglie di flag `--[no-]live-translations` e `--[no-]dev-credentials`: la CLI rifiuta qualsiasi combinazione tra le due prima di modificare i file. Se il progetto dispone già di credenziali di runtime, questo passaggio viene saltato. Il setup esegue l'accesso solo quando deve effettuare il provisioning delle credenziali e non trova né una chiave degli strumenti né un login salvato. In assenza di un terminale, l'accesso avviene tramite un codice dispositivo e resta in attesa che una persona lo approvi, senza aprire un browser. Con `--json`, il comando scrive un oggetto JSON per riga, identificato dal relativo campo `type`: * `authorization_required` — `verificationUri`, `userCode` e, se disponibile, `verificationUriComplete`. * `handoff` — l'`url` GitHub di Locadex, con `reason: "locadex"`. * `result` — `command`, `outcome` (`success`, `needs_human_action` o `failed`), `completedSteps` e, se presenti, `url`, `actions` per le operazioni manuali successive, `missingOptions` ed `error`. `completedSteps` non include nell'elenco `gt.config.json` e i file del loader di traduzioni generati, se rimasti invariati. Quando uno dei due file viene modificato, il passaggio lo indica come creato o aggiornato. ## Esempio [#example] ```bash # Esegui la procedura guidata di configurazione completa npx gt init # Eseguire gt senza alcun comando produce lo stesso risultato npx gt # Configurazione locale headless: nessun nuovo progetto né chiave di sviluppo npx gt init --no-interactive --defaults --locales fr es --no-dev-credentials --json ``` ## Altre note [#notes] * `init` condivide con [`gt configure`](/docs/cli/reference/commands/configure) la configurazione, il loader, l'installazione della CLI e il flusso delle credenziali, e aggiunge il passaggio sperimentale di configurazione di React. Non esegue [`gt setup`](/docs/cli/reference/commands/setup), che carica i tuoi file sorgente. * In un monorepo, esegui `init` dalla directory dell'app specifica. Il comando si interrompe senza modificare file nella radice di un'area di lavoro con `pnpm-workspace.yaml` o un campo `workspaces`, a meno che quest'ultimo non elenchi solo l'app stessa. * La configurazione automatica non è disponibile per le applicazioni Electron. * La chiave API e l’ID progetto non sono necessari per usare `gt-react` o `gt-next` — servono solo per chiamare l’API di General Translation. * Se la configurazione sperimentale di React non funziona per il tuo progetto, configura React manualmente usando la documentazione di [React](/docs/react/react-quickstart). * Per effettuare il provisioning delle credenziali di sviluppo, Git deve essere installato. Mantieni `.env.local` non tracciato e incluso in `.gitignore`, e usa la normale configurazione Git del tuo repository. Init rifiuta percorsi di file non sicuri e override della configurazione Git. Un collegamento simbolico deve puntare a un file regolare esistente che soddisfi gli stessi requisiti di sicurezza. Le variabili d'ambiente esistenti non correlate vengono mantenute invariate. * Esegui un solo comando di configurazione alla volta. Se non è possibile aggiornare `.env.local`, anche a causa di assegnazioni su più righe non supportate, i progetti o le chiavi appena creati potrebbero rimanere. Le modifiche precedenti alla configurazione e alle dipendenze non vengono annullate. ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.