# General Translation Integrations: Configurazione del plugin Sanity URL: https://generaltranslation.com/it/docs/integrations/sanity/reference/plugin-configuration.mdx --- title: Configurazione del plugin Sanity description: Configura il plugin gt-sanity di General Translation per Sanity Studio. Riferimento API per gtPlugin. --- Configura General Translation in Sanity Studio con la funzione `gtPlugin`. Passa un unico oggetto options. ```ts title="sanity.config.ts" import { gtPlugin } from 'gt-sanity'; gtPlugin({ sourceLocale: 'en', locales: ['es', 'fr'], translateDocuments: [{ type: 'article' }], }); ``` ## Opzioni [#options] | Opzione | Descrizione | Tipo | Facoltativo | Predefinito | | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ----------- | --------------------------------------------------------- | | [`sourceLocale`](#source-locale) | Codice locale sorgente, ad esempio `en`. | `string` | Sì | `defaultLocale`, poi il valore predefinito della libreria | | [`defaultLocale`](#default-locale) | Alias di `sourceLocale`, utile per lo spreading di `gt.config.json`. | `string` | Sì | — | | [`locales`](#locales) | Codici locale di destinazione. | `string[]` | No | — | | [`customMapping`](#custom-mapping) | Mappature personalizzate dei codici locale e override delle proprietà. | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | Sì | — | | [`apiKey`](#api-key) | Chiave API di General Translation. | `string` | Sì | Documento Secrets | | [`projectId`](#project-id) | ID progetto di General Translation. | `string` | Sì | Documento Secrets | | [`secretsNamespace`](#secrets-namespace) | `_id` del documento privato contenente le credenziali. | `string` | Sì | `generaltranslation.secrets` | | [`languageField`](#language-field) | Campo del documento che memorizza l'impostazione regionale. | `string` | Sì | `language` | | [`translateDocuments`](#translate-documents) | Filtra i documenti che possono essere tradotti. | `TranslateDocumentFilter[] \| string[]` | Sì | `[]` | | [`singletons`](#singletons) | ID documento trattati come singleton. | `string[]` | Sì | `[]` | | [`singletonMapping`](#singleton-mapping) | Mappa un ID sorgente e un'impostazione regionale a un ID singleton tradotto. | `(sourceDocumentId: string, locale: string) => string` | Sì | `` `${sourceDocumentId}-${locale}` `` | | [`showDocumentInternationalization`](#show-doc-i18n) | Aggiunge automaticamente `@sanity/document-internationalization`. | `boolean` | Sì | `true` | | [`internationalizedArray`](#internationalized-array) | Configura la localizzazione a livello di campo con array internazionalizzati. | `GTFieldLevelLocalizationConfig` | Sì | — | | [`fieldLevelLocalization`](#field-level-localization) | Alias di `internationalizedArray`. | `GTFieldLevelLocalizationConfig` | Sì | — | | [`translationLevel`](#translation-level) | Consente di scegliere tra traduzione a livello di documento, di campo o mista. | `'document' \| 'internationalizedArray' \| 'mixed'` | Sì | `'document'` | | [`fieldLevelDocuments`](#field-level-documents) | Tipi di documento che usano la localizzazione a livello di campo in modalità mista. | `TranslateDocumentFilter[] \| string[]` | Sì | `[]` | | [`ignoreFields`](#ignore-fields) | Campi copiati dalla sorgente senza traduzione. | `FieldMatcher[]` | Sì | `[]` | | [`dedupeFields`](#dedupe-fields) | Campi copiati dalla sorgente e resi univoci per impostazione regionale. | `FieldMatcher[]` | Sì | `[]` | | [`skipFields`](#skip-fields) | Campi rimossi dai documenti tradotti. | `FieldMatcher[]` | Sì | `[]` | | [`additionalStopTypes`](#additional-stop-types) | Tipi di schema aggiuntivi da mantenere senza tradurli. | `string[]` | Sì | `[]` | | [`additionalSerializers`](#additional-serializers) | Serializzatori HTML personalizzati per mark e tipi di blocco. | `Partial` | Sì | `{}` | | [`additionalDeserializers`](#additional-deserializers) | Deserializzatori HTML personalizzati. | `CustomDeserializers` | Sì | `{}` | | [`additionalBlockDeserializers`](#additional-block-deserializers) | Regole personalizzate per la deserializzazione dei blocchi Portable Text. | `unknown[]` | Sì | `[]` | ## Opzioni per l'impostazione regionale [#locale-options] ### `sourceLocale` [#source-locale] **Tipo** `string` · **Facoltativo** · **Predefinito** `defaultLocale`, quindi il valore predefinito della libreria Il codice della lingua sorgente, ad esempio `en`. Il plugin risolve l'impostazione regionale sorgente in questo ordine: `sourceLocale`, poi `defaultLocale`, poi il valore predefinito della libreria `generaltranslation`. ### `defaultLocale` [#default-locale] **Type** `string` · **Facoltativo** Alias per `sourceLocale`, accettato per consentirti di fare lo spread di `gt.config.json` direttamente nel plugin. Se sono impostati entrambi, `sourceLocale` ha la precedenza. ```ts import gtConfig from './gt.config.json'; gtPlugin({ ...gtConfig }); ``` ### `locales` [#locales] **Type** `string[]` · **Obbligatorio** I codici locale di destinazione verso cui tradurre, ad esempio `['es', 'fr', 'ja']`. ### `customMapping` [#custom-mapping] **Tipo** `CustomMapping` · **Facoltativo** Mappature personalizzate dei codici locale in nomi, oppure sovrascritture delle proprietà delle impostazioni regionali. Vengono passate alla libreria `generaltranslation`. Vedi [CustomMapping](/docs/platform/core/reference/types/custom-mapping). ## Credenziali [#credentials] Per impostazione predefinita, il plugin legge le credenziali da un documento privato di Sanity. Vedi [Memorizzare le credenziali](/docs/integrations/sanity/guides/configuring-sanity#store-credentials). ### `apiKey` [#api-key] **Tipo** `string` · **Facoltativo** · **Predefinito** letto dal documento secrets La tua chiave API di General Translation. Se impostata, viene passata alla libreria all'avvio. Quando è presente un documento secrets, il relativo campo `secret` ha la precedenza in fase di esecuzione. Preferisci il documento secrets così le chiavi restano fuori dal controllo versione. ### `projectId` [#project-id] **Tipo** `string` · **Facoltativo** · **Predefinito** letto dal documento delle credenziali segrete L'ID progetto di General Translation. Quando è presente un documento delle credenziali segrete, il campo `project` ha la precedenza a runtime. ### `secretsNamespace` [#secrets-namespace] **Tipo** `string` · **Facoltativo** · **Predefinito** `generaltranslation.secrets` L'`_id` del documento privato di Sanity che contiene le credenziali. Il plugin recupera questo documento tramite `_id` e usa il campo `secret` come chiave API e il campo `project` come ID progetto. Un `.` iniziale nell'`_id` mantiene il documento privato, anche in un dataset pubblico. ```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, }); ``` ## Opzioni del documento [#document-options] ### `languageField` [#language-field] **Type** `string` · **Facoltativo** · **Predefinito** `language` Il campo del documento utilizzato per memorizzare l'impostazione regionale di ciascun documento. Aggiungi un campo con questo nome a ogni tipo di documento traducibile e interrogalo per recuperare una specifica impostazione regionale. ### `translateDocuments` [#translate-documents] **Tipo** `TranslateDocumentFilter[] | string[]` · **Facoltativo** · **Predefinito** `[]` Filtra i documenti che possono essere tradotti. Accetta oggetti filtro o stringhe di tipo in forma abbreviata. Ogni entry di stringa `'article'` viene normalizzata in `{ type: 'article' }` e le entry senza `documentId` o `type` vengono scartate. ```ts gtPlugin({ sourceLocale: 'en', locales: ['es'], translateDocuments: [ { type: 'article' }, { documentId: 'homepage' }, 'page', // forma abbreviata per { type: 'page' } ], }); ``` `TranslateDocumentFilter` ha questa forma: ```ts type TranslateDocumentFilter = { documentId?: string; // corrisponde a un documento specifico tramite _id type?: string; // corrisponde a tutti i documenti di un tipo di schema }; ``` Le voci `type` determinano anche quali tipi di schema vengono abilitati da [`showDocumentInternationalization`](#show-doc-i18n). ### `singletons` [#singletons] **Tipo** `string[]` · **Facoltativo** · **Predefinito** `[]` ID dei documenti trattati come singleton, come le impostazioni del sito o la navigazione. Gli ID dei documenti tradotti corrispondenti sono ricavati da [`singletonMapping`](#singleton-mapping). ### `singletonMapping` [#singleton-mapping] **Type** `(sourceDocumentId: string, locale: string) => string` · **Facoltativo** · **Predefinito** `` `${sourceDocumentId}-${locale}` `` Mette in corrispondenza l'ID del documento sorgente di un singleton e un'impostazione regionale con l'ID del documento del singleton tradotto. Il valore predefinito è deterministico, quindi `siteSettings` diventa `siteSettings-es` per lo spagnolo. ```ts gtPlugin({ sourceLocale: 'en', locales: ['es'], singletons: ['siteSettings'], singletonMapping: (sourceDocumentId, locale) => `${sourceDocumentId}_${locale}`, }); ``` ### `showDocumentInternationalization` [#show-doc-i18n] **Tipo** `boolean` · **Facoltativo** · **Predefinito** `true` Quando è `true`, il plugin aggiunge `@sanity/document-internationalization` con badge della lingua, un menu di traduzione e template di documento per lingua. Usa le voci `type` in [`translateDocuments`](#translate-documents) come tipi di schema e `[sourceLocale, ...locales]` come lingue supportate, quindi ha effetto solo quando `translateDocuments` include tipi di documento. I tipi di documento localizzati in-place con array internazionalizzati vengono esclusi automaticamente. Impostalo su `false` se vuoi gestire l'internazionalizzazione manualmente. ## Localizzazione a livello di campo [#field-level] La localizzazione a livello di campo memorizza il valore di ogni impostazione regionale in un unico documento, sotto forma di array internazionalizzato. I dati memorizzati usano la stessa struttura degli elementi `{ _key, _type, language, value }` di `sanity-plugin-internationalized-array`, quindi i contenuti esistenti in `internationalized-array` non richiedono alcuna migrazione. ### `internationalizedArray` [#internationalized-array] **Tipo** `GTFieldLevelLocalizationConfig` · **Facoltativo** Configura i tipi di schema e i componenti di input dello Studio usati per la localizzazione a livello di campo. L'identificatore dell'impostazione regionale deriva sempre da `sourceLocale` e `locales`. ```ts type GTFieldLevelLocalizationConfig = { enabled?: boolean; // predefinito: false fieldTypes?: FieldLevelFieldType[]; // predefinito: ['string', 'text'] languageTitles?: Record; getLanguageTitle?: (locale: string) => string; typePrefix?: string; // predefinito: 'internationalizedArray' includeCompatibilityTypes?: boolean; // predefinito: true components?: { input?: ComponentType | false; item?: ComponentType | false; field?: ComponentType | false; }; }; type FieldLevelFieldType = | 'string' | 'text' | 'block' | { name: string; type: string; title?: string; of?: unknown[]; fields?: unknown[]; options?: Record; }; ``` Le scorciatoie `fieldTypes` integrate sono `string`, `text` e `block` (Portable Text). Una voce oggetto definisce un tipo generato personalizzato. `getLanguageTitle` ha la precedenza su `languageTitles` quando entrambi sono impostati. Ogni slot `components` accetta un componente di Studio o `false` per usare il rendering predefinito di Sanity. ### `fieldLevelLocalization` [#field-level-localization] **Tipo** `GTFieldLevelLocalizationConfig` · **Opzionale** Un alias descrittivo di [`internationalizedArray`](#internationalized-array). ### `translationLevel` [#translation-level] **Tipo** `'document' | 'internationalizedArray' | 'mixed'` · **Facoltativo** · **Predefinito** `'document'` Controlla come vengono tradotti i documenti corrispondenti: * `'document'` crea un documento per ogni impostazione regionale * `'internationalizedArray'` localizza i campi configurati in-place * `'mixed'` usa la localizzazione a livello di campo per [`fieldLevelDocuments`](#field-level-documents) e la localizzazione a livello di documento per tutti gli altri ### `fieldLevelDocuments` [#field-level-documents] **Tipo** `TranslateDocumentFilter[] | string[]` · **Facoltativo** · **Predefinito** `[]` Seleziona i tipi di documento che usano array internazionalizzati quando `translationLevel` è `'mixed'`. Accetta le stesse forme di filtro e la stessa sintassi abbreviata in formato stringa di [`translateDocuments`](#translate-documents). ```ts gtPlugin({ sourceLocale: 'en', locales: ['es', 'fr'], translateDocuments: [{ type: 'post' }, { type: 'siteSettings' }], internationalizedArray: { enabled: true, fieldTypes: ['string', 'text', 'block'], languageTitles: { es: 'Español', fr: 'Français' }, }, translationLevel: 'mixed', fieldLevelDocuments: [{ type: 'siteSettings' }], }); ``` Quindi usa i tipi generati nei tuoi schemi: ```ts defineField({ name: 'title', type: 'internationalizedArrayString', }); ``` ## Corrispondenza dei campi [#field-matchers] `ignoreFields`, `dedupeFields` e `skipFields` accettano ciascuno un array di oggetti `FieldMatcher`. Un matcher individua i campi tramite un'espressione JSONPath `property` e, facoltativamente, limita la corrispondenza a un solo documento sorgente tramite `documentId`. ```ts type FieldMatcher = { documentId?: string | null; // limita a un documento sorgente tramite _id fields?: { property: string; // espressione JSONPath, ad esempio $.slug type?: string; // suggerimento opzionale sul tipo di schema, ad esempio slug }[]; }; ``` ### `ignoreFields` [#ignore-fields] **Tipo** `FieldMatcher[]` · **Facoltativo** · **Predefinito** `[]` Campi copiati dal documento sorgente al documento tradotto senza essere inviati all'API di traduzione. Usalo per i valori che devono rimanere identici tra le varie impostazioni regionali, come categorie o tag. ```ts gtPlugin({ sourceLocale: 'en', locales: ['es'], ignoreFields: [ // Copia la categoria invariata per tutti i documenti { fields: [{ property: '$.category' }] }, // Copia i tag invariati solo per un documento { documentId: 'homepage', fields: [{ property: '$.tags' }] }, ], }); ``` ### `dedupeFields` [#dedupe-fields] **Tipo** `FieldMatcher[]` · **Facoltativo** · **Predefinito** `[]` Campi copiati dal valore sorgente e resi univoci aggiungendo l'impostazione regionale quando il documento tradotto viene creato per la prima volta. Di uso comune per gli slug. ```ts gtPlugin({ sourceLocale: 'en', locales: ['es', 'fr'], // "about" diventa "about-es" e "about-fr" dedupeFields: [{ fields: [{ property: '$.slug', type: 'slug' }] }], }); ``` Per un campo slug, il plugin aggiorna il valore `current` dell'oggetto slug. Se in seguito un editor modifica lo slug tradotto, le importazioni successive mantengono quel valore modificato. ### `skipFields` [#skip-fields] **Tipo** `FieldMatcher[]` · **Facoltativo** · **Predefinito** `[]` Campi completamente rimossi dai documenti tradotti. ```ts gtPlugin({ sourceLocale: 'en', locales: ['es'], skipFields: [ { fields: [{ property: '$.slug', type: 'slug' }] }, { documentId: 'homepage', fields: [{ property: '$.debugInfo' }] }, ], }); ``` ## Serializzazione [#serialization] Il plugin serializza i documenti in HTML per la traduzione e deserializza il risultato nei campi di Sanity. La maggior parte dei progetti non richiede queste opzioni. ### `additionalStopTypes` [#additional-stop-types] **Tipo** `string[]` · **Facoltativo** · **Predefinito** `[]` Ulteriori tipi di schema da preservare senza tradurli, che si aggiungono ai [stop types predefiniti](#stop-types). ```ts gtPlugin({ sourceLocale: 'en', locales: ['es'], additionalStopTypes: ['codeBlock', 'mux.video', 'mux.videoAsset'], }); ``` ### `additionalSerializers` [#additional-serializers] **Tipo** `Partial` · **Facoltativo** · **Predefinito** `{}` Serializzatori personalizzati combinati con quelli predefiniti, secondo la struttura dei componenti di `@portabletext/to-html` (`types`, `marks`, `block`, `list`, `listItem` e altri). Vengono usati soprattutto per serializzare `marks` personalizzati. Per i `marks` personalizzati, racchiudi l'output con `attachGTData` in modo che i dati del mark vengano mantenuti durante la traduzione. ```ts title="sanity.config.ts" import { attachGTData, gtPlugin } from 'gt-sanity'; gtPlugin({ sourceLocale: 'en', locales: ['es'], additionalSerializers: { marks: { link: ({ value, children }) => attachGTData(`${children}`, value, 'markDef'), inlineMath: ({ value, children }) => attachGTData(`${children}`, value, 'markDef'), }, }, }); ``` `attachGTData(html, data, 'markDef')` codifica `data` in base64 nell'attributo `data-gt-internal` del primo elemento di `html` e restituisce l'HTML aggiornato. Durante l'importazione, il plugin legge quell'attributo per ricostruire la definizione del mark. ```ts function attachGTData( html: string, data: Record, type: 'markDef' ): string; ``` ### `additionalDeserializers` [#additional-deserializers] **Tipo** `CustomDeserializers` · **Opzionale** · **Predefinito** `{}` Deserializzatori personalizzati che riconvertono gli elementi HTML tradotti in oggetti Sanity, raggruppati per tipo. ```ts type CustomDeserializers = { types?: Record< string, (element: HTMLElement) => Record | unknown[] >; } & Record; ``` ### `additionalBlockDeserializers` [#additional-block-deserializers] **Tipo** `unknown[]` · **Facoltativo** · **Predefinito** `[]` Regole aggiuntive per la deserializzazione dei blocchi Portable Text, aggiunte alle regole integrate del plugin. Ogni regola è un oggetto con un metodo `deserialize(node, next)`, conforme alla struttura delle regole di `@portabletext/block-tools`. ## Stop types predefiniti [#stop-types] Questi tipi di schema vengono conservati e non vengono mai inviati per la traduzione. Puoi aggiungerne altri con [`additionalStopTypes`](#additional-stop-types). ```ts const defaultStopTypes = [ 'reference', 'date', 'datetime', 'file', 'geopoint', 'image', 'number', 'crop', 'hotspot', 'boolean', 'url', 'color', 'code', ]; ``` I campi slug *non* vengono esclusi per impostazione predefinita, quindi la stringa `current` di uno slug viene tradotta, a meno che non usi [`dedupeFields`](#dedupe-fields) o [`skipFields`](#skip-fields). ## Helper esportati [#helpers] `gt-sanity` esporta anche elementi di base per la serializzazione avanzata e per nodi documento personalizzati. La maggior parte dei progetti non ne ha bisogno. * `TranslationsTab` — il componente della scheda documento per `structureTool`. Vedi [Configurare Sanity](/docs/integrations/sanity/guides/configuring-sanity#translations-tab). * `attachGTData` / `detachGTData` — associano e leggono i dati di mark codificati usati dai serializzatori personalizzati. * `BaseDocumentSerializer`, `BaseDocumentDeserializer`, `BaseDocumentMerger` — le implementazioni predefinite di serializzazione, deserializzazione e merge. * `defaultStopTypes`, `customSerializers` — gli stop types predefiniti e il set di serializzatori. * `documentInternationalization` e i relativi tipi (`DocumentInternationalizationConfig`, `Language`, `Metadata`, `TranslationReference`) — riesportati da `@sanity/document-internationalization`. ## Esempio completo [#complete-example] ```ts title="sanity.config.ts" import { defineConfig } from 'sanity'; import { attachGTData, gtPlugin } from 'gt-sanity'; export default defineConfig({ plugins: [ gtPlugin({ // Obbligatorio sourceLocale: 'en', locales: ['es', 'fr', 'de', 'ja'], // Documenti e campi languageField: 'language', translateDocuments: [{ type: 'article' }, { type: 'page' }], singletons: ['siteSettings', 'navigation'], singletonMapping: (id, locale) => `${id}_${locale}`, // Comportamento dei campi ignoreFields: [{ fields: [{ property: '$.category' }] }], dedupeFields: [{ fields: [{ property: '$.slug', type: 'slug' }] }], skipFields: [{ fields: [{ property: '$.internalNotes' }] }], // Serializzazione — solo se i valori predefiniti non gestiscono il tuo schema additionalSerializers: { marks: { link: ({ value, children }) => attachGTData(`${children}`, value, 'markDef'), }, }, }), ], }); ```