# 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 : ce guide présente les paramètres régionaux, les filtres de documents, la localisation au niveau des champs, les identifiants d'accès, les champs de langue 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.

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

Les traductions 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`.

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

Le plugin génère des types de schéma `internationalizedArray*` à partir de `sourceLocale` et de `locales`, ainsi qu’une interface utilisateur intégrée d’édition pour chaque paramètre régional. Utilisez les types générés dans vos schémas.

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

Par défaut, le plugin génère des 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' }],
},
```

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.

## 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