# General Translation Knowledge Base: Come si internazionalizza un'app con Cursor o Claude Code?
URL: https://generaltranslation.com/it/kb/ai-agent-i18n-setup.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Inizia con il prompt Setup for Agents di General Translation in Cursor o Claude Code, scegli una funzionalità e le lingue di destinazione, poi lascia che sia l'agente a implementare e verificare il risultato. L'accesso tramite browser, la documentazione leggibile dalle macchine e gli strumenti MCP collegano la configurazione alla traduzione e alla revisione. Usa Locadex per automatizzare la localizzazione continua tramite pull request.
Category: Internazionalizzazione
Last updated: 2026-10-21
Authors: Kevin Liu, Kevin Wu
Published: 2026-10-21

«Traduci la mia app in spagnolo» lascia aperte diverse questioni. L'agente deve mantenere la libreria già in uso? Lo spagnolo ha bisogno di un URL dedicato? Chi tradurrà i nuovi testi una volta terminata questa sessione? Stabilisci questi paletti prima di chiedergli di modificare l'applicazione.

General Translation mette a disposizione un prompt di configurazione costantemente aggiornato che guida l'agente di programmazione attraverso l'analisi del progetto, l'integrazione, la traduzione e la verifica. Parti da una singola funzionalità funzionante, poi estendi il pattern verificato all'intera base di codice.

## Video

The video is narrated in English, with English captions.

