# sanity: Configurazione del plugin
URL: https://generaltranslation.com/it/docs/sanity/api/plugin-config.mdx
---
title: Configurazione del plugin
description: Riferimento API delle opzioni di configurazione di gtPlugin
---

## Panoramica

La funzione `gtPlugin` configura General Translation per il tuo studio Sanity.

```typescript
import { gtPlugin } from 'gt-sanity'

gtPlugin(config: GTPluginConfig)
```


## GTPluginConfig

<TypeTable
  type={{
sourceLocale: {
type: 'string',
description: 'Codice della lingua di origine (ad es. "en"). Se non viene specificato, viene usato defaultLocale come fallback.',
optional: true,
},
defaultLocale: {
type: 'string',
description: 'Alias di sourceLocale. Accettato per consentirti di espandere direttamente gt.config.json. sourceLocale ha la precedenza se sono impostati entrambi.',
optional: true,
},
locales: { type: 'string[]', description: 'Elenco dei codici locale di destinazione' },
apiKey: {
type: 'string',
description: 'Chiave API di GT (facoltativa se si usa il documento secrets)',
optional: true,
},
projectId: {
type: 'string',
description: 'ID del progetto GT (facoltativo se si usa il documento secrets)',
optional: true,
},
languageField: {
type: 'string',
description: 'Campo del documento che memorizza l\'impostazione regionale. Predefinito: "language"',
optional: true,
},
singletons: {
type: 'string[]',
description: 'ID dei documenti trattati come singleton',
optional: true,
},
singletonMapping: {
type: '(docId: string, locale: string) => string',
description:
'Funzione per generare gli ID dei singleton tradotti. Predefinito: "${docId}-${locale}"',
optional: true,
},
ignoreFields: {
type: 'IgnoreFields[]',
description: 'Campi da escludere dalla traduzione. I campi corrispondenti vengono rimossi prima della serializzazione e ripristinati dal documento sorgente dopo la traduzione.',
optional: true,
},
dedupeFields: {
type: 'DedupeFields[]',
description: 'Campi da escludere dalla traduzione, quindi inizializzati dal documento sorgente con l\'impostazione regionale di destinazione aggiunta durante la creazione di un documento tradotto.',
optional: true,
},
skipFields: {
type: 'SkipFields[]',
description: 'Campi da rimuovere completamente dai documenti tradotti. A differenza di ignoreFields, questi campi non compariranno affatto nel documento tradotto.',
optional: true,
},
translateDocuments: {
type: "TranslateDocumentFilter[] | string[]",
description: 'Filtro che determina quali documenti possono essere tradotti. Accetta un array di oggetti filtro o un array abbreviato di stringhe con i tipi di documento.',
optional: true,
},
secretsNamespace: {
type: 'string',
description:
'Namespace del documento delle credenziali. Predefinito: "generaltranslation"',
optional: true,
},
additionalStopTypes: {
type: 'string[]',
description: 'Tipi aggiuntivi da saltare durante la serializzazione',
optional: true,
},
additionalSerializers: {
type: 'Record<string, Serializer>',
description: 'Serializzatori HTML personalizzati per i tipi di blocco',
optional: true,
},
additionalDeserializers: {
type: 'Record<string, Deserializer>',
description: 'Deserializzatori HTML personalizzati',
optional: true,
},
additionalBlockDeserializers: {
type: 'BlockDeserializer[]',
description: 'Deserializzatori personalizzati a livello di blocco',
optional: true,
},
customMapping: {
type: "Record<string, string | Partial<LocaleProperties>>",
description: 'Mappatura personalizzata dei codici locale per codici locale non standard',
optional: true,
},
showDocumentInternationalization: {
type: 'boolean',
description: 'Quando è true (predefinito), aggiunge automaticamente il plugin @sanity/document-internationalization con badge della lingua, menu di traduzione e template per ogni lingua. Richiede translateDocuments.',
optional: true,
},
}}
/>

## IgnoreFields

Campi che non vengono tradotti né inviati all&#39;API, ma copiati dal documento di origine nella traduzione. Usalo per campi come categorie, tag o metadati interni che devono avere lo stesso valore in tutte le lingue.

```typescript
type IgnoreFields = {
  documentId?: string;
  fields?: Array<{
    property: string;
    type?: string;
  }>;
};
```


