# General Translation Overview: Uso degli agenti di coding URL: https://generaltranslation.com/it/docs/overview/for-coding-agents.mdx Docs index: https://generaltranslation.com/llms.txt Description: Come usare agenti di coding IA e LLMs con General Translation, indirizzandoli alla documentazione leggibile dalle macchine, al server MCP e alla nostra guida dell'agente pronta all'uso. 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 dell'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 oppure recupera la stessa guida direttamente da [`/AGENTS.md`](/AGENTS.md). ````markdown title="AGENTS.md" # General Translation — agent guide Instructions for AI coding agents adding [General Translation](https://generaltranslation.com) to a project. General Translation is a full-stack localization product: open-source i18n libraries plus a CLI that translate an app and its content into any language. Follow these rules when internationalizing code or wiring up translations. ## What to use Pick the package that matches the stack: - **Next.js (App Router or Pages Router)** → `gt-next` - **React (SPA, e.g. Vite)** → `gt-react` - **Vue 3** → `gt-vue` - **Node.js server** → `gt-node` - **Any JavaScript runtime, or lower-level control** → `generaltranslation` (the Core library) - **Translating content files (JSON, MDX, YAML, and more) or running translation in CI** → the `gt` CLI All of these are free and open-source. The libraries work with or without a General Translation account; an API key unlocks on-demand translation in development and the hosted translation API. ## Setup Prefer the wizard. From the project root, run: ```bash npx gt init ``` It installs the right library and the `gt` CLI, wires up the framework (for Next.js, adds `withGTConfig` and `GTProvider`), creates `gt.config.json`, and generates API credentials. For manual setup, install the packages yourself: ```bash npm install gt-next # or gt-react / gt-node / generaltranslation npm install -D gt ``` Then create `gt.config.json` in the project root — this is the single source of truth for locales: ```json { "defaultLocale": "en", "locales": ["es", "fr", "ja"], "files": { "gt": { "output": "public/_gt/[locale].json" } } } ``` - `defaultLocale` — the language the source is written in. - `locales` — the languages to translate into. - `files.gt.output` — where the CLI writes translation files (`[locale]` is replaced per language). Add this directory to `.gitignore`; the files are generated. Set API credentials as environment variables (in `.env.local` for Next.js, `.env` otherwise): ```bash GT_API_KEY="gtx-dev-..." # gtx-dev- in development, gtx-api- in production/CI GT_PROJECT_ID="..." ``` Never commit `GT_API_KEY`, expose it to the browser, or prefix it with `NEXT_PUBLIC_`. ## Core usage Wrap user-facing JSX in ``. Write source copy directly — no translation keys needed: ```tsx import { T } from 'gt-next'; // or 'gt-react' // Everything inside is translated as a unit

Welcome to my app

