# General Translation Integrations: Démarrage rapide URL: https://generaltranslation.com/fr/docs/integrations/sanity/quickstart.mdx Docs index: https://generaltranslation.com/llms.txt Description: Installez gt-sanity, ajoutez le plugin General Translation à Sanity Studio et traduisez votre premier document. Le plugin `gt-sanity` traduit les documents directement depuis Sanity Studio. Il prend en charge la localisation au niveau du document et au niveau du champ ; ce démarrage rapide utilise la configuration au niveau du document par défaut, où chaque traduction est un document distinct doté d’un champ `language` et d’un document `translation.metadata` géré par `@sanity/document-internationalization`. ## Avant de commencer [#before-start] Vous avez besoin des éléments suivants : * Sanity Studio 6.9.2 ou version ultérieure. Les Studios utilisant Sanity 6.0 à 6.8 utilisent encore la génération 3 de `@sanity/ui` et doivent rester sur `gt-sanity` 3.1.x. * React 19.2.0 ou version ultérieure. * Node.js 22.12 ou version ultérieure. * Un projet Sanity existant. * Un [ID de projet](/docs/platform/dashboard/get-started) General Translation et une [clé API](/docs/platform/dashboard/reference/api-keys) de production. ## Démarrage rapide [#quickstart] ### 1. Installer `gt-sanity` [#install] Installez le plugin dans votre projet Sanity Studio. `gt-sanity` résout `@sanity/ui`, `@sanity/icons`, `@sanity/schema` et `@sanity/mutator` à partir de votre Studio en tant que dépendances homologues, afin qu'une seule copie de chaque document unique du runtime Studio reste dans l'arborescence. Un Studio Sanity 6.9.2+ fournit déjà les quatre. ```bash npm install gt-sanity ``` ```bash yarn add gt-sanity ``` ```bash bun add gt-sanity ``` ```bash pnpm add gt-sanity ``` ### 2. Ajouter le plugin [#add-plugin] Ajoutez `gtPlugin` à `sanity.config.ts`. Spécifiez votre paramètre régional source, les paramètres régionaux cibles et les types de document à traduire. ```ts title="sanity.config.ts" import { defineConfig } from 'sanity'; import { gtPlugin } from 'gt-sanity'; export default defineConfig({ // ... votre configuration existante plugins: [ gtPlugin({ sourceLocale: 'en', locales: ['es', 'zh', 'ja'], translateDocuments: [{ type: 'article' }, { type: 'page' }], }), ], }); ``` Lorsque `translateDocuments` inclut des types de documents, le plugin ajoute automatiquement le plugin `@sanity/document-internationalization` : des badges de langue, un menu de traduction dans la barre d’outils du document et des modèles de documents par langue. Définissez `showDocumentInternationalization: false` pour désactiver cette fonctionnalité. ### 3. Ajouter un champ de langue [#language-field] Chaque type de document que vous traduisez avec une localisation au niveau du document doit comporter un champ de langue. Par défaut, il s’appelle `language`. ```ts title="schema/article.ts" import { defineField, defineType } from 'sanity'; export const articleType = defineType({ name: 'article', title: 'Article', type: 'document', fields: [ // ... vos champs existants defineField({ name: 'language', type: 'string', readOnly: true, hidden: true, }), ], }); ``` Si vous définissez un [`languageField`](/docs/integrations/sanity/reference/plugin-configuration#language-field) personnalisé dans les options du plugin, utilisez ce nom dans votre schéma au lieu de `language`. ### 4. Enregistrer les identifiants [#credentials] Le plugin lit votre clé API de General Translation et votre ID de projet dans un document Sanity privé. Créez un fichier temporaire `populateSecrets.js` dans votre dossier Studio. ```js title="populateSecrets.js" import { getCliClient } from 'sanity/cli'; const client = getCliClient({ apiVersion: '2025-09-15' }); client.createOrReplace({ // Le `.` en tête de cet _id garde le document privé, // même dans un dataset public. _id: 'generaltranslation.secrets', _type: 'generaltranslationSettings', secret: process.env.GT_API_KEY, project: process.env.GT_PROJECT_ID, }); ``` Exécutez le script avec vos identifiants : ```bash GT_API_KEY=your-api-key GT_PROJECT_ID=your-project-id npx sanity exec populateSecrets.js --with-user-token ``` Le document `_id` doit correspondre au `secretsNamespace` du plugin (par défaut `generaltranslation.secrets`). Le plugin lit le champ `secret` comme clé API et le champ `project` comme ID du projet. Vérifiez que le document existe à l’aide de l’outil Vision dans votre Studio : ```text *[_id == 'generaltranslation.secrets'] ``` Si vous utilisez plusieurs jeux de données, répétez cette opération pour chacun d’eux. Une fois la vérification effectuée, supprimez `populateSecrets.js`. Un `.` en tête empêche ce document d’apparaître dans les requêtes non authentifiées sur des jeux de données publics, mais l’accès authentifié à Studio reste soumis aux rôles de votre projet Sanity. Utilisez le [contrôle d’accès basé sur les rôles de Sanity](https://www.sanity.io/docs/access-control) afin que seuls les utilisateurs ayant besoin de l’intégration puissent lire le jeu de données, et ne commitez jamais le script ni les identifiants. ### 5. Traduire un document [#translate-document] 1. Ouvrez un document dans la langue source dans Sanity Studio. 2. Cliquez sur **Traduire** dans la barre d’actions du document. 3. Sélectionnez les paramètres régionaux cibles. 4. Cliquez sur **Traduire**. Avec cette configuration au niveau du document, le plugin vérifie régulièrement si des traductions sont terminées et les importe automatiquement en tant que brouillons. La correction des références et la publication sont désactivées par défaut ; utilisez les contrôles de la boîte de dialogue ou configurez leur état initial avec [`autoPatchReferences`](/docs/integrations/sanity/reference/plugin-configuration#auto-patch-references) et [`autoPublish`](/docs/integrations/sanity/reference/plugin-configuration#auto-publish). Vérifiez les documents importés dans la perspective **Brouillons** de Sanity, puis publiez-les avant d’effectuer des requêtes depuis un frontend qui n’utilise que le contenu publié. (Consultez les guides complets pour [traduire le contenu](/docs/integrations/sanity/guides/translating-content) et [gérer les traductions](/docs/integrations/sanity/guides/managing-translations)). ### 6. Interroger le contenu traduit [#query-content] Avec cette configuration au niveau du document, les traductions sont stockées dans des documents séparés avec un champ de langue. Pour récupérer du contenu traduit, filtrez sur le champ de langue. ```text // Par défaut, les documents dans la langue source ne définissent pas le champ language *[_type == "article" && !defined(language)]{ title, slug, body } ``` ```text // Récupère les articles en espagnol *[_type == "article" && language == "es"]{ title, slug, body } ``` (Consultez [Interroger les traductions](/docs/integrations/sanity/guides/querying-translations) pour voir d'autres exemples de requêtes). ## Next steps - /docs/integrations/sanity/guides/translating-content - /docs/integrations/sanity/guides/managing-translations - /docs/integrations/sanity/guides/querying-translations - /docs/integrations/sanity/guides/configuring-sanity ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.