# sanity: Configuration
URL: https://generaltranslation.com/fr/docs/sanity/guides/configuration.mdx
---
title: Configuration
description: Configurez le plugin gt-sanity pour votre projet Sanity
---

## Vue d’ensemble

La fonction `gtPlugin` accepte un objet de configuration pour personnaliser le comportement de traduction, les paramètres régionaux et le traitement des documents.

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

export default defineConfig({
  plugins: [
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'zh', 'ja'], // Remplacez par vos paramètres régionaux cibles
      languageField: 'language',
      singletons: ['siteSettings', 'navigation'],
    }),
  ],
});
```

## Configuration de base

### Paramètre régional source et paramètres régionaux cibles

Définissez votre langue source et vos paramètres régionaux cibles :

```typescript
gtPlugin({
  sourceLocale: 'en', // Langue source du contenu
  locales: ['es', 'zh', 'ja'], // Langues cibles pour la traduction
});
```


### Utiliser `defaultLocale` de `gt.config.json`

Si vous avez déjà un `gt.config.json` (par ex. si vous utilisez `gt-next` ou `gt-react`), vous pouvez l’inclure directement dans la configuration du plugin. Le champ `defaultLocale` est accepté comme alias de `sourceLocale` :

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

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

Si `sourceLocale` et `defaultLocale` sont tous deux renseignés, `sourceLocale` est prioritaire.


### Champ de langue

Indiquez dans quel champ est stocké le paramètre régional du document. La valeur par défaut est `'language'` :

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  languageField: 'locale', // Par défaut, les documents utilisent le champ 'language'. Ici, nous utilisons 'locale' à la place.
});
```


## Filtrage des documents

### Traduire des types de documents précis

Limitez la traduction à certains types de documents :

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


### Traduire des documents spécifiques

Ciblez des identifiants de document spécifiques :

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


## Documents uniques

Les documents uniques sont des documents Sanity qui n’existent qu’en un seul exemplaire, avec des variantes traduites. Configurez la manière dont les versions traduites sont nommées :

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  singletons: ['siteSettings', 'navigation', 'footer'], // Liste des IDs de documents singleton
  singletonMapping: (docId, locale) => `${docId}-${locale}`, // Fonction optionnelle pour personnaliser les ids des documents singleton traduits
});
```

Par défaut, les traductions des documents uniques auront des identifiants générés aléatoirement, sauf si `singletonMapping` est défini.

## Ignorer certains champs

Champs que vous ne souhaitez ni traduire ni envoyer à l’API GT, mais qui doivent tout de même être copiés du document source vers la traduction. Les champs ignorés sont retirés avant la sérialisation (le contenu n’est donc jamais envoyé à l’API), puis restaurés à partir du document source une fois le document traduit créé.

Utilisez `ignoreFields` pour des champs comme les catégories, les tags ou les métadonnées internes, qui doivent avoir la même valeur dans les documents source et traduits, mais n’ont pas besoin d’être traduits :

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  ignoreFields: [
    { fields: [{ property: '$.category' }] },       // même catégorie pour toutes les langues
    { fields: [{ property: '$..linkType' }] },       // métadonnées de lien interne
    { fields: [{ property: '$..frequencies.default' }] },
  ],
});
```

`property` est une expression [JSONPath](https://goessner.net/articles/JsonPath/) qui cible un ou plusieurs champs dans les documents.
`type` est un paramètre facultatif qui permet d’affiner le filtrage des champs à ignorer en le limitant à certains types.


## Déduplication des champs

Les champs que vous ne souhaitez ni traduire ni envoyer à l’API GT, mais qui doivent tout de même être copiés depuis le document source et rendus uniques lors de la création initiale d’un document traduit. Les champs à dédupliquer sont supprimés avant la sérialisation, puis restaurés à partir du document source avec le paramètre régional cible ajouté.

Utilisez `dedupeFields` pour les slugs Sanity ou d’autres identifiants de type chaîne de caractères qui doivent rester basés sur la valeur source, tout en étant uniques pour chaque langue :

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

Pour les champs slug de Sanity, le plugin met à jour la valeur `current` de l’objet slug. Par exemple, `{ _type: 'slug', current: 'about' }` devient `{ _type: 'slug', current: 'about-es' }` lorsque le document en espagnol est créé. Si un éditeur modifie ensuite le slug traduit, les futures importations de traduction conservent cette valeur modifiée.

## Exclure des champs

Champs qui ne doivent en aucun cas être copiés automatiquement dans les documents traduits. Contrairement à `ignoreFields` (qui conserve la valeur source dans la traduction), `skipFields` supprime complètement les champs correspondants du document traduit.

Utilisez `skipFields` pour des champs comme des URL canoniques SEO, des métadonnées propres à la source ou des slugs que les éditeurs doivent définir manuellement pour chaque langue :

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  skipFields: [
    { fields: [{ property: '$.slug', type: 'slug' }] },  // les éditeurs définissent les slugs manuellement par langue
    { fields: [{ property: '$.canonicalUrl' }] },         // pertinent uniquement pour la source
    {
      documentId: 'homepage',
      fields: [{ property: '$.debugInfo' }],              // données de débogage propres à la source
    },
  ],
});
```

## Options de sérialisation

Étendez le comportement de sérialisation par défaut :

```typescript
import { attachGTData, gtPlugin } from 'gt-sanity';
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  additionalSerializers: {
    // Sérialiseurs supplémentaires pour les marques (annotations personnalisées)
    marks: {
      link: ({ value, children }) =>
        attachGTData(`<a>${children}</a>`, value, 'markDef'),
      inlineMath: ({ value, children }) =>
        attachGTData(`<span>${children}</span>`, value, 'markDef'),
    },
  },
});
```

Consultez le [guide de sérialisation](/docs/sanity/guides/serialization) pour en savoir plus.


## Exemple complet

```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,
  },
});
```

## Étapes suivantes

* [Guide de sérialisation](/docs/sanity/guides/serialization) - Règles de sérialisation personnalisées
* [Référence de l’API](/docs/sanity/api/plugin-config) - Options de configuration complètes