Plugin Configuration

API reference for gtPlugin configuration options

Overview

The gtPlugin function configures General Translation for your Sanity Studio.

import { gtPlugin } from 'gt-sanity'

gtPlugin(config: GTPluginConfig)

GTPluginConfig

Prop

Type

IgnoreFields

Configure fields to exclude from translation:

type IgnoreFields = {
  documentId?: string;
  fields?: Array<{
    property: string;
    type?: string;
  }>;
};

Example

gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  ignoreFields: [
    // Ignore slug on all documents
    {
      fields: [{ property: 'slug' }],
    },
    // Ignore specific fields on document with id 'article'
    {
      documentId: 'article',
      fields: [{ property: 'internalNotes' }, { property: 'canonical' }],
    },
  ],
});

TranslateDocumentFilter

Filter which documents are available for translation:

type TranslateDocumentFilter = {
  documentId?: string; // Specific document ID
  type?: string; // Document type
};

Example

gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  translateDocuments: [
    { type: 'article' },
    { type: 'page' },
    { documentId: 'homepage' },
  ],
});

Serializer

Custom function to convert a Sanity block to HTML:

type Serializer = (props: {
  value: any;
  isInline?: boolean;
  children?: string;
}) => string;

Example

import { attachGTData, gtPlugin } from 'gt-sanity';
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  additionalSerializers: {
    link: ({ value, children }) =>
      attachGTData(`<a>${children}</a>`, value, 'markDef'),
  },
});

Default stop types

These types are preserved but not sent for translation:

const defaultStopTypes = [
  'reference',
  'crossDatasetReference',
  'date',
  'datetime',
  'file',
  'geopoint',
  'image',
  'number',
  'slug',
  'url',
];

Add more with additionalStopTypes:

gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  additionalStopTypes: ['codeBlock', 'mathFormula'],
});

Complete example

sanity.config.ts
import { defineConfig } from 'sanity';
import { attachGTData, gtPlugin } from 'gt-sanity';

export default defineConfig({
  plugins: [
    gtPlugin({
      // Required
      sourceLocale: 'en',
      locales: ['es', 'fr', 'de', 'ja'],

      // Document handling
      languageField: 'language',
      singletons: ['siteSettings', 'navigation'],
      singletonMapping: (id, locale) => `${id}_${locale}`,

      // Filtering
      translateDocuments: [{ type: 'article' }, { type: 'page' }],
      ignoreFields: [{ fields: [{ property: 'slug' }] }],

      // Serialization - Do not use this unless you know what you are doing!
      additionalSerializers: {
        // Additional serializers for marks (custom annotations)
        marks: {
          link: ({ value, children }) =>
            attachGTData(`<a>${children}</a>`, value, 'markDef'),
          inlineMath: ({ value, children }) =>
            attachGTData(`<span>${children}</span>`, value, 'markDef'),
        },
      },
    }),
  ],
});

Next steps

How is this guide?