# sanity: Configuration du plugin
URL: https://generaltranslation.com/fr/docs/sanity/api/plugin-config.mdx
---
title: Configuration du plugin
description: Référence de l’API des options de configuration de gtPlugin
---

## Aperçu

La fonction `gtPlugin` configure General Translation pour votre studio Sanity.

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

gtPlugin(config: GTPluginConfig)
```


## GTPluginConfig

<TypeTable
  type={{
sourceLocale: {
type: 'string',
description: 'Code de la langue source (par ex. "en"). Utilise defaultLocale comme valeur de repli s’il n’est pas fourni.',
optional: true,
},
defaultLocale: {
type: 'string',
description: 'Alias de sourceLocale. Accepté pour que vous puissiez étendre gt.config.json directement. sourceLocale est prioritaire si les deux sont définis.',
optional: true,
},
locales: { type: 'string[]', description: 'Tableau des codes de langue cibles' },
apiKey: {
type: 'string',
description: 'Clé API GT (facultative si vous utilisez un document de secrets)',
optional: true,
},
projectId: {
type: 'string',
description: 'ID du projet GT (facultatif si vous utilisez un document de secrets)',
optional: true,
},
languageField: {
type: 'string',
description: 'Champ du document qui stocke le paramètre régional. Par défaut : "language"',
optional: true,
},
singletons: {
type: 'string[]',
description: 'ID de documents traités comme des singletons',
optional: true,
},
singletonMapping: {
type: '(docId: string, locale: string) => string',
description:
'Fonction permettant de générer les ID de singletons traduits. Par défaut : "${docId}-${locale}"',
optional: true,
},
ignoreFields: {
type: 'IgnoreFields[]',
description: 'Champs à exclure de la traduction. Les champs correspondants sont supprimés avant la sérialisation et restaurés à partir du document source après la traduction.',
optional: true,
},
dedupeFields: {
type: 'DedupeFields[]',
description: 'Champs à exclure de la traduction, puis à initialiser à partir du document source avec le paramètre régional cible ajouté lors de la création d’un document traduit.',
optional: true,
},
skipFields: {
type: 'SkipFields[]',
description: 'Champs à supprimer entièrement des documents traduits. Contrairement à ignoreFields, ces champs n’apparaîtront pas du tout dans le document traduit.',
optional: true,
},
translateDocuments: {
type: "TranslateDocumentFilter[] | string[]",
description: 'Filtre déterminant quels documents peuvent être traduits. Accepte un tableau d’objets de filtre ou un tableau abrégé de chaînes de types de document.',
optional: true,
},
secretsNamespace: {
type: 'string',
description:
'Espace de noms du document d’identifiants. Par défaut : "generaltranslation"',
optional: true,
},
additionalStopTypes: {
type: 'string[]',
description: 'Types supplémentaires à ignorer lors de la sérialisation',
optional: true,
},
additionalSerializers: {
type: 'Record<string, Serializer>',
description: 'Sérialiseurs HTML personnalisés pour les types de blocs',
optional: true,
},
additionalDeserializers: {
type: 'Record<string, Deserializer>',
description: 'Désérialiseurs HTML personnalisés',
optional: true,
},
additionalBlockDeserializers: {
type: 'BlockDeserializer[]',
description: 'Désérialiseurs personnalisés au niveau des blocs',
optional: true,
},
customMapping: {
type: "Record<string, string | Partial<LocaleProperties>>",
description: 'Mappage personnalisé des paramètres régionaux pour les codes de paramètre régional non standard',
optional: true,
},
showDocumentInternationalization: {
type: 'boolean',
description: 'Lorsque cette option est définie sur true (valeur par défaut), ajoute automatiquement le plugin @sanity/document-internationalization avec des badges de langue, un menu de traduction et des templates par langue. Nécessite translateDocuments.',
optional: true,
},
}}
/>

## IgnoreFields

Champs qui ne sont pas traduits ni envoyés à l’API, mais copiés du document source vers la traduction. Utilisez-le pour des champs tels que les catégories, les tags ou les métadonnées internes, qui doivent avoir la même valeur dans toutes les langues.

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


### Exemple

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  ignoreFields: [
    // Copier la catégorie telle quelle dans tous les documents traduits
    {
      fields: [{ property: '$.category' }],
    },
    // Copier ces champs tels quels uniquement pour les articles
    {
      documentId: 'article',
      fields: [{ property: '$.tags' }, { property: '$.author' }],
    },
  ],
});
```


## DedupeFields

Champs qui ne sont ni traduits ni envoyés à l’API, mais qui sont copiés depuis le document source avec le paramètre régional cible ajouté lors de la création initiale d’un document traduit. Utilisez ceci pour des champs qui doivent au départ rester dérivés de la source tout en étant uniques pour chaque document traduit, comme les slugs Sanity.

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

### Exemple

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

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 traductions conservent cette valeur modifiée.

## SkipFields

Champs entièrement supprimés des documents traduits. Contrairement à `ignoreFields`, ces champs n’apparaîtront pas du tout dans les documents traduits. Utilisez ceci pour des champs comme des URL canoniques SEO, des métadonnées présentes uniquement dans la source ou des slugs que les éditeurs doivent définir manuellement pour chaque langue.

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

### Exemple

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  skipFields: [
    // Les éditeurs définiront les slugs manuellement par langue
    {
      fields: [{ property: '$.slug', type: 'slug' }],
    },
    // Remove source-only debug data from homepage translations
    {
      documentId: 'homepage',
      fields: [{ property: '$.debugInfo' }],
    },
  ],
});
```

## TranslateDocumentFilter

Filtre qui détermine quels documents sont disponibles à la traduction :

```typescript
type TranslateDocumentFilter = {
  documentId?: string; // ID de document spécifique
  type?: string; // Type de document
};
```


### Exemple

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


## Sérialiseur

Fonction personnalisée permettant de convertir un bloc Sanity en HTML :

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


### Exemple

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


## Types pour exclusion par défaut

Ces types sont conservés, mais ne sont pas envoyés à la traduction :

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

Ajoutez-en d’autres avec `additionalStopTypes` :

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


## Exemple complet

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

export default defineConfig({
  plugins: [
    gtPlugin({
      // Obligatoire
      sourceLocale: 'en',
      locales: ['es', 'fr', 'de', 'ja'],

      // Gestion des documents
      languageField: 'language',
      singletons: ['siteSettings', 'navigation'],
      singletonMapping: (id, locale) => `${id}_${locale}`,

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

      // Sérialisation - N'utilisez pas ceci à moins de savoir ce que vous faites !
      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'),
        },
      },
    }),
  ],
});
```

## Étapes suivantes

* [Guide de configuration](/docs/sanity/guides/configuration) - Schémas de configuration
* [Guide de sérialisation](/docs/sanity/guides/serialization) - Sérialisation personnalisée