# General Translation Overview: Uso degli agenti di coding
URL: https://generaltranslation.com/it/docs/overview/for-coding-agents.mdx
---

title: Uso degli agenti di coding
description: Come usare agenti di coding IA e LLMs con General Translation, indirizzandoli alla documentazione in formato leggibile dalle macchine, al server MCP e alla nostra guida pronta all'uso per agenti.

---

General Translation è progettato per funzionare con agenti di coding IA e LLMs. Le librerie sono open-source, la configurazione è prevedibile e la documentazione è pubblicata in formati leggibili dalle macchine. Un agente come Cursor, Claude Code o Copilot può aggiungere ed eseguire General Translation per te con un contesto accurato e aggiornato.

*Per una localizzazione completamente automatizzata che apra pull request in autonomia, usa invece il nostro agente dedicato [Locadex](/docs/platform/locadex/quickstart) anziché affidarti a un agente personalizzato.*

## Guida rapida per agente [#agent-guide]

Fornisci al tuo agente tutto ciò di cui ha bisogno con un solo copia e incolla. Copia la guida qui sotto in un file `AGENTS.md` (o `CLAUDE.md`, una regola di Cursor o il file di istruzioni del tuo strumento) nella radice del progetto e il tuo agente aggiungerà ed eseguirà General Translation correttamente. Usa il pulsante Copia nell'angolo in alto a destra del blocco.

````markdown title="AGENTS.md"
# General Translation — agent guide

