# General Translation Integrations: Configurare Sanity URL: https://generaltranslation.com/it/docs/integrations/sanity/guides/configuring-sanity.mdx --- title: Configurare Sanity description: Come configurare il plugin gt-sanity di General Translation per locales, filtri dei documenti, localizzazione a livello di campo, credenziali e singleton. related: links: - /docs/integrations/sanity/guides/translating-content - /docs/integrations/sanity/guides/managing-translations - /docs/integrations/sanity/guides/querying-translations --- Configura il funzionamento di General Translation in Sanity Studio con la funzione `gtPlugin`. Questa guida illustra le opzioni più comuni. Per l'elenco completo, consulta il [riferimento della configurazione del plugin](/docs/integrations/sanity/reference/plugin-configuration). ## Aggiungi il plugin [#add-plugin] Aggiungi `gtPlugin` alla configurazione di Studio. Questo passaggio è descritto anche nel [Quickstart](/docs/integrations/sanity/quickstart). ```ts title="sanity.config.ts" import { defineConfig } from 'sanity'; import { gtPlugin } from 'gt-sanity'; export default defineConfig({ plugins: [ gtPlugin({ sourceLocale: 'en', locales: ['es', 'zh', 'ja'], translateDocuments: [{ type: 'article' }, { type: 'page' }], }), ], }); ``` ## Imposta le impostazioni regionali di origine e di destinazione [#set-locales] Usa `sourceLocale` per la lingua sorgente e `locales` per le lingue di destinazione. ```ts gtPlugin({ sourceLocale: 'en', locales: ['es', 'zh', 'ja'], }); ``` Se hai già un `gt.config.json`, puoi includerlo nella configurazione del plugin con lo spread. `defaultLocale` è accettato anche come alias di `sourceLocale`. ```ts title="sanity.config.ts" import gtConfig from './gt.config.json'; gtPlugin({ ...gtConfig, }); ``` L'impostazione regionale sorgente viene determinata in questo ordine: `sourceLocale`, poi `defaultLocale`, poi il valore predefinito della libreria. Se sono impostati sia `sourceLocale` sia `defaultLocale`, prevale `sourceLocale`. Il plugin rimuove l'impostazione regionale sorgente e le voci duplicate da `locales`, quindi un file `gt.config.json` condiviso può includere in sicurezza l'impostazione regionale predefinita. ## Aggiungi un campo lingua [#language-field] Le traduzioni a livello di documento sono archiviate come documenti separati. Il plugin usa un campo lingua per registrare l'impostazione regionale di ciascun documento. Per impostazione predefinita, il campo si chiama `language`. La localizzazione a livello di campo non usa questo campo. ```ts title="schema/article.ts" import { defineField, defineType } from 'sanity'; export const articleType = defineType({ name: 'article', title: 'Article', type: 'document', fields: [ defineField({ name: 'language', type: 'string', readOnly: true, hidden: true, }), ], }); ``` Per usare un nome di campo diverso, imposta `languageField` e usa lo stesso nome nello schema. ```ts gtPlugin({ sourceLocale: 'en', locales: ['es', 'zh', 'ja'], languageField: 'locale', }); ``` ## Scegli quali documenti tradurre [#choose-documents] Usa `translateDocuments` per filtrare i documenti che possono essere tradotti. Accetta filtri per tipo di documento, filtri per ID documento oppure stringhe abbreviate del tipo. ```ts // Per tipo di documento gtPlugin({ sourceLocale: 'en', locales: ['es', 'zh', 'ja'], translateDocuments: [{ type: 'page' }, { type: 'post' }], }); ``` ```ts // Per ID documento specifico gtPlugin({ sourceLocale: 'en', locales: ['es', 'zh', 'ja'], translateDocuments: [{ documentId: 'homepage' }, { documentId: 'about-page' }], }); ``` ```ts // Stringhe di tipo in forma abbreviata gtPlugin({ sourceLocale: 'en', locales: ['es'], translateDocuments: ['article', 'page'], }); ``` Le voci di tipo stringa sono trattate come `{ type: '' }`. `showDocumentInternationalization` usa le voci `type` per stabilire quali tipi di schema ricevono badge di lingua e template, quindi per abilitare queste funzionalità sono necessari filtri per i tipi di documento. ## Configura la localizzazione a livello di campo [#field-level] Per impostazione predefinita, `gt-sanity` traduce a livello di documento, creando un documento per ogni impostazione regionale. La localizzazione a livello di campo memorizza il valore di ogni impostazione regionale nello stesso documento sotto forma di array internazionalizzato (`[{ _key, _type, language, value }]` — con la stessa struttura di [`sanity-plugin-internationalized-array`](https://github.com/sanity-io/sanity-plugin-internationalized-array), quindi non è necessaria alcuna migrazione dei dati esistenti). Abilita la generazione dello schema con `internationalizedArray` (o il relativo alias `fieldLevelLocalization`), quindi imposta `translationLevel` su `'internationalizedArray'`. ```ts gtPlugin({ sourceLocale: 'en', locales: ['es', 'zh', 'ja'], translateDocuments: [{ type: 'post' }], internationalizedArray: { enabled: true }, translationLevel: 'internationalizedArray', }); ``` La localizzazione a livello di campo è supportata da [`sanity-plugin-internationalized-array`](https://github.com/sanity-io/sanity-plugin-internationalized-array), il plugin Sanity di riferimento. `gtPlugin` lo configura a partire da `sourceLocale` e `locales`, e il plugin nativo registra i tipi di schema `internationalizedArray*` e l'interfaccia utente di modifica di Studio: i pulsanti per aggiungere lingue, le etichette delle lingue e le azioni sui campi si comportano esattamente come nel plugin autonomo. Usa i tipi registrati nei tuoi schemi. ```ts defineField({ name: 'title', type: 'internationalizedArrayString', }); ``` Per impostazione predefinita, il plugin registra i tipi `string` e `text`. Usa `fieldTypes` per aggiungere `block` (Portable Text) o definizioni di oggetti personalizzate. ```ts internationalizedArray: { enabled: true, fieldTypes: ['string', 'text', 'block', { name: 'seo', type: 'seoFields' }], }, ``` Se registri già `sanity-plugin-internationalized-array` nel tuo Studio, mantieni la configurazione esistente e lascia `internationalizedArray` non impostato, in modo che i tipi di schema vengano registrati una sola volta. Translation legge e scrive i dati memorizzati `{ _key, _type, language, value }` indipendentemente dall'istanza del plugin che ha registrato i tipi, quindi a GT basta impostare `translationLevel` (e `translateDocuments`). ```ts import { internationalizedArray } from 'gt-sanity'; plugins: [ internationalizedArray({ languages: [ { id: 'en', title: 'English' }, { id: 'es', title: 'Spanish' }, ], fieldTypes: ['string'], }), gtPlugin({ sourceLocale: 'en', locales: ['es'], translateDocuments: [{ type: 'post' }], translationLevel: 'internationalizedArray', }), ], ``` Per combinare entrambe le strategie, imposta `translationLevel` su `'mixed'` ed elenca in `fieldLevelDocuments` i tipi di documento con traduzione a livello di campo. ```ts gtPlugin({ sourceLocale: 'en', locales: ['es', 'zh', 'ja'], translateDocuments: [{ type: 'post' }, { type: 'siteSettings' }], internationalizedArray: { enabled: true }, translationLevel: 'mixed', fieldLevelDocuments: [{ type: 'siteSettings' }], }); ``` I tipi di documento localizzati in-place vengono esclusi automaticamente da `@sanity/document-internationalization`, quindi non ricevono badge di lingua né modelli di documento per singola impostazione regionale. Durante l'importazione, il plugin aggiorna solo l'impostazione regionale di destinazione nel documento sorgente e mantiene inalterate tutte le altre lingue. Consulta il [riferimento della configurazione del plugin](/docs/integrations/sanity/reference/plugin-configuration#field-level) per tutte le opzioni a livello di campo. ## Escludi i campi dalla traduzione [#exclude-fields] Contrassegna un campo nel tuo schema per escluderne il contenuto dalla traduzione. Imposta `options.gt.exclude` nella definizione del campo. ```ts title="schema/article.ts" defineField({ name: 'internalNotes', type: 'string', options: { gt: { exclude: true } }, }); ``` I campi esclusi non vengono mai inviati per la traduzione, quindi i documenti tradotti mantengono invariato il valore sorgente. L'esclusione si applica a qualsiasi livello di annidamento. Il plugin rispetta anche le opzioni di esclusione dei plugin di localizzazione standard di Sanity, quindi se il tuo schema le usa già non devi aggiungere un secondo contrassegno: * `options.documentInternationalization.exclude` di `@sanity/document-internationalization` * `options.aiAssist.exclude` di `@sanity/assist` * la proprietà di campo legacy `localize: false` Per escludere tutte le occorrenze di un tipo personalizzato, imposta l'opzione direttamente sulla definizione del tipo. ```ts title="schema/objects/legalDisclaimer.ts" export const legalDisclaimer = defineType({ name: 'legalDisclaimer', type: 'object', // Esclude questo tipo ovunque venga utilizzato options: { gt: { exclude: true } }, fields: [ defineField({ name: 'jurisdiction', type: 'string' }), defineField({ name: 'text', type: 'text' }), ], }); ``` Per le regole che selezionano i documenti in base all'ID o trasformano i valori per impostazione regionale — come la deduplicazione dello slug — usa invece le opzioni a livello di plugin [`ignoreFields`, `skipFields`, and `dedupeFields`](/docs/integrations/sanity/reference/plugin-configuration#field-matchers). ## Configura i documenti singleton [#singletons] Usa `singletons` per i documenti che esistono una sola volta per sito, come le impostazioni del sito o la navigazione. `singletonMapping` controlla come l'ID del documento del singleton tradotto viene ricavato dall'ID sorgente e dall'impostazione regionale. ```ts gtPlugin({ sourceLocale: 'en', locales: ['es', 'zh', 'ja'], singletons: ['siteSettings', 'navigation', 'footer'], singletonMapping: (sourceDocumentId, locale) => `${sourceDocumentId}-${locale}`, }); ``` Se ometti `singletonMapping`, il comportamento predefinito associa `sourceDocumentId` e `locale` a `` `${sourceDocumentId}-${locale}` `` (ad esempio, `siteSettings-es`). ## Memorizza le credenziali [#store-credentials] Il plugin legge la tua chiave API e l'ID progetto da un documento privato di Sanity il cui `_id` corrisponde a `secretsNamespace` (predefinito: `generaltranslation.secrets`). Crealo con uno script eseguito una sola volta. ```js title="populateSecrets.js" import { getCliClient } from 'sanity/cli'; const client = getCliClient({ apiVersion: '2026-04-06' }); client.createOrReplace({ _id: 'generaltranslation.secrets', _type: 'generaltranslation.secrets', secret: process.env.GT_API_KEY, project: process.env.GT_PROJECT_ID, }); ``` ```bash GT_API_KEY=your-api-key GT_PROJECT_ID=your-project-id npx sanity exec populateSecrets.js --with-user-token ``` Il campo `secret` viene usato come chiave API e il campo `project` come ID progetto. Per leggere le credenziali da un documento diverso, imposta `secretsNamespace` sull`_id` di quel documento. Puoi anche passare `apiKey` e `projectId` direttamente a `gtPlugin`, ma si consiglia di usare il documento dei segreti per evitare che le credenziali finiscano nel controllo del codice sorgente. Quando sono presenti entrambi, il documento dei segreti ha la precedenza in fase di runtime. ## Aggiungi la scheda facoltativa Translations [#translations-tab] L'azione del documento **Translate** viene aggiunta automaticamente. Per mostrare anche la scheda Translations nell'editor del documento, aggiungi `TranslationsTab` con `structureTool`. ```ts title="sanity.config.ts" import { defineConfig } from 'sanity'; import { structureTool } from 'sanity/structure'; import { gtPlugin, TranslationsTab } from 'gt-sanity'; export default defineConfig({ plugins: [ structureTool({ defaultDocumentNode: (S) => S.document().views([ S.view.form(), S.view.component(TranslationsTab).title('General Translation'), ]), }), gtPlugin({ sourceLocale: 'en', locales: ['es', 'zh', 'ja'], }), ], }); ``` ## Next steps - /docs/integrations/sanity/guides/translating-content - /docs/integrations/sanity/guides/managing-translations - /docs/integrations/sanity/guides/querying-translations