# 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` traduit les documents directement depuis Sanity Studio.

Le plugin 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 : chaque traduction est enregistrée dans un document Sanity distinct avec un champ de langue, par exemple `language: "es"`, ainsi qu’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.
* Node.js 18 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 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: '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 **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. 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]

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.

<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