# General Translation Integrations: Démarrage rapide
URL: https://generaltranslation.com/fr/docs/integrations/sanity/quickstart.mdx
---

title: Démarrage rapide
description: Installez gt-sanity, ajoutez le plugin General Translation à Sanity Studio et traduisez votre premier document.
related:
  links:
    - /docs/integrations/sanity/guides/translating-content
    - /docs/integrations/sanity/guides/managing-translations
    - /docs/integrations/sanity/guides/querying-translations
    - /docs/integrations/sanity/guides/configuring-sanity

---

Le plugin `gt-sanity` de General Translation traduit les documents Sanity directement depuis Sanity Studio.

Le plugin utilise une localisation au niveau du document : chaque traduction est enregistrée dans un document Sanity distinct avec un champ de langue, par exemple `language: "es"`. Les traductions sont liées au document source via un document `translation.metadata` géré par `@sanity/document-internationalization`.

## Avant de commencer [#before-start]

Vous avez besoin des éléments suivants :

* Sanity Studio 5.0.0 ou version ultérieure.
* React 19.2.0 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.

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

### 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 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: '2026-04-06' });

client.createOrReplace({
  // Le `.` en tête de cet _id garde le document privé,
  // même dans un dataset public.
  _id: 'generaltranslation.secrets',
  _type: 'generaltranslation.secrets',
  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`.

### 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 **Générer des traductions**.

Dans la boîte de dialogue du document, le plugin vérifie régulièrement si des traductions sont terminées et les importe automatiquement. Après l’importation, il met à jour les références du document et publie les documents traduits, car l’importation automatique, la mise à jour automatique et la publication automatique sont activées par défaut dans cette boîte de dialogue.

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]

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.

<Tabs items={['Requête source', 'Requête localisée']}>
  <Tab value="Requête source">
    ```text
    // Par défaut, les documents dans la langue source ne définissent pas le champ language
    *[_type == "article" && !defined(language)]{
      title,
      slug,
      body
    }
    ```
  </Tab>

  <Tab value="Requête localisée">
    ```text
    // Récupère les articles en espagnol
    *[_type == "article" && language == "es"]{
      title,
      slug,
      body
    }
    ```
  </Tab>
</Tabs>

Consultez [Interroger les traductions](/docs/integrations/sanity/guides/querying-translations) pour voir d&#39;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