Istruzioni per gli agenti di codifica AI che aggiungono [General Translation](https://generaltranslation.com) a un progetto. General Translation è un prodotto di localizzazione full-stack: librerie i18n open-source più una CLI che traducono un'app e i suoi contenuti in qualsiasi lingua. Segui queste regole quando internazionalizzi il codice o configuri le traduzioni.

## Cosa usare

Scegli il pacchetto adatto allo stack:

- **Next.js (App Router or Pages Router)** → `gt-next`
- **React (SPA, e.g. Vite)** → `gt-react`
- **Node.js server** → `gt-node`
- **Qualsiasi runtime JavaScript, o controllo di basso livello** → `generaltranslation` (la libreria Core)
- **Traduzione di file di contenuto (JSON, MDX, YAML e altro) o esecuzione della traduzione in CI** → la CLI `gt`

Tutti questi pacchetti sono gratuiti e open-source. Le librerie funzionano con o senza un account General Translation; una chiave API sblocca la traduzione su richiesta in sviluppo e la translation API ospitata.

## Configurazione

Preferisci la procedura guidata. Dalla radice del progetto, esegui:

```bash
npx gt init
```

Installa la libreria corretta e la CLI `gt`, configura il framework (per Next.js, aggiunge `withGTConfig` e `GTProvider`), crea `gt.config.json` e genera le credenziali API.

Per la configurazione manuale, installa i pacchetti direttamente:

```bash
npm install gt-next   # or gt-react / gt-node / generaltranslation
npm install -D gt
```

Poi crea `gt.config.json` nella radice del progetto — è l'unica fonte di verità per le impostazioni regionali:

```json
{
  "defaultLocale": "en",
  "locales": ["es", "fr", "ja"],
  "files": { "gt": { "output": "public/_gt/[locale].json" } }
}
```

- `defaultLocale` — la lingua in cui è scritto il sorgente.
- `locales` — le lingue in cui tradurre.
- `files.gt.output` — dove la CLI scrive i file di traduzione (`[locale]` viene sostituito per ogni lingua). Aggiungi questa directory a `.gitignore`; i file sono generati automaticamente.

Imposta le credenziali API come variabili d'ambiente (in `.env.local` per Next.js, altrimenti `.env`):

```bash
GT_API_KEY="gtx-dev-..."   # gtx-dev- in development, gtx-api- in production/CI
GT_PROJECT_ID="..."
```

Non eseguire mai il commit di `GT_API_KEY`, non esporla al browser e non anteporle il prefisso `NEXT_PUBLIC_`.

## Utilizzo di base

Racchiudi il JSX rivolto all'utente in `<T>`. Scrivi il testo sorgente direttamente — non servono chiavi di traduzione:

```tsx
import { T } from 'gt-next'; // or 'gt-react'

// Tutto ciò che è dentro <T> viene tradotto come un'unità
<T>
  <h1>Welcome to my app</h1>
</T>;
```

Usa `useGT()` per le stringhe autonome (segnaposto, `aria-label`, `alt`, etichette dei pulsanti). `useGT()` restituisce direttamente la funzione di traduzione:

```tsx
import { useGT } from 'gt-next';

const gt = useGT(); // ✅ correct
// const { gt } = useGT(); // ❌ sbagliato — useGT restituisce la funzione, non un oggetto

<input placeholder={gt('Search products')} />;
```

Nei componenti async App Router, usa invece `getGT`. `gt-next/server` non funziona con il Pages Router:

```tsx
import { getGT } from 'gt-next/server';

const gt = await getGT();
```

Racchiudi i valori dinamici o privati (nomi, email, ID) in `<Var>` in modo che non vengano tradotti e non vengano mai inviati all'API. Usa `<Currency>`, `<DateTime>` e `<Num>` per i valori che devono essere riformattati ma non tradotti:

```tsx
import { T, Var } from 'gt-next';

// Genera una traduzione, mantiene il nome invariato
<T>
  Hello, <Var>{name}</Var>!
</T>;
```

Per i server Node.js, inizializza una volta sola e risolvi le traduzioni per ogni richiesta:

```js
import { initializeGT, withGT, getGT } from 'gt-node';

initializeGT({ defaultLocale: 'en', locales: ['en', 'es', 'fr'] });
// racchiudi gli handler in withGT(locale, ...); poi usa `const gt = await getGT()` al loro interno
```

Mantieni tutta la configurazione delle impostazioni regionali in `gt.config.json` — non disperdere gli elenchi di locales nella base di codice.

## Comandi

| Comando | Quando eseguirlo |
| --- | --- |
| `npx gt init` | Una volta sola, per configurare un progetto (installa le dipendenze, configura il framework, crea `gt.config.json`, genera le credenziali). |
| `npx gt configure` | Per creare o aggiornare `gt.config.json` (impostazioni regionali e file) senza la procedura guidata completa. |
| `npx gt auth` | Per generare o aggiornare le credenziali API. |
| `npx gt translate` | Per tradurre il progetto tramite la General Translation API. Esegui in CI **prima** della build per la produzione. |
| `npx gt generate` | Per creare template di file di traduzione da tradurre manualmente (non è necessaria una chiave API). |

Aggiungi la traduzione alla build di produzione per mantenere le traduzioni aggiornate, ad esempio: `"build": "npx gt translate && next build"`.

## Regole — cosa fare e cosa non fare

Da fare:

- Racchiudi ogni nuovo testo rivolto all'utente in `<T>` (o `useGT()`/`getGT()` per le stringhe autonome) man mano che lo scrivi.
- Esegui `npx gt translate` prima di eseguire il commit o la build per la produzione, in modo che il nuovo testo venga tradotto.
- Mantieni l'elenco delle impostazioni regionali solo in `gt.config.json`.
- Racchiudi i valori dinamici e privati in `<Var>` e aggiungi `context` quando una stringa è ambigua.

Da non fare:

- Non inserire stringhe già tradotte nel sorgente, né aggiungere rami `if`/`switch` per lingua — traduci invece il testo sorgente.
- Non modificare manualmente i file di traduzione generati (la CLI li sovrascrive).
- Non eseguire il commit di `GT_API_KEY` né esporla al client.
- Non duplicare la configurazione delle impostazioni regionali al di fuori di `gt.config.json`.

## Link

- [`llms.txt`](/llms.txt) — indice della documentazione, breve e leggibile da macchina.
- [`sitemap.md`](/sitemap.md) — mappa di tutte le pagine della documentazione.
- Quickstart: [React](/docs/react/react-quickstart), [Node](/docs/node/quickstart), [libreria Core](/docs/platform/core/quickstart) e la [CLI](/docs/cli/quickstart).
- [Concetti chiave](/docs/overview/key-concepts) — impostazioni regionali, contesto e contenuto statico vs. dinamico.
````

## Indirizza gli agenti alla documentazione [#point-agents]

Fornisci al tuo agente l&#39;accesso diretto alla documentazione, così le sue risposte resteranno accurate. General Translation pubblica diversi punti di accesso leggibili dalle macchine nella radice del sito:

* [`llms.txt`](/llms.txt) — un breve indice della documentazione in stile [llmstxt.org](https://llmstxt.org/).
* [`sitemap.md`](/sitemap.md) — una mappa con link a tutte le pagine nell&#39;ordine di navigazione.

Ogni pagina della documentazione è disponibile anche come **Markdown non elaborato**: aggiungi `.md` a qualsiasi URL di pagina (ad esempio `/docs/cli/quickstart.md`) per ottenere il sorgente pulito invece di analizzare l&#39;HTML renderizzato.

Per aggiungere la documentazione come contesto, incolla un URL della documentazione o il link a `llms.txt` nel contesto del tuo agente, oppure aggiungi la documentazione come sorgente negli strumenti che supportano l&#39;indicizzazione della documentazione.

## Server MCP [#mcp]

General Translation offre un server [Model Context Protocol](https://modelcontextprotocol.io) (MCP) che consente agli agenti di interrogare direttamente la documentazione. È disponibile in due forme:

* **Locale (stdio)** — il pacchetto npm pubblicato [`@generaltranslation/mcp`](https://www.npmjs.com/package/@generaltranslation/mcp), da eseguire sulla tua macchina con `npx`. Ideale per gli strumenti che mantengono una connessione persistente, come Cursor e Claude Code.
* **Remoto (HTTP/SSE)** — un endpoint ospitato su `https://mcp.gtx.dev`. Usa l&#39;endpoint SSE solo se il tuo strumento non supporta HTTP in streaming.

Configura la connessione usando il trasporto supportato dal tuo strumento. La struttura della configurazione è identica per tutti gli strumenti: aggiungila al file di configurazione MCP del tuo strumento (ad esempio, `.mcp.json`):

<Tabs items={['Locale', 'HTTP in streaming', 'SSE']}>
  <Tab value="Locale">
    ```json title=".mcp.json"
    {
      "mcpServers": {
        "generaltranslation": {
          "command": "npx",
          "args": ["-y", "@generaltranslation/mcp@latest"]
        }
      }
    }
    ```
  </Tab>

  <Tab value="HTTP in streaming">
    ```json title=".mcp.json"
    {
      "mcpServers": {
        "generaltranslation": {
          "type": "streamable-http",
          "url": "https://mcp.gtx.dev"
        }
      }
    }
    ```
  </Tab>

  <Tab value="SSE">
    ```json title=".mcp.json"
    {
      "mcpServers": {
        "generaltranslation": {
          "type": "sse",
          "url": "https://mcp.gtx.dev/sse"
        }
      }
    }
    ```
  </Tab>
</Tabs>

Una volta connesso, chiedi al tuo agente di usare il server MCP `generaltranslation`. *Esempio: &quot;Usa il server MCP generaltranslation per spiegare come usare un componente [`<T>`](/docs/react/reference/components/t).&quot;*

## Suggerimenti specifici per gli editor [#editor-tips]

La maggior parte della configurazione è uguale per tutti gli agenti; questi sono i pochi punti in cui le indicazioni cambiano.

* **Cursor** — registra il server MCP, poi chiedigli di &quot;usare lo strumento `generaltranslation`&quot;. Aggiungi la documentazione come sorgente oppure fai riferimento a `/llms.txt` nel prompt.
* **Claude Code** — legge automaticamente un file `AGENTS.md` nella radice, quindi basta inserire la [guida dell&#39;agente](#agent-guide) nel file `AGENTS.md` del tuo progetto per prepararlo. Registra il server MCP e chiedigli di &quot;usare il server MCP `generaltranslation`&quot;.
* **Copilot** — inserisci le indicazioni valide per tutto il repo nel file delle istruzioni (ad esempio `.github/copilot-instructions.md`) e fai riferimento lì a `/llms.txt` della documentazione.

## Best practice [#best-practices]

Gli agenti sono affidabili per il lavoro meccanico di i18n, ma per la qualità della traduzione e la configurazione serve comunque l&#39;intervento umano. Usa questa suddivisione:

* **Affida all&#39;agente:** racchiudere il testo visibile agli utenti in `<T>`, aggiungere [`useGT()`](/docs/react/reference/hooks/use-gt) per le stringhe standalone, impostare `gt.config.json` ed eseguire `npx gt init`.
* **Verifica manualmente:** il [contesto di traduzione](/docs/overview/key-concepts#context) (Glossario e Direttive) scritto dall&#39;agente, la configurazione delle impostazioni regionali (`defaultLocale` e `locales`) e che i valori dinamici o privati siano racchiusi in [`<Var>`](/docs/react/reference/components/var).
* **Non lasciare mai all&#39;agente:** la modifica manuale dei file di traduzione generati o l&#39;inserimento nel codice di stringhe già tradotte invece di tradurre il testo sorgente con la CLI.