Panoramica

gt-sanity v2 è una release importante che aggiorna il plugin con il supporto a Sanity v5 e React 19, semplifica il setup con una finestra di dialogo di traduzione senza configurazione e aggiunge nuove opzioni per controllare quali campi compaiono nei documenti tradotti.

Novità

Setup più semplice: dialogo Traduci

Il cambiamento più importante della v2 riguarda il modo in cui gli sviluppatori interagiscono con l'interfaccia utente di traduzione. In precedenza, dovevi configurare structureTool con un defaultDocumentNode personalizzato per aggiungere una scheda Translations ai tuoi documenti. Ora, il plugin aggiunge automaticamente un'azione Traduci a ogni documento: facendo clic su di essa si apre un dialogo con l'intera interfaccia utente di traduzione.

Questo significa che il setup minimo richiede solo due passaggi: installare il plugin e aggiungerlo alla configurazione.

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

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

Il componente TranslationsTab viene ancora esportato per gli utenti che preferiscono una scheda dedicata, ma ora è facoltativo.

Opzione di configurazione defaultLocale

Se hai già un file gt.config.json perché usi gt-next o gt-react, ora puoi includerlo direttamente nella configurazione del plugin. Il campo defaultLocale è accettato come alias di sourceLocale:

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

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

Se vengono specificati sia sourceLocale sia defaultLocale, sourceLocale ha la precedenza.

Opzione skipFields

Una nuova opzione di configurazione, skipFields, rimuove completamente dai documenti tradotti i campi corrispondenti. A differenza di ignoreFields, che copia il valore del documento sorgente nella traduzione, skipFields garantisce che il campo non compaia affatto nel documento tradotto.

Usa skipFields per campi come slug documento univoci, URL canonici SEO o metadati presenti solo nel documento sorgente che non dovrebbero essere riportati nelle traduzioni:

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

Al contrario, ignoreFields serve per i campi che non vuoi tradurre ma che vuoi comunque copiare dall'origine, come categorie, tag o metadati interni che devono avere lo stesso valore in tutte le lingue.

Come con ignoreFields, puoi limitare le regole di esclusione a documenti specifici usando documentId e usare espressioni JSONPath per property.

Comportamento di ignoreFields migliorato

Nella v1, i campi ignorati venivano ripristinati dal documento sorgente solo dopo la traduzione, ma il contenuto veniva comunque inviato all'API di traduzione. Nella v2, invece, i campi ignorati vengono rimossi dal documento prima della serializzazione, quindi il contenuto ignorato non viene mai inviato all'API.

Modifiche non retrocompatibili

Sanity v5 e React 19

gt-sanity v2 richiede Sanity v5+ e React 19+. Se utilizzi ancora Sanity v3 o v4, continua a usare gt-sanity v1.

La scheda Translations non viene più registrata automaticamente

Il plugin non registra più automaticamente una vista con scheda Translations. Il dialogo Traduci la sostituisce come modalità di interazione predefinita. Se vuoi comunque una scheda dedicata, puoi aggiungerla manualmente — vedi il Quickstart.

Link

• Quickstart
• Guida alla configurazione
• Riferimento API