# General Translation Integrations: Configuration de Sanity
URL: https://generaltranslation.com/fr/docs/integrations/sanity/guides/configuring-sanity.mdx
---
title: Configuration de Sanity
description: Comment configurer le plugin gt-sanity de General Translation pour les paramètres régionaux, les filtres de documents, la localisation au niveau des champs, l’identifiant et les documents uniques.
related:
  links:
    - /docs/integrations/sanity/guides/translating-content
    - /docs/integrations/sanity/guides/managing-translations
    - /docs/integrations/sanity/guides/querying-translations

---

Configurez le fonctionnement de General Translation dans Sanity Studio avec la fonction `gtPlugin`.

Ce guide présente les options les plus courantes. Pour la liste complète, consultez la [référence de configuration du plugin](/docs/integrations/sanity/reference/plugin-configuration).

## Ajouter le plugin [#add-plugin]

Ajoutez `gtPlugin` à la configuration de votre Studio. Cette étape est également décrite dans le [Quickstart](/docs/integrations/sanity/quickstart).

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

export default defineConfig({
  plugins: [
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'zh', 'ja'],
      translateDocuments: [{ type: 'article' }, { type: 'page' }],
    }),
  ],
});
```

## Définir les paramètres régionaux source et cibles [#set-locales]

Utilisez `sourceLocale` pour la langue source et `locales` pour les langues cibles.

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
});
```

Si vous avez déjà un `gt.config.json`, vous pouvez l’inclure dans la configuration du plugin avec l’opérateur spread. `defaultLocale` est accepté comme alias de `sourceLocale`.

```ts title="sanity.config.ts"
import gtConfig from './gt.config.json';

gtPlugin({
  ...gtConfig,
});
```

Le paramètre régional source est déterminé dans l’ordre suivant : `sourceLocale`, puis `defaultLocale`, puis la valeur par défaut de la bibliothèque. Si `sourceLocale` et `defaultLocale` sont tous deux définis, `sourceLocale` l’emporte. Le plugin supprime le paramètre régional source et les entrées en double de `locales`, afin qu’un `gt.config.json` partagé puisse inclure sans risque le paramètre régional par défaut.

## Ajouter un champ de langue [#language-field]

Les traductions au niveau du document sont stockées dans des documents séparés. Le plugin utilise un champ de langue pour enregistrer le paramètre régional de chaque document. Par défaut, ce champ s’appelle `language`. La localisation au niveau des champs n’utilise pas ce champ.

```ts title="schema/article.ts"
import { defineField, defineType } from 'sanity';

export const articleType = defineType({
  name: 'article',
  title: 'Article',
  type: 'document',
  fields: [
    defineField({
      name: 'language',
      type: 'string',
      readOnly: true,
      hidden: true,
    }),
  ],
});
```

Pour utiliser un autre nom de champ, définissez `languageField` et utilisez le même nom dans votre schéma.

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  languageField: 'locale',
});
```

## Choisissez les documents à traduire [#choose-documents]

Utilisez `translateDocuments` pour filtrer les documents pouvant être traduits. Accepte des filtres par type de document, des filtres par ID de document ou une syntaxe abrégée sous forme de chaîne pour le type.

```ts
// Par type de document
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [{ type: 'page' }, { type: 'post' }],
});
```

```ts
// Par ID de document spécifique
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [{ documentId: 'homepage' }, { documentId: 'about-page' }],
});
```

```ts
// Chaînes de type abrégées
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  translateDocuments: ['article', 'page'],
});
```

Les entrées de type `string` sont traitées comme `{ type: '<string>' }`. `showDocumentInternationalization` utilise les entrées `type` pour déterminer quels types de schéma reçoivent des badges de langue et des modèles, donc des filtres par type de document sont nécessaires pour activer ces fonctionnalités.

## Configurer la localisation au niveau des champs [#field-level]

Par défaut, `gt-sanity` traduit au niveau du document, en créant un document pour chaque paramètre régional. La localisation au niveau des champs stocke la valeur de chaque paramètre régional dans le même document sous la forme d’un tableau internationalisé (`[{ _key, _type, language, value }]` — la même structure que [`sanity-plugin-internationalized-array`](https://github.com/sanity-io/sanity-plugin-internationalized-array), de sorte que les données existantes n’ont pas besoin d’être migrées).

Activez la génération du schéma avec `internationalizedArray` (ou son alias `fieldLevelLocalization`), puis définissez `translationLevel` sur `'internationalizedArray'`.

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [{ type: 'post' }],
  internationalizedArray: { enabled: true },
  translationLevel: 'internationalizedArray',
});
```