[Can an AI coding agent set up i18n for me?](https://caxecubb9c64cezv.public.blob.vercel-storage.com/films/kb-ai-agent-i18n-setup.mp4) (46 s)

General Translation lets your agent set up i18n with the prompt from Setup for Agents. The prompt has the agent run `gt login`, which you approve in your browser, and run `gt init` with a flag for every question, so the command asks nothing. Then it wraps your page in the `T` component, adds a `LocaleSelector`, runs `gt translate`, builds the app and reports what it actually verified.

## Inizia con Setup for Agents

Usa **Setup for Agents** su generaltranslation.com, oppure fornisci a Cursor o Claude Code il [prompt ufficiale per agenti](https://generaltranslation.com/agent-prompt.md). Il prompt indica all'agente di analizzare il tuo progetto e di seguire le istruzioni aggiornate per il framework. Per i progetti supportati, [`gt init`](/docs/cli/reference/commands/init) offre una configurazione sperimentale del framework; l'agente esamina l'integrazione generata, contrassegna i contenuti, genera le traduzioni e verifica l'app.

Per l'accesso locale al servizio, [`gt login`](/docs/cli/reference/commands/login) ti permette di approvare l'accesso dal browser anziché incollare una chiave API nella chat. La CLI deve comunque avere selezionato o configurato il progetto corretto. I flag di configurazione permettono di rispondere alle domande della procedura guidata senza un terminale interattivo, ma l'accesso iniziale richiede comunque la tua approvazione. Per le build non presidiate, usa credenziali con ambito limitato prelevate dall'archivio dei segreti della tua CI.

L'agente può individuare la documentazione tramite [`llms.txt`](https://generaltranslation.com/llms.txt), ottenere il sorgente pulito aggiungendo `.mdx` all'URL di una pagina della documentazione e consultare la [specifica OpenAPI](https://generaltranslation.com/openapi.yaml). La [guida per agenti di programmazione](/docs/overview/for-coding-agents) include istruzioni di progetto riutilizzabili. Queste risorse, costantemente aggiornate, mantengono la configurazione allineata alle API attuali del prodotto. L'[articolo sulla progettazione della documentazione](/blog/rewriting-our-docs) spiega come funzionano questi canali di individuazione.

## Assegna all'agente un compito circoscritto

Chiedigli di esaminare il framework, le versioni installate, il modello di rendering, le route, la configurazione i18n esistente e gli script di build. Se l'app utilizza già una libreria i18n, mantienila, a meno che la migrazione non faccia parte del compito. La CLI di GT può [tradurre i cataloghi esistenti supportati](/docs/cli/guides/generating-translations), inclusi quelli di next-intl e react-i18next.

Specifica la lingua di origine, le impostazioni locali di destinazione e la funzionalità da modificare. Includi i messaggi di validazione, i segnaposto, le etichette di accessibilità e i metadati. Scegli se distribuire le traduzioni in locale o tramite CDN e indica chi revisionerà il risultato nell'[Editor di traduzione della dashboard](/docs/platform/dashboard/guides/reviewing-translations).

## Connetti il server MCP di General Translation

Il [server Model Context Protocol (MCP)](/docs/overview/for-coding-agents#mcp) ospitato da General Translation consente al tuo agente di programmazione di consultare in tempo reale le impostazioni del progetto e di gestire il contesto di traduzione. L'agente può verificare le impostazioni regionali del progetto, leggere la terminologia condivisa e, quando l'attività lo richiede, aggiornare i termini del Glossario o i prompt personalizzati. In questo modo le modifiche al codice restano allineate alle regole di traduzione che il tuo team gestisce in General Translation.

La connessione copre l'intero flusso di lavoro di traduzione con strumenti per:

* Tradurre contenuti, caricare file sorgente, mettere in coda job di traduzione, verificarne lo stato e scaricare i risultati.
* Pubblicare le traduzioni sulla CDN o annullarne la pubblicazione.
* Individuare e creare progetti e, se autorizzato, creare chiavi API di progetto con ambito limitato.
* Gestire i gruppi di contesto, i termini del Glossario e i prompt personalizzati.

Concedi all'agente i permessi necessari per il flusso di lavoro che deve eseguire. Conserva le chiavi generate in un archivio di segreti protetto, mai nella chat o nel codice lato browser. La generazione delle traduzioni passa dal servizio ed è soggetta alla relativa tariffazione a consumo; la CLI descritta di seguito gestisce la sequenza locale di estrazione e traduzione dell'app.

In **Cursor**, aggiungi questa voce del server al file `.cursor/mcp.json` del tuo progetto, mantenendo le voci già presenti. Consulta la [configurazione MCP di Cursor](https://cursor.com/docs/mcp) per le opzioni di configurazione e autenticazione.

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "generaltranslation": {
      "url": "https://api.gtx.dev/mcp"
    }
  }
}
```

In **Claude Code**, registra lo stesso server tramite il [trasporto HTTP](https://code.claude.com/docs/en/mcp):

```bash
claude mcp add --transport http generaltranslation https://api.gtx.dev/mcp
```

Completa il flusso di accesso OAuth del client oppure configura una chiave API tramite le impostazioni dell'intestazione segreta, come descritto nella [guida all'autenticazione MCP](/docs/overview/for-coding-agents#mcp). La gestione del contesto richiede l'accesso al contesto dell'organizzazione tramite OAuth oppure una chiave di organizzazione con i relativi permessi di contesto; le chiavi di progetto non possono accedere a questi strumenti.

Inizia con una richiesta concreta: «Usa il server MCP generaltranslation per elencare i miei progetti e mostrare le impostazioni regionali del progetto che stiamo localizzando». Poi chiedi all'agente di esaminare i gruppi di contesto assegnati al progetto, che contengono i termini condivisi del Glossario e i prompt personalizzati. L'agente può usare questi termini e queste istruzioni mentre prepara la funzionalità e aggiornarli quando richiedi una modifica alla terminologia o allo stile.

Usa la documentazione del framework per integrare il codice e la CLI per i passaggi di estrazione e traduzione descritti di seguito. La connessione MCP consente all'agente di accedere al progetto live e al relativo contesto; l'app richiede comunque la configurazione dell'SDK, il contenuto tradotto e la verifica.

## Aggiungi una descrizione della funzionalità con i criteri di accettazione

Aggiungi questa descrizione al prompt di configurazione ufficiale. Sostituisci la funzionalità e le impostazioni regionali in base alle tue esigenze; l'esempio seguente usa inglese, spagnolo e francese.

```text
Internazionalizza la funzionalità project-list di questa applicazione.
Usa l'inglese come lingua di origine e lo spagnolo e il francese come lingue di destinazione.
Includi l'intestazione, il nome del proprietario, il numero di progetti, il campo di ricerca, l'etichetta visibile,
il segnaposto e il selettore della lingua. Usa traduzioni incluse localmente nel bundle e
mantieni invariati le route e i provider esistenti. Usa il server GT MCP connesso per
leggere le impostazioni del progetto e la terminologia assegnata, se consentito. Segnala eventuali
problemi di connessione o permessi mancanti. Non modificare il contesto condiviso al di fuori di questa attività.
Verifica i conteggi 0, 1 e 2, un nome contenente segni di punteggiatura, le etichette e i
segnaposto dei campi di input, il cambio di lingua, la persistenza dopo il ricaricamento e la build di produzione.
Controlla il contenuto server-rendered se questa app usa SSR. Riporta i comandi effettivamente eseguiti
e i relativi risultati, lo stato della revisione delle traduzioni e tutto ciò che non è stato testato. I modelli di origine
non sono traduzioni completate. Limita le modifiche a questa funzionalità e alla sua configurazione.
Non eseguire il deploy né il merge.
```

Definisci le regole del progetto nel meccanismo di istruzioni letto dal tuo agente. Cursor documenta le [regole di progetto e AGENTS.md](https://cursor.com/docs/rules); Claude Code documenta [CLAUDE.md e altre istruzioni di progetto](https://code.claude.com/docs/en/memory). Aggiungi alle istruzioni esistenti la libreria scelta, il locale di origine, il comando di traduzione e i controlli obbligatori. Evita di mantenere più copie parallele che rischiano di non essere più allineate.

## Esaminare un'implementazione rappresentativa

Per un'app React eseguita solo nel browser, la [Guida rapida per SPA React](/docs/react/react-spa-quickstart) configura `gt-react` prima del rendering. Questo esempio presuppone che la configurazione sia già completata e che l'output locale si trovi in `src/_gt/[locale].json`. Vengono utilizzati `gt-react@11.4.12` e la CLI `gt@2.26.5`.

Il componente seguente comprende testo statico, un valore dinamico, forme plurali e testo di input. Renderizzalo passando il numero di progetti e il nome di un proprietario forniti dalla tua applicazione.

```tsx title="src/ProjectSummary.tsx"
import { Num, Plural, T, Var, useGT } from 'gt-react';

export default function ProjectSummary({
  count,
  ownerName,
}: {
  count: number;
  ownerName: string;
}) {
  const gt = useGT();

  return (
    <section>
      <T>
        <h1>Projects for <Var>{ownerName}</Var></h1>
        <p>
          <Plural
            n={count}
            one={<>You have <Num>{count}</Num> project.</>}
            other={<>You have <Num>{count}</Num> projects.</>}
          />
        </p>
      </T>
      <label>
        <T>Search projects</T>
        <input type='search' placeholder={gt('Search projects')} />
      </label>
    </section>
  );
}
```

[`<Var>`](/docs/react/reference/components/var) mantiene invariato il nome del proprietario mentre il resto del messaggio viene tradotto; il suo valore non viene inviato all&#39;API di traduzione. [`<Plural>`](/docs/react/reference/components/plural) seleziona un ramo in base alle regole dell&#39;impostazione regionale e [`<Num>`](/docs/react/reference/components/num) formatta il conteggio. [`useGT`](/docs/react/reference/hooks/use-gt) restituisce direttamente la funzione di traduzione. L&#39;etichetta visibile racchiude l&#39;input, quindi il controllo ha sia un&#39;etichetta sia un segnaposto tradotto.

I rami `one` e `other` si riferiscono alla lingua sorgente inglese. Le traduzioni nella lingua di destinazione devono rappresentare le proprie forme plurali: non dare per scontato che, testando la coppia singolare/plurale dell&#39;inglese, siano coperte tutte le lingue. Consulta la [guida alla pluralizzazione in React](/kb/how-to-handle-plurals-in-react).

In una SPA React, la configurazione documentata con [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) carica le traduzioni prima dell&#39;avvio dell&#39;app. Il relativo [`LocaleSelector`](/docs/react/reference/components/locale-selector) salva la lingua scelta in un cookie e ricarica la pagina. I framework server-rendered hanno requisiti di configurazione diversi: segui la rispettiva guida di avvio rapido.

## Genera le traduzioni prima di valutare il risultato

Per la prova in locale, dopo aver aggiunto il componente, esegui questo comando dalla directory dell&#39;app configurata:

```bash
npx gt generate
```

[`gt generate`](/docs/cli/reference/commands/generate) crea modelli di origine senza chiamare il servizio di traduzione. Inserisci il testo tradotto nei file spagnolo e francese, mantenendo invariati le chiavi generate, i marcatori di variabile e la struttura JSX. Il fatto che esista `es.json` non significa che contenga testo in spagnolo.

Per ottenere le traduzioni dal servizio, segui la [procedura di autenticazione della CLI e di configurazione del progetto](/docs/cli/quickstart), quindi usa [`gt translate`](/docs/cli/reference/commands/translate). Autenticati tramite login dalla CLI o con una chiave API e configura separatamente l&#39;ID progetto: il login da solo non seleziona alcun progetto. Per una CI non presidiata, fornisci `GT_API_KEY` tramite le impostazioni dei segreti del provider CI, con i permessi necessari per il flusso di lavoro di traduzione. Consulta la [guida alla configurazione delle credenziali](/docs/cli/guides/configuring#credentials) e non inserire le chiavi degli strumenti nel codice eseguito nel browser. L&#39;utilizzo del servizio è a pagamento.

General Translation traduce il JSX contrassegnato tenendo conto della sua struttura e di qualsiasi contesto esplicito fornito. Aggiungi la [prop `context`](/docs/react/reference/components/t#context) per i testi ambigui e applica i [termini del Glossario e i prompt personalizzati](/docs/platform/dashboard/guides/defining-context-for-translations) condivisi del progetto per orientare la terminologia e il tono del prodotto. In questo modo, la produzione delle traduzioni segue le stesse regole di prodotto che l&#39;agente di programmazione legge tramite MCP.

Con le [traduzioni incluse localmente nel bundle](/docs/react/guides/storing-translations), prepara i file delle impostazioni regionali prima della build di Produzione. Conserva i file gestiti manualmente nel controllo di versione o nella tua pipeline di traduzione. Non escludere l&#39;unica copia delle traduzioni modificate a mano come se fosse un output usa e getta.

## Verifica la funzionalità, poi estendila

Esegui [`gt validate`](/docs/cli/reference/commands/validate) per individuare gli errori di traduzione inline supportati prima di inviare una richiesta API, quindi chiedi all&#39;agente di riportare i risultati osservati per ciascuno dei controlli seguenti.

| Controllo                                       | Risultato atteso                                                                         |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Seleziona lo spagnolo, poi il francese          | Titolo, messaggio con il conteggio, etichetta e segnaposto sono nella lingua selezionata |
| Ricarica la pagina dopo aver scelto una lingua  | La lingua selezionata viene mantenuta secondo la policy dell&#39;app                     |
| Prova i conteggi 0, 1 e 2                       | Ogni lingua applica le proprie regole del plurale e il numero resta corretto             |
| Usa un proprietario come O&#39;Connor           | Il nome rimane invariato in tutte le lingue                                              |
| Ispeziona il nome accessibile dell&#39;input    | Corrisponde all&#39;etichetta visibile tradotta                                          |
| Esegui la build di produzione e l&#39;anteprima | La funzionalità si comporta allo stesso modo con i file che verranno distribuiti         |

Nell&#39;esempio, [lo zero in francese e lo zero in inglese rientrano in categorie di plurale diverse](https://cldr.unicode.org/index/cldr-spec/plural-rules). Verifica che la frase renderizzata usi la forma corretta e conservi il conteggio.

Una volta che il pattern funziona, estendilo a una route o a una funzionalità alla volta. I revisori possono modificare le traduzioni nell&#39;[Editor di traduzione della dashboard](/docs/platform/dashboard/guides/reviewing-translations). Per invitare traduttori, PM e revisori madrelingua nei mercati di riferimento serve un piano Starter o Enterprise; entrambi includono [utenti illimitati](https://generaltranslation.com/pricing). Enterprise aggiunge anche l&#39;approvazione delle traduzioni. Se il tuo team modifica i file locali generati, abilita [`gt save-local`](/docs/cli/reference/commands/save-local) per caricare queste modifiche e riutilizzarle in seguito. Per il flusso di lavoro di revisione, consulta [revisione delle traduzioni AI](/kb/review-translations).

## Mantenere attiva la localizzazione dopo la sessione dell&#39;agente

Esegui [`gt translate` prima della build di produzione](/docs/cli/guides/generating-translations) per aggiornare le traduzioni ogni volta che il testo sorgente cambia. Il flusso di lavoro incrementale riutilizza le traduzioni corrispondenti anziché rigenerare tutti i messaggi a ogni esecuzione.

Per il lavoro continuativo senza dover gestire in prima persona un assistente di programmazione, l&#39;agente in hosting di General Translation, [Locadex](/docs/platform/locadex/guides/configuring-automations), può internazionalizzare le nuove parti della UI, generare traduzioni e sincronizzare le impostazioni regionali aggiunte o rimosse. Puoi configurare trigger su pull request, su push o manuali; le modifiche vengono proposte tramite pull request. L&#39;[auto-merge](/docs/platform/locadex/guides/auto-merging-prs) è facoltativo. Un assistente di programmazione può impostare l&#39;integrazione, mentre Locadex può mantenerla nei rilasci successivi. Locadex richiede un piano Starter o un Piano Enterprise e le sue esecuzioni vengono fatturate in base all&#39;[utilizzo](https://generaltranslation.com/pricing/usage). Per la configurazione, consulta il [riferimento sulle automazioni](/docs/platform/locadex/reference/automations), oppure [esegui la traduzione in CI](/kb/translations-in-ci) con la tua pipeline.

## Related questions

- [Come si aggiunge l'i18n a un'app Next.js con App Router?](https://generaltranslation.com/it/kb/add-i18n-to-nextjs.mdx): Inizia con gt init per configurare General Translation in un progetto App Router supportato, poi contrassegna il contenuto di origine, genera le traduzioni e verifica il cambio di lingua. gt-next mantiene i testi nel JSX insieme al contesto di traduzione; la CLI, l'editor della Dashboard e Locadex si occupano di generazione, revisione e aggiornamenti continui. Questa guida mostra anche la configurazione esplicita con file locali.
- [Posso fare i18n senza file di traduzione?](https://generaltranslation.com/it/kb/i18n-without-translation-files.mdx): Sì. Le librerie gt-react e gt-next di General Translation gestiscono l'i18n in React e Next.js senza chiavi di traduzione e senza dover mantenere un file JSON per ogni lingua. I testi restano inline nel JSX all'interno del componente `<T>` e il comando gt translate genera le traduzioni per ogni lingua durante la build, sfruttando il contesto del tuo codice. Locadex può mantenerle aggiornate tramite pull request.
- [Come si gestiscono i plurali in React?](https://generaltranslation.com/it/kb/how-to-handle-plurals-in-react.mdx): Per gestire i plurali in React, fornisci per ogni lingua una frase per ciascuna forma plurale e scegli quella corretta in base alle regole del plurale di quella lingua, dato che l'inglese ha 2 forme, il russo 4 e l'arabo 6. Il componente `<Plural>` di General Translation in gt-react e gt-next accetta le tue forme sorgente, e General Translation genera le forme necessarie per ogni lingua di destinazione.
- [Cosa fa l'agente Locadex?](https://generaltranslation.com/it/kb/what-is-locadex.mdx): Locadex è l'agente IA di General Translation che internazionalizza il codice e traduce i contenuti nel tuo repository GitHub. Le sue automazioni vengono eseguite all'apertura di una pull request, al push di un commit o quando le avvii tu, e ogni modifica arriva sotto forma di pull request.

## Previous and next questions

- Previous question: [Come si formattano numeri, date e valute per ogni impostazione regionale?](https://generaltranslation.com/it/kb/format-numbers-dates-currencies.mdx)
- Next question: [Come si revisionano e modificano le traduzioni?](https://generaltranslation.com/it/kb/review-translations.mdx)

## Sitemap

See the [Knowledge Base sitemap](https://generaltranslation.com/it/kb/sitemap.md) for every article.