### Esempio

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  ignoreFields: [
    // Copia category così com'è in tutti i documenti tradotti
    {
      fields: [{ property: '$.category' }],
    },
    // Copia questi campi così come sono solo per gli articoli
    {
      documentId: 'article',
      fields: [{ property: '$.tags' }, { property: '$.author' }],
    },
  ],
});
```


## DedupeFields

Campi che non vengono tradotti né inviati all&#39;API, ma copiati dal documento sorgente con l&#39;impostazione regionale di destinazione aggiunta in coda quando un documento tradotto viene creato per la prima volta. Usalo per i campi che devono iniziare come derivati dalla sorgente ma essere univoci per ogni documento tradotto, come gli slug di Sanity.

```typescript
type DedupeFields = {
  documentId?: string;
  fields?: Array<{
    property: string;
    type?: string;
  }>;
};
```

### Esempio

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'fr'],
  dedupeFields: [
    // "about" diventa "about-es" e "about-fr"
    {
      fields: [{ property: '$.slug', type: 'slug' }],
    },
  ],
});
```

Per i campi slug di Sanity, il plugin aggiorna il valore `current` dell’oggetto slug. Ad esempio, `{ _type: 'slug', current: 'about' }` diventa `{ _type: 'slug', current: 'about-es' }` quando viene creato il documento in spagnolo. Se in seguito un editor modifica lo slug tradotto, le future importazioni di traduzione mantengono quel valore modificato.

## SkipFields

Campi rimossi completamente dai documenti tradotti. A differenza di `ignoreFields`, questi campi non compariranno affatto nelle traduzioni. Usalo per campi come gli URL canonici per la SEO, i metadati presenti solo nella sorgente o gli slug che gli editor devono impostare manualmente per ogni lingua.

```typescript
type SkipFields = {
  documentId?: string;
  fields?: Array<{
    property: string;
    type?: string;
  }>;
};
```

### Esempio

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  skipFields: [
    // Gli editor imposteranno gli slug manualmente per ogni lingua
    {
      fields: [{ property: '$.slug', type: 'slug' }],
    },
    // Remove source-only debug data from homepage translations
    {
      documentId: 'homepage',
      fields: [{ property: '$.debugInfo' }],
    },
  ],
});
```

## TranslateDocumentFilter

Filtro che determina quali documenti sono disponibili per la traduzione:

```typescript
type TranslateDocumentFilter = {
  documentId?: string; // ID documento specifico
  type?: string; // Tipo di documento
};
```


### Esempio

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  translateDocuments: [
    { type: 'article' },
    { type: 'page' },
    { documentId: 'homepage' },
  ],
});
```


## Serializer

Funzione personalizzata per convertire un blocco di Sanity in HTML:

```typescript
type Serializer = (props: {
  value: any;
  isInline?: boolean;
  children?: string;
}) => string;
```


### Esempio

```typescript
import { attachGTData, gtPlugin } from 'gt-sanity';
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  additionalSerializers: {
    link: ({ value, children }) =>
      attachGTData(`<a>${children}</a>`, value, 'markDef'),
  },
});
```


## Tipi di arresto predefiniti

Questi tipi vengono mantenuti ma non inviati alla traduzione:

```typescript
const defaultStopTypes = [
  'reference',
  'crossDatasetReference',
  'date',
  'datetime',
  'file',
  'geopoint',
  'image',
  'number',
  'slug',
  'url',
];
```

Aggiungine altri con `additionalStopTypes`:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  additionalStopTypes: ['codeBlock', 'mathFormula'],
});
```


## Esempio completo

```typescript 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'],

      // Gestione dei documenti
      languageField: 'language',
      singletons: ['siteSettings', 'navigation'],
      singletonMapping: (id, locale) => `${id}_${locale}`,

      // Filtraggio
      translateDocuments: [{ type: 'article' }, { type: 'page' }],
      ignoreFields: [{ fields: [{ property: '$.publishedAt' }] }],
      dedupeFields: [{ fields: [{ property: '$.slug', type: 'slug' }] }],
      skipFields: [{ fields: [{ property: '$.internalNotes' }] }],

      // Serializzazione - Non utilizzare questa opzione a meno che non si sappia cosa si sta facendo!
      additionalSerializers: {
        // Serializzatori aggiuntivi per i mark (annotazioni personalizzate)
        marks: {
          link: ({ value, children }) =>
            attachGTData(`<a>${children}</a>`, value, 'markDef'),
          inlineMath: ({ value, children }) =>
            attachGTData(`<span>${children}</span>`, value, 'markDef'),
        },
      },
    }),
  ],
});
```

## Prossimi passaggi

* [Guida alla configurazione](/docs/sanity/guides/configuration) - Schemi di configurazione
* [Guida alla serializzazione](/docs/sanity/guides/serialization) - Serializzazione personalizzata