La localisation au niveau des champs s’appuie sur [`sanity-plugin-internationalized-array`](https://github.com/sanity-io/sanity-plugin-internationalized-array), le plugin Sanity de référence. `gtPlugin` le configure à partir de `sourceLocale` et de `locales`, et le plugin natif enregistre les types de schéma `internationalizedArray*` ainsi que l’interface utilisateur d’édition de Studio — les boutons d’ajout pour chaque langue, les libellés de langue et les actions sur les champs se comportent exactement comme avec le plugin autonome. Utilisez les types enregistrés dans vos schémas.

```ts
defineField({
  name: 'title',
  type: 'internationalizedArrayString',
});
```

Par défaut, le plugin enregistre les types `string` et `text`. Utilisez `fieldTypes` pour ajouter `block` (Portable Text) ou des définitions d’objets personnalisées.

```ts
internationalizedArray: {
  enabled: true,
  fieldTypes: ['string', 'text', 'block', { name: 'seo', type: 'seoFields' }],
},
```

Si vous enregistrez déjà vous-même `sanity-plugin-internationalized-array` dans votre Studio, conservez votre configuration et laissez `internationalizedArray` non défini afin que les types de schéma ne soient enregistrés qu’une seule fois. Translation lit et écrit les données stockées `{ _key, _type, language, value }`, quelle que soit l’instance du plugin qui a enregistré les types ; il suffit donc de définir `translationLevel` (et `translateDocuments`) pour que GT dispose de tout ce dont il a besoin.

```ts
import { internationalizedArray } from 'gt-sanity';

plugins: [
  internationalizedArray({
    languages: [
      { id: 'en', title: 'English' },
      { id: 'es', title: 'Spanish' },
    ],
    fieldTypes: ['string'],
  }),
  gtPlugin({
    sourceLocale: 'en',
    locales: ['es'],
    translateDocuments: [{ type: 'post' }],
    translationLevel: 'internationalizedArray',
  }),
],
```

Pour combiner les deux stratégies, définissez `translationLevel` sur `'mixed'` et indiquez dans `fieldLevelDocuments` les types de documents traduits au niveau des champs.

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [{ type: 'post' }, { type: 'siteSettings' }],
  internationalizedArray: { enabled: true },
  translationLevel: 'mixed',
  fieldLevelDocuments: [{ type: 'siteSettings' }],
});
```

Les types de document localisés sur place sont automatiquement exclus de `@sanity/document-internationalization` ; ils ne reçoivent donc ni badges de langue ni modèles de document propres à chaque paramètre régional. Lors de l’importation, le plugin met à jour uniquement le paramètre régional cible dans le document source et préserve toutes les autres langues.

Consultez la [référence de configuration du plugin](/docs/integrations/sanity/reference/plugin-configuration#field-level) pour connaître toutes les options au niveau des champs.

## Exclure des champs de la traduction [#exclude-fields]

Marquez un champ dans votre schéma pour empêcher la traduction de son contenu. Définissez `options.gt.exclude` dans la définition du champ.

```ts title="schema/article.ts"
defineField({
  name: 'internalNotes',
  type: 'string',
  options: { gt: { exclude: true } },
});
```

Les champs exclus ne sont jamais envoyés à la traduction ; les documents traduits conservent donc la valeur source inchangée. L&#39;exclusion s&#39;applique à tous les niveaux d&#39;imbrication.

Le plugin respecte également les options d&#39;exclusion des plugins de localisation standard de Sanity. Si votre schéma les utilise déjà, vous n&#39;avez pas besoin d&#39;ajouter un second marqueur :

* `options.documentInternationalization.exclude` de `@sanity/document-internationalization`
* `options.aiAssist.exclude` de `@sanity/assist`
* l&#39;ancienne propriété de champ `localize: false`

Pour exclure toutes les occurrences d&#39;un type personnalisé, définissez l&#39;option directement sur la définition du type.

```ts title="schema/objects/legalDisclaimer.ts"
export const legalDisclaimer = defineType({
  name: 'legalDisclaimer',
  type: 'object',
  // Exclut ce type partout où il est utilisé
  options: { gt: { exclude: true } },
  fields: [
    defineField({ name: 'jurisdiction', type: 'string' }),
    defineField({ name: 'text', type: 'text' }),
  ],
});
```

Pour les règles qui ciblent des documents par ID ou transforment des valeurs selon le paramètre régional — comme la déduplication du slug — utilisez plutôt les options [`ignoreFields`, `skipFields` et `dedupeFields`](/docs/integrations/sanity/reference/plugin-configuration#field-matchers) au niveau du plugin.

## Configurer les documents uniques [#singletons]

Utilisez `singletons` pour les documents présents en un seul exemplaire par site, comme les paramètres du site ou la navigation. `singletonMapping` détermine comment l’ID du document unique traduit est généré à partir de l’ID source et du paramètre régional.

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  singletons: ['siteSettings', 'navigation', 'footer'],
  singletonMapping: (sourceDocumentId, locale) => `${sourceDocumentId}-${locale}`,
});
```

