# General Translation Integrations: Guida rapida URL: https://generaltranslation.com/it/docs/integrations/sanity/quickstart.mdx Docs index: https://generaltranslation.com/llms.txt Description: Installa gt-sanity, aggiungi il plugin di General Translation a Sanity Studio e traduci il tuo primo documento. Il plugin `gt-sanity` traduce i documenti direttamente da Sanity Studio. Supporta la localizzazione a livello di documento e a livello di campo; questa Guida rapida usa la configurazione predefinita a livello di documento, in cui ogni traduzione è un documento separato con un campo `language` e un documento `translation.metadata` gestito da `@sanity/document-internationalization`. ## Prima di iniziare [#before-start] Ti servono: * Sanity Studio 6.9.2 o successivo. Gli Studio con Sanity dalla versione 6.0 alla 6.8 usano ancora la generazione 3 di `@sanity/ui` e devono rimanere su `gt-sanity` 3.1.x. * React 19.2.0 o successivo. * Node.js 22.12 o successivo. * Un progetto Sanity esistente. * Un [ID progetto](/docs/platform/dashboard/get-started) di General Translation e una [chiave API](/docs/platform/dashboard/reference/api-keys) per la produzione. ## Guida rapida [#quickstart] ### 1. Installa `gt-sanity` [#install] Installa il plugin nel progetto Sanity Studio. `gt-sanity` risolve `@sanity/ui`, `@sanity/icons`, `@sanity/schema` e `@sanity/mutator` dallo Studio come dipendenze peer, in modo che nell'albero rimanga un'unica copia di ciascun singleton del runtime di Studio. Uno Studio Sanity 6.9.2+ fornisce già tutti e quattro. ```bash npm install gt-sanity ``` ```bash yarn add gt-sanity ``` ```bash bun add gt-sanity ``` ```bash pnpm add gt-sanity ``` ### 2. Aggiungi il plugin [#add-plugin] Aggiungi `gtPlugin` a `sanity.config.ts`. Imposta l'impostazione regionale sorgente, le impostazioni regionali di destinazione e i tipi di documento da tradurre. ```ts title="sanity.config.ts" import { defineConfig } from 'sanity'; import { gtPlugin } from 'gt-sanity'; export default defineConfig({ // ... la tua configurazione esistente plugins: [ gtPlugin({ sourceLocale: 'en', locales: ['es', 'zh', 'ja'], translateDocuments: [{ type: 'article' }, { type: 'page' }], }), ], }); ``` Quando `translateDocuments` include tipi di documento, il plugin aggiunge automaticamente il plugin `@sanity/document-internationalization`: badge di lingua, un menu di traduzione nella barra degli strumenti del documento e modelli di documento per ogni lingua. Imposta `showDocumentInternationalization: false` per disattivarlo. ### 3. Aggiungi un language field [#language-field] Ogni tipo di documento che traduci con la localizzazione a livello di documento deve avere un language field. Per impostazione predefinita si chiama `language`. ```ts title="schema/article.ts" import { defineField, defineType } from 'sanity'; export const articleType = defineType({ name: 'article', title: 'Article', type: 'document', fields: [ // ... i tuoi campi esistenti defineField({ name: 'language', type: 'string', readOnly: true, hidden: true, }), ], }); ``` Se imposti un [`languageField`](/docs/integrations/sanity/reference/plugin-configuration#language-field) personalizzato nelle opzioni del plugin, usa quel nome nel tuo schema anziché `language`. ### 4. Salva le credenziali [#credentials] Il plugin legge la tua chiave API di General Translation e l'ID progetto da un documento privato di Sanity. Crea un file temporaneo `populateSecrets.js` nella cartella del tuo Studio. ```js title="populateSecrets.js" import { getCliClient } from 'sanity/cli'; const client = getCliClient({ apiVersion: '2025-09-15' }); client.createOrReplace({ // Il `.` iniziale in questo _id mantiene il documento privato, // anche in un dataset pubblico. _id: 'generaltranslation.secrets', _type: 'generaltranslationSettings', secret: process.env.GT_API_KEY, project: process.env.GT_PROJECT_ID, }); ``` Esegui lo script con le tue credenziali: ```bash GT_API_KEY=your-api-key GT_PROJECT_ID=your-project-id npx sanity exec populateSecrets.js --with-user-token ``` Il documento `_id` deve corrispondere al `secretsNamespace` del plugin (impostazione predefinita: `generaltranslation.secrets`). Il plugin legge il campo `secret` come chiave API e il campo `project` come ID progetto. Verifica che il documento esista con lo strumento Vision nel tuo Studio: ```text *[_id == 'generaltranslation.secrets'] ``` Se utilizzi più dataset, ripeti questa operazione per ognuno di essi. Dopo aver verificato, elimina `populateSecrets.js`. Un `.` iniziale esclude questo documento dalle query non autenticate su dataset pubblici, ma l'accesso autenticato a Studio segue comunque i ruoli del tuo progetto Sanity. Usa il [controllo degli accessi basato sui ruoli di Sanity](https://www.sanity.io/docs/access-control) affinché solo gli utenti che necessitano dell'integrazione possano leggere il dataset e non eseguire mai il commit dello script o delle credenziali. ### 5. Tradurre un documento [#translate-document] 1. Apri un documento nella lingua sorgente in Sanity Studio. 2. Fai clic su **Traduci** nella barra delle azioni del documento. 3. Seleziona le impostazioni regionali di destinazione. 4. Fai clic su **Traduci**. Con questa configurazione a livello di documento, il plugin controlla periodicamente se le traduzioni sono state completate e le importa automaticamente come bozze. La correzione dei riferimenti e la pubblicazione sono disattivate per impostazione predefinita; usa i controlli della finestra di dialogo oppure configura il loro stato iniziale con [`autoPatchReferences`](/docs/integrations/sanity/reference/plugin-configuration#auto-patch-references) e [`autoPublish`](/docs/integrations/sanity/reference/plugin-configuration#auto-publish). Esamina i documenti importati nella prospettiva **Bozze** di Sanity, quindi pubblicali prima di eseguire query da un frontend che usa solo contenuti pubblicati. (Consulta le guide complete per [tradurre i contenuti](/docs/integrations/sanity/guides/translating-content) e [gestire le traduzioni](/docs/integrations/sanity/guides/managing-translations)). ### 6. Esegui query sui contenuti tradotti [#query-content] Con questa configurazione a livello di documento, le traduzioni sono archiviate come documenti separati con un campo language. Per recuperare i contenuti tradotti, filtra in base al campo language. ```text // Per impostazione predefinita, i documenti nella lingua sorgente non impostano il campo language *[_type == "article" && !defined(language)]{ title, slug, body } ``` ```text // Recupera gli articoli in spagnolo *[_type == "article" && language == "es"]{ title, slug, body } ``` (Per altri pattern di query, vedi [Interrogare le traduzioni](/docs/integrations/sanity/guides/querying-translations)). ## Next steps - /docs/integrations/sanity/guides/translating-content - /docs/integrations/sanity/guides/managing-translations - /docs/integrations/sanity/guides/querying-translations - /docs/integrations/sanity/guides/configuring-sanity ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.