Vue d’ensemble

gt-sanity v2 est une version majeure qui met à jour le plugin pour prendre en charge Sanity v5 et React 19, simplifie la configuration grâce à une boîte de dialogue de traduction sans configuration préalable, et ajoute de nouvelles options pour contrôler les champs affichés dans les documents traduits.

Nouveautés

Configuration simplifiée : boîte de dialogue Traduire

Le principal changement de la v2 concerne la manière dont les développeurs interagissent avec l’interface de traduction. Auparavant, vous deviez configurer structureTool avec un defaultDocumentNode personnalisé pour ajouter un onglet Traductions à vos documents. Désormais, le plugin ajoute automatiquement une action Traduire à chaque document : un clic dessus ouvre une boîte de dialogue avec l’interface de traduction complète.

Autrement dit, la configuration minimale se limite à deux étapes : installer le plugin et l’ajouter à votre configuration.

import { defineConfig } from 'sanity';
import { gtPlugin } from 'gt-sanity';

export default defineConfig({
  plugins: [
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'zh', 'ja'],
    }),
  ],
});

Le composant TranslationsTab est toujours exporté pour les utilisateurs qui préfèrent un onglet dédié, mais il est désormais facultatif.

Option de configuration defaultLocale

Si vous avez déjà un gt.config.json issu de gt-next ou de gt-react, vous pouvez maintenant l’inclure directement dans la configuration du plugin via l’opérateur spread. Le champ defaultLocale est accepté comme alias de sourceLocale :

import gtConfig from './gt.config.json';

gtPlugin({
  ...gtConfig, // { defaultLocale: 'en', locales: ['es', 'zh', 'ja'] }
});

Si sourceLocale et defaultLocale sont tous deux définis, sourceLocale est prioritaire.

Option skipFields

Une nouvelle option de configuration skipFields supprime complètement les champs correspondants des documents traduits. Cela diffère de ignoreFields, qui copie la valeur du document source sur la traduction — skipFields garantit que le champ n’apparaît pas du tout dans le document traduit.

Utilisez skipFields pour des champs comme les slugs de document uniques, les URL canoniques SEO ou des métadonnées propres au document source qui ne doivent pas être reportées dans les traductions :

gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  skipFields: [
    { fields: [{ property: '$.slug', type: 'slug' }] },
    { fields: [{ property: '$.canonicalUrl' }] },
  ],
});

À l’inverse, ignoreFields sert aux champs que vous ne voulez pas traduire, mais que vous souhaitez tout de même recopier depuis la source — par exemple les catégories, les tags ou les métadonnées internes qui doivent avoir la même valeur dans toutes les langues.

Comme pour ignoreFields, vous pouvez limiter les règles d’exclusion à certains documents à l’aide de documentId, et utiliser des expressions JSONPath pour property.

Comportement amélioré de ignoreFields

En v1, les champs ignorés n’étaient restaurés à partir du document source qu’après la traduction — le contenu était donc tout de même envoyé à l’API de traduction. En v2, les champs ignorés sont désormais retirés du document avant la sérialisation, de sorte que le contenu ignoré n’est jamais envoyé à l’API.

Changements incompatibles

Sanity v5 et React 19

gt-sanity v2 nécessite Sanity v5+ et React 19+. Si vous êtes encore sur Sanity v3 ou v4, continuez d’utiliser gt-sanity v1.

L’onglet Traductions n’est plus ajouté automatiquement

Le plugin n’ajoute plus automatiquement de vue d’onglet « Traductions ». La boîte de dialogue Traduire la remplace désormais comme mode d’interaction par défaut. Si vous souhaitez toujours un onglet dédié, vous pouvez l’ajouter manuellement — voir le Quickstart.

Liens

• Quickstart
• Guide de configuration
• Référence API