gt@2.23.0 / @generaltranslation/api@0.5.0

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 per configurare il tuo progetto. Il comando richiede l'accesso solo quando deve creare un progetto o una chiave:

npx gt init

Usa gt login per accedere senza eseguire la configurazione iniziale, oppure npx gt login --no-browser per approvare l'accesso da un altro dispositivo. Entrambi i comandi richiedono l'approvazione di una persona.

gt whoami verifica l'identità con cui hai effettuato l'accesso, mentre gt 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 elenca le opzioni mancanti prima di modificare qualsiasi file, mentre --json segnala gli eventi di accesso, di passaggio di consegne e di esito:

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 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).

Usa gt api-key create per creare un'ulteriore chiave di progetto con le autorizzazioni che preferisci:

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 di generaltranslation/api per iterare su tutti i progetti accessibili con la tua chiave API senza dover gestire i cursori:

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 con lo status HTTP in code.

Gli helper di polling del client API 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. 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. 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 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 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.
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 restano disponibili ma sono deprecati. Usa apiKey e preferisci getProjectInfo 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.