Si vous omettez `singletonMapping`, le comportement par défaut associe `sourceDocumentId` et le paramètre régional à `` `${sourceDocumentId}-${locale}` `` (par exemple, `siteSettings-es`).

## Enregistrer les identifiants [#store-credentials]

Le plugin lit votre clé API et votre identifiant du projet à partir d’un document Sanity privé dont le `_id` correspond à `secretsNamespace` (par défaut : `generaltranslation.secrets`). Créez-le à l’aide d’un script ponctuel.

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

```bash
GT_API_KEY=your-api-key GT_PROJECT_ID=your-project-id npx sanity exec populateSecrets.js --with-user-token
```

Le champ `secret` est utilisé comme clé d’API et le champ `project` comme identifiant du projet. Pour lire les identifiants depuis un autre document, définissez `secretsNamespace` sur le `_id` de ce document.

Vous pouvez aussi passer `apiKey` et `projectId` directement à `gtPlugin`, mais il est recommandé d’utiliser le document de secrets pour que les identifiants ne se retrouvent pas dans le contrôle de version. Lorsque les deux sont présents, le document de secrets est prioritaire à l’exécution.

## Ajouter l’onglet Traductions facultatif [#translations-tab]

L’action de document **Traduire** est ajoutée automatiquement. Pour afficher également l’onglet Traductions dans l’éditeur du document, ajoutez `TranslationsTab` avec `structureTool`.

```ts title="sanity.config.ts"
import { defineConfig } from 'sanity';
import { structureTool } from 'sanity/structure';
import { gtPlugin, TranslationsTab } from 'gt-sanity';

export default defineConfig({
  plugins: [
    structureTool({
      defaultDocumentNode: (S) =>
        S.document().views([
          S.view.form(),
          S.view.component(TranslationsTab).title('General Translation'),
        ]),
    }),
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'zh', 'ja'],
    }),
  ],
});
```
## Next steps

- /docs/integrations/sanity/guides/translating-content
- /docs/integrations/sanity/guides/managing-translations
- /docs/integrations/sanity/guides/querying-translations