; ``` Use `useGT()` for standalone strings (placeholders, `aria-label`, `alt`, button labels). `useGT()` returns the translation function directly: ```tsx import { useGT } from 'gt-next'; const gt = useGT(); // ✅ correct // const { gt } = useGT(); // ❌ wrong — useGT returns the function, not an object ; ``` In async App Router components, use `getGT` instead. `gt-next/server` does not work with the Pages Router: ```tsx import { getGT } from 'gt-next/server'; const gt = await getGT(); ``` Wrap dynamic or private values (names, emails, IDs) in `` so they are not translated and never sent to the API. Use ``, ``, and `` for values that should be reformatted but not translated: ```tsx import { T, Var } from 'gt-next'; // Generates one translation, keeps the name unchanged Hello, {name}! ; ``` For Node.js servers, initialize once and resolve translations per request: ```js import { initializeGT, withGT, getGT } from 'gt-node'; initializeGT({ defaultLocale: 'en', locales: ['en', 'es', 'fr'] }); // racchiudi gli handler in withGT(locale, ...); poi `const gt = await getGT()` al loro interno ``` Mantieni tutta la configurazione delle lingue in `gt.config.json` — non disseminare elenchi di lingue nel 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` (lingue 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 l'API di General Translation. Eseguilo in CI **prima** della build per la produzione; aggiungi `--save-local` solo quando le modifiche locali devono essere sincronizzate per prime. | | `npx gt generate` | Per creare modelli di file di traduzione da tradurre manualmente (non serve una chiave API). | | `npx gt api --spec` | Per esaminare il contratto OpenAPI incluso nella CLI installata. | | `npx gt api ` | Per effettuare una richiesta API grezza autenticata da uno script o dal terminale. | | `npx gt project create --org-id --name --default-locale ` | Per creare un progetto con una chiave di organizzazione. | | `npx gt project status ` | Per esaminare un job di traduzione o di generazione del contesto del progetto. | Aggiungi la traduzione alla build di produzione affinché le traduzioni restino aggiornate, per esempio: `"build": "npx gt translate && next build"`. ## Regole — cosa fare e cosa non fare Da fare: - Racchiudi in `` ogni nuovo testo rivolto agli utenti (o usa `useGT()`/`getGT()` per le stringhe autonome) mentre lo scrivi. - Esegui `npx gt translate` prima di fare commit o build per la produzione, così i nuovi testi vengono tradotti. - Mantieni l'elenco delle lingue solo in `gt.config.json`. - Racchiudi i valori dinamici e privati in `` e aggiungi `context` quando una stringa è ambigua. - Dopo aver modificato deliberatamente un file di traduzione generato, esegui `npx gt save-local` prima di scaricare nuovamente le traduzioni, oppure passa `--save-local` alla successiva esecuzione della traduzione. Da non fare: - Inserire stringhe già tradotte direttamente nel sorgente, o aggiungere rami `if`/`switch` per lingua — traduci invece il testo sorgente. - Modificare i file di traduzione generati senza sincronizzare le modifiche: un download successivo può sovrascrivere le modifiche non salvate. - Fare il commit di `GT_API_KEY` o esporla al client. - Duplicare la configurazione delle lingue al di fuori di `gt.config.json`. ## Link - [`llms.txt`](/llms.txt) — curated machine-readable docs entry point. - [`llms-index.txt`](/llms-index.txt) — exhaustive index of every docs page. - [`llms-full.txt`](/llms-full.txt) — full docs content for tools that can load a larger context. - [React index](/docs/react/llms.txt), [CLI index](/docs/cli/llms.txt), and [OpenAPI index](/docs/platform/openapi/llms.txt) — focused entry points for common tasks. - [`AGENTS.md`](/AGENTS.md) — this drop-in guide as raw Markdown. - [`openapi.yaml`](/openapi.yaml) — canonical General Translation API specification. - [`sitemap.md`](/sitemap.md) — Markdown index of every docs page and blog post. - [`sitemap.xml`](/sitemap.xml) — standard sitemap for every published page. - Quickstarts: [React](/docs/react/react-quickstart), [Vue](/docs/vue/quickstart), [Node](/docs/node/quickstart), [Core library](/docs/platform/core/quickstart), and the [CLI](/docs/cli/quickstart). - [Key concepts](/docs/overview/key-concepts) — locales, context, and static vs. dynamic content. - CLI reference: [`gt api`](/docs/cli/reference/commands/api), [`gt project create`](/docs/cli/reference/commands/project-create), and [`gt project status`](/docs/cli/reference/commands/project-status). ```` ## Indirizza gli agenti alla documentazione [#point-agents] Fornisci al tuo agente accesso diretto alla documentazione, così le sue risposte restano accurate. General Translation pubblica diversi entry point leggibili dalle macchine nella radice del sito e sotto `/docs` sull'host della documentazione: * [`llms.txt`](/llms.txt) — un entry point curato in stile [llmstxt.org](https://llmstxt.org/) con le Quickstart principali e indici mirati. * [`llms-index.txt`](/llms-index.txt) — l'indice esaustivo dei link a ogni pagina pubblicata della documentazione. * [`llms-full.txt`](/llms-full.txt) — l'intero contenuto della documentazione in un unico file, esclusa la reference OpenAPI generata. * [`AGENTS.md`](/AGENTS.md) — la guida pronta all'uso qui sopra in Markdown non elaborato. * [`sitemap.md`](/sitemap.md) — un indice in Markdown di ogni pagina della documentazione e di ogni post del blog. * [`sitemap.xml`](/sitemap.xml) — la sitemap XML standard di ogni pagina pubblicata. Usa un indice circoscritto quando l'agente sa già di quale parte del prodotto ha bisogno: * [Overview](/docs/overview/llms.txt) * [Platform](/docs/platform/llms.txt), con indici mirati per [Dashboard](/docs/platform/dashboard/llms.txt), [Locadex](/docs/platform/locadex/llms.txt), [Core](/docs/platform/core/llms.txt) e [OpenAPI](/docs/platform/openapi/llms.txt) * [CLI](/docs/cli/llms.txt) * [React](/docs/react/llms.txt) * [Vue](/docs/vue/llms.txt) * [Node.js](/docs/node/llms.txt) * [Python](/docs/python/llms.txt) * [Integrations](/docs/integrations/llms.txt) Per lavorare con le API, usa il [bundle delle operazioni OpenAPI](/docs/platform/openapi/llms-full.txt) o la specifica canonica [`openapi.yaml`](/openapi.yaml) invece di estrarre i contenuti dalle pagine interattive degli endpoint. L'host della documentazione serve anche i file di radice sotto `/docs`, inclusi `/docs/llms.txt`, `/docs/llms-index.txt` e `/docs/llms-full.txt`. Ogni pagina della documentazione è disponibile come **Markdown non elaborato**: aggiungi `.md` o `.mdx` all'URL di qualsiasi pagina per ottenere il sorgente pulito senza dover analizzare l'HTML renderizzato. Gli indici generati e i metadati di discovery usano `.mdx`, ad esempio `/docs/cli/quickstart.mdx`. Per aggiungere la documentazione come context, incolla un URL della documentazione o il link `llms.txt` nel context del tuo agente, oppure aggiungi la documentazione come sorgente negli strumenti che supportano l'indicizzazione della documentazione. ## server MCP [#mcp] Usa il package pubblicato [`@generaltranslation/mcp`](https://www.npmjs.com/package/@generaltranslation/mcp) quando il tuo agente ha bisogno della documentazione tramite una connection [Model Context Protocol](https://modelcontextprotocol.io) (MCP) locale su standard input e output: ```json title=".mcp.json" { "mcpServers": { "generaltranslation-docs": { "command": "npx", "args": ["-y", "@generaltranslation/mcp@latest"] } } } ``` Il package fornisce strumenti per elencare e recuperare la documentazione. Per un accesso più semplice alla documentazione, indirizza il tuo agente direttamente alla [documentazione leggibile dalle macchine](#point-agents). Per informazioni sul progetto in tempo reale, usa il server MCP ospitato all'indirizzo `https://api.gtx.dev/mcp`. Utilizza streamable HTTP. Il server ospitato fornisce anche [strumenti MCP per Google Drive](/docs/integrations/google-drive/reference/mcp-tools) per trovare i progetti collegati, tradurre Google Docs e Google Slides ed eseguire il polling dello stato di avanzamento delle copie tradotte. Aggiungi la connection al config file MCP del tuo strumento (ad esempio, `.mcp.json`). I nomi dei trasporti e i campi di configurazione possono variare a seconda del client: ```json title=".mcp.json" { "mcpServers": { "generaltranslation": { "type": "http", "url": "https://api.gtx.dev/mcp" } } } ``` ### Autenticarsi con l'API remota Connettiti tramite il flusso di accesso OAuth del tuo client MCP, oppure configura `Authorization: Bearer ` utilizzando le sue impostazioni dell'header segreto. Le connessioni con chiave API accettano chiavi di progetto di produzione (`gtx-api-`), chiavi di progetto di sviluppo (`gtx-dev-`) e chiavi di organizzazione (`gtx-org-`). Ogni strumento decide se le chiavi di sviluppo sono ammesse: la runtime translation e gli [strumenti MCP di Google Drive](/docs/integrations/google-drive/reference/mcp-tools) le accettano, mentre altri strumenti possono rifiutarle. Il server espone i metadati della risorsa protetta e dell'authorization server. Un client compatibile con OAuth si registra dinamicamente, utilizza il flusso Authorization Code con Proof Key for Code Exchange (PKCE) e apre la schermata di consenso della Dashboard. Richiedi `openid` e `profile` per i claim di identità e richiedi `offline_access` quando il client necessita di un refresh token. Usa `list_projects` per trovare un ID progetto, quindi passalo come `projectId` agli strumenti del progetto. Una chiave di progetto di produzione può omettere `projectId` per utilizzare il proprio progetto. Una volta effettuata la connessione, chiedi al tuo agente di utilizzare il server MCP `generaltranslation`. Prova con: «Elenca i miei progetti e mostra le impostazioni di impostazione regionale di uno di essi». ## 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 "usare lo strumento `generaltranslation`". Aggiungi la documentazione come sorgente oppure fai riferimento a `/llms.txt` nel prompt. * **Claude Code** — legge automaticamente un file `CLAUDE.md` nella radice, quindi copia la [guida dell'agente](#agent-guide) nel file `CLAUDE.md` del tuo progetto. Registra il server MCP e chiedigli di "usare il server MCP `generaltranslation`". * **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'intervento umano. Usa questa suddivisione: * **Affida all'agente:** racchiudere il testo visibile agli utenti in [``](/docs/react/reference/components/t), aggiungere [`useGT()`](/docs/react/reference/hooks/use-gt) per le stringhe standalone, impostare `gt.config.json` ed eseguire [`npx gt init`](/docs/cli/reference/commands/init). * **Verifica manualmente:** il [contesto di traduzione](/docs/overview/key-concepts#context) (Glossario e prompt personalizzati) scritto dall'agente, la configurazione delle impostazioni regionali (`defaultLocale` e `locales`) e che i valori dinamici o privati siano racchiusi in [``](/docs/react/reference/components/var). * **Non lasciare mai all'agente:** la modifica dei file di traduzione generati senza sincronizzare le modifiche o l'inserimento nel codice di stringhe già tradotte invece di tradurre il testo sorgente con la CLI. ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.