# 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: questa guida copre locales, filtri dei documenti, localizzazione a livello di campo, credenziali, campi lingua 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`. ## Aggiungi un campo lingua [#language-field] Le traduzioni 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`. ```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', }); ``` Il plugin genera tipi di schema `internationalizedArray*` da `sourceLocale` e `locales`, insieme a un'interfaccia utente integrata per la modifica di ogni impostazione regionale. Usa i tipi generati nei tuoi schemi. ```ts defineField({ name: 'title', type: 'internationalizedArrayString', }); ``` Per impostazione predefinita, il plugin genera 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' }], }, ``` 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. ## 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