# General Translation Changelog: gt 2.23.0 / @generaltranslation/api 0.5.0: Accedi e configura i progetti dalla CLI
URL: https://generaltranslation.com/it/blog/gt_v2_23_0_generaltranslation-api_v0_5_0.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Accedi, configura un progetto e crea chiavi con autorizzazioni esplicite dalla CLI, oppure esegui la configurazione in modalità headless da script e agenti.
Authors: Chenxin (Cyan) Yan
Published: 2026-09-29

`gt@2.23.0` porta direttamente nel terminale l'accesso all'account, la selezione del progetto, la creazione di chiavi con ambito limitato e una configurazione automatizzabile tramite script. I rilasci di accompagnamento `@generaltranslation/api@0.5.0` e `generaltranslation@9.5.2` introducono l'individuazione dei progetti con paginazione automatica.

## Inizia con la configurazione guidata

Esegui [`gt init`](/docs/cli/reference/commands/init) per configurare il tuo progetto. Il comando richiede l'accesso solo quando deve creare un progetto o una chiave:

```bash
npx gt init
```

Usa [`gt login`](/docs/cli/reference/commands/login) per accedere senza eseguire la configurazione iniziale, oppure [`npx gt login --no-browser`](/docs/cli/reference/commands/login#flags) per approvare l'accesso da un altro dispositivo. Entrambi i comandi richiedono l'approvazione di una persona.

[`gt whoami`](/docs/cli/reference/commands/whoami) verifica l'identità con cui hai effettuato l'accesso, mentre [`gt logout`](/docs/cli/reference/commands/logout) rimuove le credenziali di accesso salvate. Per i workflow non presidiati, usa chiavi API con ambito limitato, conservate nell'archivio dei segreti del tuo provider di CI.

## Eseguire la configurazione da script e agenti

Ogni domanda della configurazione ha un flag corrispondente. In assenza di un terminale, oppure con `--no-interactive`, [`gt init`](/docs/cli/reference/commands/init#headless) elenca le opzioni mancanti prima di modificare qualsiasi file, mentre `--json` segnala gli eventi di accesso, di passaggio di consegne e di esito:

```bash
npx gt init --no-interactive --json --defaults --locales fr es --no-dev-credentials
```

`--defaults` accetta le scelte locali consigliate, ma non crea mai progetti né chiavi.

## Scegliere un progetto e le autorizzazioni della chiave

[`gt init`](/docs/cli/reference/commands/init) può selezionare un progetto accessibile oppure crearne uno in un'Organization in cui disponi dell'autorizzazione necessaria, quindi salvarne l'ID e una chiave runtime di sviluppo in `.env.local`.

La chiave concede solo `project:translations:generate`: serve per le traduzioni runtime in locale, non per i caricamenti della CLI né per la CI. Gli eventuali valori `GT_API_KEY` già presenti restano invariati. I progetti Next.js con App Router ricevono `NEXT_PUBLIC_GT_PROJECT_ID` e `NEXT_PUBLIC_GT_DEV_API_KEY`, così anche i client component vengono tradotti in fase di sviluppo; escludi entrambi dalle build di produzione (vedi [credenziali di Next.js](/docs/react/nextjs/config#credentials)).

Usa [`gt api-key create`](/docs/cli/reference/commands/api-key-create) per creare un'ulteriore chiave di progetto con le autorizzazioni che preferisci:

```bash
npx gt api-key create --project-id your-project-id \
  --name "Runtime translations" \
  --permission project:translations:generate
```

Devi disporre delle autorizzazioni necessarie per creare chiavi e per concedere ciascuna delle autorizzazioni selezionate. Il comando mostra il segreto una sola volta: conservalo in un luogo sicuro. Per la CI, scegli le autorizzazioni richieste dall'intero workflow anziché riutilizzare questo esempio limitato alla sola generazione. Non includere mai le chiavi API nei bundle distribuiti su browser o dispositivi mobili.

## Usa chiamate API tipizzate e verifica i risultati dei job

Usa [`paginate`](/docs/platform/core/reference/api-client#pagination) di [`generaltranslation/api`](/docs/platform/core/reference/api-client) per iterare su tutti i progetti accessibili con la tua chiave API senza dover gestire i cursori:

```ts
import { listProjects, paginate } from 'generaltranslation/api';

for await (const project of paginate(listProjects, { client })) {
  console.log(project.id, project.name);
}
```

Con un client `createApiClient`, gli errori HTTP nelle chiamate `throwOnError` ora generano un [`ApiError`](/docs/platform/core/reference/api-client#api-error) con lo status HTTP in `code`.

Gli [helper di polling del client API](/docs/platform/core/reference/api-client#job-polling) consentono di attendere il termine dei job di traduzione e, in caso di timeout, restituiscono `complete: false`. Il completamento non implica che tutti i job siano andati a buon fine: verifica i risultati dei job prima di scaricare le traduzioni.

La formattazione della diagnostica è ora disponibile tramite l'entry point pubblico [`generaltranslation/diagnostics`](/docs/platform/core/reference/diagnostics). Gli strumenti possono così formattare messaggi con indicazioni operative senza importare l'intero entry point di Core.

## Aggiornamento

* **Esegui l'aggiornamento per elencare progetti e Organization.** L'API ora li restituisce in `items` anziché in `projects` o `orgs` e rifiuta i cursori emessi prima di questa modifica. Le versioni precedenti della CLI non possono elencarli in [`gt init`](/docs/cli/reference/commands/init). Chi effettua chiamate HTTP dirette o tramite SDK deve leggere `items` e ricominciare la paginazione.
* **Intercetta `ApiError` dalle chiamate che generano eccezioni.** Gli errori HTTP nelle chiamate con `throwOnError` e in [`awaitJobs`](/docs/platform/core/reference/api-client#job-polling) generano `ApiError` anziché il body della risposta decodificato. Le chiamate senza `throwOnError` continuano a restituire il body in `error`.
* **Sposta `src/gt.config.json`.** La CLI non lo legge più. Spostalo nella radice del progetto oppure passa `--config src/gt.config.json`.
* **Sostituisci `gt auth` e `--key-type`.** Usa login per l'autenticazione dell'account, init per la configurazione guidata del progetto e la creazione esplicita delle chiavi per ulteriori credenziali. [`gt configure`](/docs/cli/reference/commands/configure) non è un sostituto privo di effetti collaterali: a seconda della configurazione, può installare dipendenze ed effettuare il provisioning di credenziali.
* **Tieni separate le credenziali di runtime da quelle degli strumenti.** `GT_DEV_API_KEY` resta un'impostazione di runtime del framework. Il solo accesso non configura le credenziali dell'SDK di runtime. Le chiavi API esplicite continuano ad avere la precedenza sull'accesso salvato nella CLI; consulta [selezione delle credenziali](/docs/cli/guides/configuring#credentials).
* **Verifica le ipotesi sui nuovi tentativi.** Le richieste POST di gestione non ritentano automaticamente in caso di errori di rete o del server, ma le risposte 429 possono comunque essere ritentate se i nuovi tentativi sono abilitati. La traduzione runtime di Core non ritenta automaticamente né in caso di questi errori né di risposte 429. Evita di ripetere alla cieca la creazione di progetti o chiavi: ogni richiesta andata a buon fine crea un'ulteriore risorsa.
* **Continua a usare le API di compatibilità supportate.** Il fallback `devApiKey` di Core e [`getProjectData`](/docs/platform/core/reference/gt-class-methods/translation/get-project-data) restano disponibili ma sono deprecati. Usa `apiKey` e preferisci [`getProjectInfo`](/docs/platform/core/reference/gt-class-methods/project/project-management#get-project-info) per le nuove chiamate che recuperano le informazioni del progetto.
* **Gestisci le modifiche a validazione e risultati.** I valori non supportati per il provider del modello generano un errore prima che la richiesta venga inviata. I risultati del caricamento dei font non includono più il campo `deduped`.

## Sitemap

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