# sanity: Démarrage rapide avec Sanity
URL: https://generaltranslation.com/fr/docs/sanity/guides/quickstart.mdx
---
title: Démarrage rapide avec Sanity
description: Intégrez General Translation à Sanity CMS avec gt-sanity
---

**Prérequis :** Sanity Studio v5+, React 19+, projet Sanity existant

<Callout type="warn">
  **Des modifications du schéma et du frontend sont nécessaires.** Chaque type de document que vous traduisez doit inclure un champ `language` dans son schéma — consultez la [configuration du champ de langue](/docs/sanity#language-field) pour plus de détails.
  Cependant, les traductions sont stockées dans des documents distincts. Vous devrez donc mettre à jour vos requêtes frontend pour récupérer la version dans la bonne langue.
  Consultez [Interroger le contenu traduit](#querying-translated-content) ci-dessous pour voir des exemples.
</Callout>

## Installation

Installez le package `gt-sanity` dans le dossier de votre studio Sanity :

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install gt-sanity
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-sanity
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-sanity
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-sanity
    ```
  </Tab>
</Tabs>

## Configuration

<Steps>
  <Step title="Ajoutez le plugin à votre configuration Sanity">
    ```typescript 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'], // Remplacez par vos paramètres régionaux cibles
          translateDocuments: [{ type: 'article' }, { type: 'page' }], // Types de documents pour lesquels activer les traductions
        })
      ]
    })
    ```

    Lorsque `translateDocuments` est fourni, le plugin ajoute automatiquement les fonctionnalités de @sanity/document-internationalization : badges de langue, menu de traduction dans la barre d’outils du document et templates de document par langue. Définissez `showDocumentInternationalization: false` pour désactiver cette fonctionnalité.
  </Step>

  <Step title="Ajoutez un champ de langue à vos schémas">
    Chaque type de document que vous traduisez doit comporter un champ `language` :

    ```typescript 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 avez configuré un `languageField` personnalisé dans les options du plugin, utilisez ce nom à la place de `'language'`.
  </Step>

  <Step title="Configurez les identifiants d'API">
    Dans votre dossier Studio, créez un fichier nommé `populateSecrets.js` avec le contenu suivant :

    ```javascript title="populateSecrets.js"
    import { getCliClient } from 'sanity/cli';

    const client = getCliClient({ apiVersion: '2026-04-06' });

    client.createOrReplace({
      // Le `.` dans cet _id garantit que le document restera privé,
      // même dans un dataset public !
      _id: 'generaltranslation.secrets',
      _type: 'generaltranslationSettings',
      secret: process.env.GT_API_KEY,
      project: process.env.GT_PROJECT_ID,
    });
    ```

    Ensuite, obtenez une clé d&#39;API de production sur [dash.generaltranslation.com](https://dash.generaltranslation.com).

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

    Vérifiez que le document a bien été créé à l&#39;aide de l&#39;outil Vision dans le Studio, puis exécutez la requête `*[_id == 'generaltranslation.secrets']`.

    Remarque : si vous avez plusieurs datasets, vous devrez effectuer cette opération dans chacun d&#39;eux.

    Si le document a bien été trouvé dans votre ou vos datasets, supprimez `populateSecrets.js`.

    <Callout type="warn">
      Ces identifiants seront stockés dans votre base de données Sanity. Par défaut, ils sont stockés dans le document `generaltranslation.secrets`, qui est privé par défaut, même dans un dataset public.
      Toutefois, si vous craignez qu&#39;ils soient exposés aux utilisateurs authentifiés de votre Studio, vous pouvez contrôler l&#39;accès à ce chemin via le [contrôle d&#39;accès basé sur les rôles](https://www.sanity.io/docs/access-control).
    </Callout>
  </Step>

  <Step title="(Facultatif) Ajoutez un onglet traduction dédié">
    Le plugin ajoute automatiquement une action **traduire** à chaque document, qui ouvre une boîte de dialogue. Si vous souhaitez également une vue par onglet dédiée, ajoutez le composant `TranslationsTab` à vos vues de document :

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

    export default defineConfig({
      // ... votre configuration
      plugins: [
        structureTool({
          structure: (S) =>
            S.list()
              .title('Content')
              .items(S.documentTypeListItems()),
          defaultDocumentNode: (S, { schemaType }) => {
            return S.document().views([
              S.view.form(),
              S.view
                .component(TranslationsTab)
                .title('General Translation')
            ])
          }
        }),
        gtPlugin({
          sourceLocale: 'en',
          locales: ['es', 'zh', 'ja']
        })
      ]
    })
    ```
  </Step>
</Steps>

## Utilisation

Une fois la configuration terminée, vous pouvez traduire des documents directement depuis votre Sanity Studio :

1. Ouvrez n’importe quel document dans votre Studio
2. Cliquez sur le bouton **Traduire** dans la barre d’actions du document — une boîte de dialogue s’ouvrira
3. Sélectionnez les langues cibles
4. Cliquez sur **Generate Translations** pour envoyer le contenu en traduction
5. Par défaut, le plugin réimporte automatiquement les traductions dans votre document dès qu’elles sont prêtes.
6. En outre, les documents importés sont automatiquement analysés pour repérer les références à d’autres documents, puis mis à jour pour pointer vers leurs traductions correspondantes.

## Interroger le contenu traduit

Le plugin stocke les traductions dans des documents distincts avec un champ `language` (configurable via [`languageField`](/docs/sanity/api/plugin-config)). Vos requêtes GROQ existantes pour le contenu source continuent de fonctionner telles quelles.

Pour récupérer le contenu traduit, filtrez par le champ `language` :

<Tabs items={["Requête de base", "Requête localisée"]}>
  <Tab value="Requête de base">
    Vos requêtes existantes restent les mêmes — aucune modification nécessaire :

    ```plaintext
    // Récupérer tous les articles (renvoie les documents dans la langue source)
    *[_type == "article"]{
      title,
      slug,
      body
    }
    ```
  </Tab>

  <Tab value="Requête localisée">
    Pour récupérer les documents traduits, ajoutez un filtre sur `language` :

    ```plaintext
    // Récupérer les articles en espagnol
    *[_type == "article" && language == "es"]{
      title,
      slug,
      body
    }

    // Récupérer un article spécifique dans une langue donnée
    *[_type == "article" && slug.current == "hello-world" && language == "es"][0]{
      title,
      body
    }

    // Récupérer les articles dans n’importe quelle langue
    *[_type == "article"]{
      title,
      slug,
      body,
      language
    }
    ```
  </Tab>
</Tabs>

<Callout type="info">
  Les documents source n’ont pas le champ `language` défini par défaut. Pour interroger le contenu source en même temps que les traductions, vous pouvez filtrer les documents dont `language` correspond soit à votre paramètre régional source, soit n’est pas défini : `language == "en" || !defined(language)`.
</Callout>

## Étapes suivantes

* [Guide de configuration](/docs/sanity/guides/configuration) - Personnalisez le comportement du plugin
* [Guide de sérialisation](/docs/sanity/guides/serialization) - Définissez des règles de sérialisation personnalisées
* [Référence de l’API](/docs/sanity/api/plugin-config) - Toutes les options de configuration