# sanity: Configurazione
URL: https://generaltranslation.com/it/docs/sanity/guides/configuration.mdx
---
title: Configurazione
description: Configura il plugin gt-sanity per il progetto Sanity
---

## Panoramica

La funzione `gtPlugin` accetta un oggetto di configurazione per personalizzare il comportamento della traduzione, le impostazioni regionali e la gestione dei documenti.

```typescript title="sanity.config.ts"
import { gtPlugin } from 'gt-sanity';

export default defineConfig({
  plugins: [
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'zh', 'ja'], // Sostituisci con le tue impostazioni regionali di destinazione
      languageField: 'language',
      singletons: ['siteSettings', 'navigation'],
    }),
  ],
});
```


## Configurazione di base

### Lingua di origine e impostazioni regionali di destinazione

Definisci la lingua di origine e le impostazioni regionali di destinazione:

```typescript
gtPlugin({
  sourceLocale: 'en', // Lingua di origine del contenuto
  locales: ['es', 'zh', 'ja'], // Lingue di destinazione per la traduzione
});
```

### Uso di `defaultLocale` da `gt.config.json`

Se hai già un `gt.config.json` (ad esempio perché usi `gt-next` o `gt-react`), puoi espanderlo direttamente nella configurazione del plugin. Il campo `defaultLocale` è accettato anche come alias di `sourceLocale`:

```typescript
import gtConfig from './gt.config.json';

gtPlugin({
  ...gtConfig, // { defaultLocale: 'en', locales: ['es', 'zh', 'ja'] }
});
```

Se vengono specificati sia `sourceLocale` che `defaultLocale`, `sourceLocale` ha la precedenza.


### Campo lingua

Specifica quale campo memorizza l'impostazione regionale del documento. Per impostazione predefinita è `'language'`:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  languageField: 'locale', // Per impostazione predefinita, i documenti usano il campo 'language'. Qui usiamo 'locale' al suo posto.
});
```


## Filtrare i documenti

### Traduci tipi di documenti specifici

Limita la traduzione a specifici tipi di documento:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [{ type: 'page' }, { type: 'post' }],
});
```


### Tradurre documenti specifici

Seleziona gli ID dei documenti specifici:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [
    { documentId: 'homepage' },
    { documentId: 'about-page' },
  ],
});
```


## Documenti singleton

I singleton sono documenti di Sanity che esistono in un'unica istanza con varianti tradotte. Configura come vengono denominate le versioni tradotte:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  singletons: ['siteSettings', 'navigation', 'footer'], // Elenco degli ID dei documenti singleton
  singletonMapping: (docId, locale) => `${docId}-${locale}`, // Funzione opzionale per personalizzare gli ID dei documenti singleton tradotti
});
```

Per impostazione predefinita, le traduzioni dei singleton avranno ID generati casualmente, a meno che non venga fornito `singletonMapping`.


## Ignora i campi

Campi che non vuoi tradurre o inviare all'API di GT, ma che devono comunque essere copiati dal documento sorgente alla traduzione. I campi ignorati vengono rimossi prima della serializzazione (quindi il contenuto non viene mai inviato all'API), quindi ripristinati dal documento sorgente dopo la creazione del documento tradotto.

Usa `ignoreFields` per campi come categorie, tag o metadati interni che devono avere lo stesso valore sia nel documento sorgente sia in quello tradotto, ma che non richiedono traduzione:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  ignoreFields: [
    { fields: [{ property: '$.category' }] },       // stessa categoria per tutte le lingue
    { fields: [{ property: '$..linkType' }] },       // metadati interni dei link
    { fields: [{ property: '$..frequencies.default' }] },
  ],
});
```

`property` è un'espressione [JSONPath](https://goessner.net/articles/JsonPath/) che identifica uno o più campi nei documenti.
`type` è un parametro facoltativo per filtrare ulteriormente i campi da ignorare in base a tipi specifici.


## Rendere univoci i campi

Campi che non vuoi tradurre né inviare all'API di GT, ma che devono comunque essere copiati dal documento sorgente e resi univoci quando un documento tradotto viene creato per la prima volta. Questi campi vengono rimossi prima della serializzazione, quindi ripristinati dal documento sorgente con l'impostazione regionale di destinazione aggiunta.

Usa `dedupeFields` per gli slug di Sanity o altri identificatori testuali che devono continuare a basarsi sul valore sorgente, ma risultare univoci per ogni lingua:

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

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 spagnolo. Se in seguito un editor modifica lo slug tradotto, le future importazioni di traduzione mantengono quel valore modificato.

## Escludere i campi

Campi che non devono essere copiati automaticamente nei documenti tradotti. A differenza di `ignoreFields` (che mantiene il valore di origine nel documento tradotto), `skipFields` rimuove completamente i campi corrispondenti dal documento tradotto.

Usa `skipFields` per campi come gli URL canonici SEO, i metadati presenti solo nella sorgente o gli slug che gli editor devono impostare manualmente per ogni lingua:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  skipFields: [
    { fields: [{ property: '$.slug', type: 'slug' }] },  // gli editor impostano gli slug manualmente per lingua
    { fields: [{ property: '$.canonicalUrl' }] },         // only relevant on source
    {
      documentId: 'homepage',
      fields: [{ property: '$.debugInfo' }],              // source-only debug data
    },
  ],
});
```

## Opzioni di serializzazione

Estendi il comportamento di serializzazione predefinito:

```typescript
import { attachGTData, gtPlugin } from 'gt-sanity';
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  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'),
    },
  },
});
```

Per i dettagli, consulta la [Guida alla serializzazione](/docs/sanity/guides/serialization).


## Esempio completo

```typescript title="sanity.config.ts"
import { defineConfig } from 'sanity';
import { gtPlugin } from 'gt-sanity';

export default defineConfig({
  name: 'default',
  title: 'My Project',
  projectId: 'your-project-id',
  dataset: 'production',

  plugins: [
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'fr', 'de', 'ja', 'zh'],
      languageField: 'language',
      singletons: ['siteSettings', 'navigation'],
      translateDocuments: [{ type: 'article' }, { type: 'page' }],
      ignoreFields: [
        {
          fields: [{ property: '$.publishedAt' }],
        },
      ],
      dedupeFields: [
        {
          fields: [{ property: '$.slug', type: 'slug' }],
        },
      ],
      skipFields: [
        {
          fields: [{ property: '$.internalNotes' }],
        },
      ],
    }),
  ],

  schema: {
    types: schemaTypes,
  },
});
```

## Passaggi successivi

* [Guida alla serializzazione](/docs/sanity/guides/serialization) - Regole di serializzazione personalizzate
* [Riferimento API](/docs/sanity/api/plugin-config) - Tutte le opzioni di configurazione