# General Translation Integrations: Configuration du plugin Sanity URL: https://generaltranslation.com/fr/docs/integrations/sanity/reference/plugin-configuration.mdx --- title: Configuration du plugin Sanity description: Configurez le plugin gt-sanity de General Translation pour Sanity Studio. Référence API de gtPlugin. --- Configurez General Translation dans Sanity Studio avec la fonction `gtPlugin`. Passez un seul objet d’options. ```ts title="sanity.config.ts" import { gtPlugin } from 'gt-sanity'; gtPlugin({ sourceLocale: 'en', locales: ['es', 'fr'], translateDocuments: [{ type: 'article' }], }); ``` ## Options [#options] | Option | Description | Type | Facultatif | Par défaut | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | ---------- | ------------------------------------------------------------- | | [`sourceLocale`](#source-locale) | Code de langue source, tel que `en`. | `string` | Oui | `defaultLocale`, puis la valeur par défaut de la bibliothèque | | [`defaultLocale`](#default-locale) | Alias de `sourceLocale`, pour le spread de `gt.config.json`. | `string` | Oui | — | | [`locales`](#locales) | Codes de langue cibles. | `string[]` | Non | — | | [`customMapping`](#custom-mapping) | Correspondances personnalisées de codes de langue et surcharges de propriétés. | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | Oui | — | | [`apiKey`](#api-key) | Clé d’API General Translation. | `string` | Oui | Document des secrets | | [`projectId`](#project-id) | ID de projet General Translation. | `string` | Oui | Document des secrets | | [`secretsNamespace`](#secrets-namespace) | `_id` du document privé d’identifiants. | `string` | Oui | `generaltranslation.secrets` | | [`languageField`](#language-field) | Champ du document qui stocke le paramètre régional. | `string` | Oui | `language` | | [`translateDocuments`](#translate-documents) | Filtre déterminant quels documents peuvent être traduits. | `TranslateDocumentFilter[] \| string[]` | Oui | `[]` | | [`singletons`](#singletons) | ID de documents traités comme des documents uniques. | `string[]` | Oui | `[]` | | [`singletonMapping`](#singleton-mapping) | Associe un ID source et un paramètre régional à l’ID d’un document unique traduit. | `(sourceDocumentId: string, locale: string) => string` | Oui | `` `${sourceDocumentId}-${locale}` `` | | [`showDocumentInternationalization`](#show-doc-i18n) | Ajoute automatiquement `@sanity/document-internationalization`. | `boolean` | Oui | `true` | | [`internationalizedArray`](#internationalized-array) | Configure la localisation au niveau des champs avec des tableaux internationalisés. | `GTFieldLevelLocalizationConfig` | Oui | — | | [`fieldLevelLocalization`](#field-level-localization) | Alias de `internationalizedArray`. | `GTFieldLevelLocalizationConfig` | Oui | — | | [`translationLevel`](#translation-level) | Permet de choisir une traduction au niveau du document, du champ ou mixte. | `'document' \| 'internationalizedArray' \| 'mixed'` | Oui | `'document'` | | [`fieldLevelDocuments`](#field-level-documents) | Types de documents qui utilisent la localisation au niveau des champs en mode mixte. | `TranslateDocumentFilter[] \| string[]` | Oui | `[]` | | [`ignoreFields`](#ignore-fields) | Champs copiés depuis la source sans être traduits. | `FieldMatcher[]` | Oui | `[]` | | [`dedupeFields`](#dedupe-fields) | Champs copiés depuis la source et rendus uniques par paramètre régional. | `FieldMatcher[]` | Oui | `[]` | | [`skipFields`](#skip-fields) | Champs supprimés des documents traduits. | `FieldMatcher[]` | Oui | `[]` | | [`additionalStopTypes`](#additional-stop-types) | Types de schéma supplémentaires à conserver sans traduction. | `string[]` | Oui | `[]` | | [`additionalSerializers`](#additional-serializers) | Sérialiseurs HTML personnalisés pour les marks et les types de blocs. | `Partial` | Oui | `{}` | | [`additionalDeserializers`](#additional-deserializers) | Désérialiseurs HTML personnalisés. | `CustomDeserializers` | Oui | `{}` | | [`additionalBlockDeserializers`](#additional-block-deserializers) | Règles personnalisées de désérialisation des blocs Portable Text. | `unknown[]` | Oui | `[]` | ## Options du paramètre régional [#locale-options] ### `sourceLocale` [#source-locale] **Type** `string` · **Facultatif** · **Par défaut** `defaultLocale`, puis la valeur par défaut de la bibliothèque Le code de la langue source, par exemple `en`. Le plugin détermine le paramètre régional source dans l’ordre suivant : `sourceLocale`, puis `defaultLocale`, puis la valeur par défaut de la bibliothèque `generaltranslation`. ### `defaultLocale` [#default-locale] **Type** `string` · **Facultatif** Alias de `sourceLocale`, accepté pour vous permettre de passer directement un `gt.config.json` au plugin via l’opérateur spread. Si les deux sont définis, `sourceLocale` est prioritaire. ```ts import gtConfig from './gt.config.json'; gtPlugin({ ...gtConfig }); ``` ### `locales` [#locales] **Type** `string[]` · **Obligatoire** Les codes de langue cibles vers lesquels traduire, par exemple `['es', 'fr', 'ja']`. ### `customMapping` [#custom-mapping] **Type** `CustomMapping` · **Facultatif** Correspondances personnalisées entre codes de langue et noms, ou remplacements des propriétés du paramètre régional. Transmis tel quel à la bibliothèque `generaltranslation`. Voir [CustomMapping](/docs/platform/core/reference/types/custom-mapping). ## Identifiants [#credentials] Par défaut, le plugin lit les identifiants dans un document Sanity privé. Voir [Stocker les identifiants](/docs/integrations/sanity/guides/configuring-sanity#store-credentials). ### `apiKey` [#api-key] **Type** `string` · **Facultatif** · **Par défaut** lu dans le document de secrets Votre clé API General Translation. Si elle est définie, elle est transmise à la bibliothèque au démarrage. Lorsqu’un document de secrets est présent, son champ `secret` est utilisé en priorité à l’exécution. Préférez le document de secrets pour éviter que les clés ne se retrouvent dans le contrôle de version. ### `projectId` [#project-id] **Type** `string` · **Facultatif** · **Par défaut** lu dans le document de secrets L’ID de votre projet General Translation. Lorsqu’un document de secrets est présent, son champ `project` est prioritaire à l’exécution. ### `secretsNamespace` [#secrets-namespace] **Type** `string` · **Facultatif** · **Par défaut** `generaltranslation.secrets` L’`_id` du document Sanity privé qui stocke les identifiants. Le plugin récupère ce document à partir de son `_id` et lit son champ `secret` comme clé API, ainsi que son champ `project` comme ID de projet. Un `.` au début de l’`_id` garde le document privé, même dans un dataset public. ```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, }); ``` ## Options du document [#document-options] ### `languageField` [#language-field] **Type** `string` · **Facultatif** · **Par défaut** `language` Le champ du document utilisé pour stocker le paramètre régional de chaque document. Ajoutez un champ portant ce nom à chaque type de document traduisible et interrogez-le pour récupérer un paramètre régional spécifique. ### `translateDocuments` [#translate-documents] **Type** `TranslateDocumentFilter[] | string[]` · **Facultatif** · **Par défaut** `[]` Détermine quels documents peuvent être traduits. Accepte des objets de filtrage ou des chaînes de type en syntaxe abrégée. Chaque entrée de chaîne `'article'` est normalisée en `{ type: 'article' }`, et les entrées sans `documentId` ni `type` sont exclues. ```ts gtPlugin({ sourceLocale: 'en', locales: ['es'], translateDocuments: [ { type: 'article' }, { documentId: 'homepage' }, 'page', // raccourci pour { type: 'page' } ], }); ``` `TranslateDocumentFilter` a la forme suivante : ```ts type TranslateDocumentFilter = { documentId?: string; // correspond à un document spécifique par _id type?: string; // correspond à tous les documents d'un type de schéma }; ``` Les entrées `type` déterminent également les types de schéma pour lesquels [`showDocumentInternationalization`](#show-doc-i18n) est activé. ### `singletons` [#singletons] **Type** `string[]` · **Facultatif** · **Par défaut** `[]` ID de documents traités comme des documents uniques, tels que les paramètres du site ou la navigation. Les ID de leurs documents traduits sont déterminés par [`singletonMapping`](#singleton-mapping). ### `singletonMapping` [#singleton-mapping] **Type** `(sourceDocumentId: string, locale: string) => string` · **Facultatif** · **Par défaut** `` `${sourceDocumentId}-${locale}` `` Associe l’ID du document source d’un document unique et un paramètre régional à l’ID du document traduit de ce document unique. La valeur par défaut est déterministe : `siteSettings` devient donc `siteSettings-es` pour l’espagnol. ```ts gtPlugin({ sourceLocale: 'en', locales: ['es'], singletons: ['siteSettings'], singletonMapping: (sourceDocumentId, locale) => `${sourceDocumentId}_${locale}`, }); ``` ### `showDocumentInternationalization` [#show-doc-i18n] **Type** `boolean` · **Facultatif** · **Par défaut** `true` Lorsque `true`, le plugin ajoute `@sanity/document-internationalization`, avec des badges de langue, un menu de traduction et des modèles de document par langue. Il utilise les entrées `type` de [`translateDocuments`](#translate-documents) comme types de schéma et `[sourceLocale, ...locales]` comme langues prises en charge. Il ne prend donc effet que lorsque `translateDocuments` inclut des types de document. Les types de document localisés sur place avec des tableaux internationalisés sont automatiquement exclus. Définissez cette option sur `false` pour gérer vous-même l’internationalisation. ## Localisation au niveau des champs [#field-level] La localisation au niveau des champs stocke, dans un seul document, la valeur associée à chaque paramètre régional sous la forme d’un tableau internationalisé. Les données stockées utilisent la même structure d’élément `{ _key, _type, language, value }` que `sanity-plugin-internationalized-array`, de sorte que le contenu `internationalized-array` existant ne nécessite aucune migration. ### `internationalizedArray` [#internationalized-array] **Type** `GTFieldLevelLocalizationConfig` · **Facultatif** Configure les types de schéma et les composants d’entrée du Studio utilisés pour la localisation au niveau des champs. L’identifiant du paramètre régional provient toujours de `sourceLocale` et `locales`. ```ts type GTFieldLevelLocalizationConfig = { enabled?: boolean; // par défaut : false fieldTypes?: FieldLevelFieldType[]; // par défaut : ['string', 'text'] languageTitles?: Record; getLanguageTitle?: (locale: string) => string; typePrefix?: string; // par défaut : 'internationalizedArray' includeCompatibilityTypes?: boolean; // par défaut : true components?: { input?: ComponentType | false; item?: ComponentType | false; field?: ComponentType | false; }; }; type FieldLevelFieldType = | 'string' | 'text' | 'block' | { name: string; type: string; title?: string; of?: unknown[]; fields?: unknown[]; options?: Record; }; ``` Les raccourcis `fieldTypes` intégrés sont `string`, `text` et `block` (Portable Text). Une entrée d’objet définit un type généré personnalisé. `getLanguageTitle` remplace `languageTitles` lorsque les deux sont définis. Chaque emplacement `components` accepte un composant Studio ou `false` pour utiliser le rendu par défaut de Sanity. ### `fieldLevelLocalization` [#field-level-localization] **Type** `GTFieldLevelLocalizationConfig` · **Facultatif** Un alias explicite de [`internationalizedArray`](#internationalized-array). ### `translationLevel` [#translation-level] **Type** `'document' | 'internationalizedArray' | 'mixed'` · **Facultatif** · **Par défaut** `'document'` Détermine comment les documents correspondants sont traduits : * `'document'` crée un document par paramètre régional * `'internationalizedArray'` localise sur place les champs configurés * `'mixed'` utilise la localisation au niveau des champs pour [`fieldLevelDocuments`](#field-level-documents) et la localisation au niveau du document pour tout le reste ### `fieldLevelDocuments` [#field-level-documents] **Type** `TranslateDocumentFilter[] | string[]` · **Facultatif** · **Par défaut** `[]` Sélectionne les types de documents qui utilisent des tableaux internationalisés lorsque `translationLevel` est défini sur `'mixed'`. Il accepte les mêmes filtres et les mêmes chaînes en syntaxe abrégée que [`translateDocuments`](#translate-documents). ```ts gtPlugin({ sourceLocale: 'en', locales: ['es', 'fr'], translateDocuments: [{ type: 'post' }, { type: 'siteSettings' }], internationalizedArray: { enabled: true, fieldTypes: ['string', 'text', 'block'], languageTitles: { es: 'Español', fr: 'Français' }, }, translationLevel: 'mixed', fieldLevelDocuments: [{ type: 'siteSettings' }], }); ``` Utilisez ensuite les types générés dans vos schémas : ```ts defineField({ name: 'title', type: 'internationalizedArrayString', }); ``` ## Critères de correspondance de champs [#field-matchers] `ignoreFields`, `dedupeFields` et `skipFields` acceptent chacun un tableau d’objets `FieldMatcher`. Un critère de correspondance cible des champs à l’aide d’une expression JSONPath `property` et peut, éventuellement, être limité à un seul document source via `documentId`. ```ts type FieldMatcher = { documentId?: string | null; // restreindre à un document source par _id fields?: { property: string; // expression JSONPath, par exemple $.slug type?: string; // indication de type de schéma facultative, par exemple slug }[]; }; ``` ### `ignoreFields` [#ignore-fields] **Type** `FieldMatcher[]` · **Facultatif** · **Par défaut** `[]` Champs copiés du document source vers le document traduit sans être envoyés à l’API de traduction. À utiliser pour les valeurs qui doivent rester identiques d’un paramètre régional à l’autre, comme les catégories ou les tags. ```ts gtPlugin({ sourceLocale: 'en', locales: ['es'], ignoreFields: [ // Copier la catégorie telle quelle pour tous les documents { fields: [{ property: '$.category' }] }, // Copier les tags tels quels pour un seul document { documentId: 'homepage', fields: [{ property: '$.tags' }] }, ], }); ``` ### `dedupeFields` [#dedupe-fields] **Type** `FieldMatcher[]` · **Facultatif** · **Par défaut** `[]` Champs copiés à partir de la valeur source et rendus uniques par ajout du paramètre régional lors de la création initiale du document traduit. Couramment utilisé pour les slugs. ```ts gtPlugin({ sourceLocale: 'en', locales: ['es', 'fr'], // "about" devient "about-es" et "about-fr" dedupeFields: [{ fields: [{ property: '$.slug', type: 'slug' }] }], }); ``` Pour un champ slug, le plugin met à jour la valeur `current` de l’objet slug. Si un utilisateur modifie ensuite le slug traduit, les importations suivantes conservent cette valeur modifiée. ### `skipFields` [#skip-fields] **Type** `FieldMatcher[]` · **Facultatif** · **Par défaut** `[]` Champs entièrement supprimés des documents traduits. ```ts gtPlugin({ sourceLocale: 'en', locales: ['es'], skipFields: [ { fields: [{ property: '$.slug', type: 'slug' }] }, { documentId: 'homepage', fields: [{ property: '$.debugInfo' }] }, ], }); ``` ## Sérialisation [#serialization] Le plugin sérialise les documents en HTML pour la traduction, puis désérialise le résultat dans les champs Sanity. La plupart des projets n’ont pas besoin de ces options. ### `additionalStopTypes` [#additional-stop-types] **Type** `string[]` · **Facultatif** · **Par défaut** `[]` Types de schéma supplémentaires à conserver sans les traduire, ajoutés aux [types d’exclusion par défaut](#stop-types). ```ts gtPlugin({ sourceLocale: 'en', locales: ['es'], additionalStopTypes: ['codeBlock', 'mux.video', 'mux.videoAsset'], }); ``` ### `additionalSerializers` [#additional-serializers] **Type** `Partial` · **Facultatif** · **Par défaut** `{}` Sérialiseurs personnalisés fusionnés avec ceux par défaut, selon la structure des composants `@portabletext/to-html` (`types`, `marks`, `block`, `list`, `listItem`, etc.). Ils sont le plus souvent utilisés pour sérialiser des `marks` personnalisés. Pour les marks personnalisés, encapsulez la sortie avec `attachGTData` afin que les données du `mark` soient préservées pendant la traduction. ```ts title="sanity.config.ts" import { attachGTData, gtPlugin } from 'gt-sanity'; gtPlugin({ sourceLocale: 'en', locales: ['es'], additionalSerializers: { marks: { link: ({ value, children }) => attachGTData(`${children}`, value, 'markDef'), inlineMath: ({ value, children }) => attachGTData(`${children}`, value, 'markDef'), }, }, }); ``` `attachGTData(html, data, 'markDef')` encode `data` en base64 dans un attribut `data-gt-internal` sur le premier élément de `html`, puis renvoie le HTML mis à jour. Lors de l’importation, le plugin lit cet attribut pour reconstruire la définition de la marque. ```ts function attachGTData( html: string, data: Record, type: 'markDef' ): string; ``` ### `additionalDeserializers` [#additional-deserializers] **Type** `CustomDeserializers` · **Facultatif** · **Par défaut** `{}` Désérialiseurs personnalisés qui convertissent les éléments HTML traduits en objets Sanity, associés à leur type. ```ts type CustomDeserializers = { types?: Record< string, (element: HTMLElement) => Record | unknown[] >; } & Record; ``` ### `additionalBlockDeserializers` [#additional-block-deserializers] **Type** `unknown[]` · **Facultatif** · **Par défaut** `[]` Règles supplémentaires de désérialisation pour les blocs Portable Text, ajoutées aux règles intégrées du plugin. Chaque règle est un objet doté d’une méthode `deserialize(node, next)`, conforme au format de règle de `@portabletext/block-tools`. ## Types d’exclusion par défaut [#stop-types] Ces types de schéma sont conservés et ne sont jamais envoyés à la traduction. Vous pouvez en ajouter d’autres avec [`additionalStopTypes`](#additional-stop-types). ```ts const defaultStopTypes = [ 'reference', 'date', 'datetime', 'file', 'geopoint', 'image', 'number', 'crop', 'hotspot', 'boolean', 'url', 'color', 'code', ]; ``` Les champs de slug ne sont *pas* ignorés par défaut, donc la chaîne `current` d’un slug est traduite, sauf si vous utilisez [`dedupeFields`](#dedupe-fields) ou [`skipFields`](#skip-fields). ## Helpers exportés [#helpers] `gt-sanity` exporte également des éléments de base pour la sérialisation avancée et les nœuds de document personnalisés. La plupart des projets n’en ont pas besoin. * `TranslationsTab` — le composant d’onglet de document pour `structureTool`. Voir [Configurer Sanity](/docs/integrations/sanity/guides/configuring-sanity#translations-tab). * `attachGTData` / `detachGTData` — associent et lisent les données de balisage encodées utilisées par les sérialiseurs personnalisés. * `BaseDocumentSerializer`, `BaseDocumentDeserializer`, `BaseDocumentMerger` — les implémentations par défaut pour la sérialisation, la désérialisation et la fusion. * `defaultStopTypes`, `customSerializers` — les types d’exclusion et le jeu de sérialiseurs par défaut. * `documentInternationalization` et ses types (`DocumentInternationalizationConfig`, `Language`, `Metadata`, `TranslationReference`) — réexportés depuis `@sanity/document-internationalization`. ## Exemple complet [#complete-example] ```ts title="sanity.config.ts" import { defineConfig } from 'sanity'; import { attachGTData, gtPlugin } from 'gt-sanity'; export default defineConfig({ plugins: [ gtPlugin({ // Requis sourceLocale: 'en', locales: ['es', 'fr', 'de', 'ja'], // Documents et champs languageField: 'language', translateDocuments: [{ type: 'article' }, { type: 'page' }], singletons: ['siteSettings', 'navigation'], singletonMapping: (id, locale) => `${id}_${locale}`, // Comportement des champs ignoreFields: [{ fields: [{ property: '$.category' }] }], dedupeFields: [{ fields: [{ property: '$.slug', type: 'slug' }] }], skipFields: [{ fields: [{ property: '$.internalNotes' }] }], // Sérialisation — uniquement si les valeurs par défaut ne couvrent pas votre schéma additionalSerializers: { marks: { link: ({ value, children }) => attachGTData(`${children}`, value, 'markDef'), }, }, }), ], }); ```