# sanity: Introduction
URL: https://generaltranslation.com/en-GB/docs/sanity.mdx
---
title: Introduction
description: Overview of the General Translation Sanity CMS plugin
---

## Overview

The `gt-sanity` plugin integrates General Translation directly into Sanity Studio v5+.
It provides a complete translation workflow for your Sanity content, including automatic translation, document-level translation, and translated document management.

```typescript title="sanity.config.ts"
import { defineConfig } from 'sanity';
import { gtPlugin } from 'gt-sanity';

export default defineConfig({
  // ... your existing config
  plugins: [
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'zh', 'ja'],
    }),
  ],
});
```


## How it works

The plugin uses Sanity's [document-level localisation](https://www.sanity.io/docs/studio/localization) approach: for each source document, it creates separate translated documents with a `language` field set to the target locale.

<Callout type="warn">
  **Schema and query changes required.** Each document type you translate must include a `language` field in its schema (see below).
  You will also need to update your frontend queries to fetch the correct language version.
  See the [quickstart](/docs/sanity/guides/quickstart#querying-translated-content) for set-up and GROQ query examples.
</Callout>

### Language field

Each document type you translate must define a `language` field:

```typescript
import { defineField, defineType } from 'sanity'

export const articleType = defineType({
  name: 'article',
  title: 'Article',
  type: 'document',
  fields: [
    // ... your existing fields
    defineField({
      name: 'language',
      type: 'string',
      readOnly: true,
      hidden: true,
    }),
  ],
})
```

If you use a custom `languageField` name in your plugin config, the field name must be the same.

## Key features

### Document translation

Translate entire documents into multiple target locales. The plugin handles Portable Text, nested objects, arrays, and custom schema types.

### Batch operations

Translate multiple documents or your entire site at once. Import all translations, import only missing translations, or selectively import by locale.

### Intelligent serialisation

Documents are serialised to HTML for translation, preserving structure and metadata.
Translations for languages with different grammatical structures have their structure automatically modified to sound natural in the target language.

Custom serialisers let you control how specific field types are handled.

## Plugin UI

The plugin provides three main UI components:

### Translate action (dialogue)

The Translate action is added automatically to every document. Clicking the **Translate** button in the document action bar opens a dialogue with the full translation UI — no extra configuration required.

### Translations tab (optional)

![TranslationsTab](https://assets.gtx.dev/docs/sanity-translations-tab.png)

The `TranslationsTab` can optionally be added as a dedicated document view via `structureTool`. This provides the same translation functionality as the dialogue, embedded as a tab in the document editor.

See the [Quickstart](/docs/sanity/guides/quickstart#configuration) for set-up instructions.

### Translations page

![TranslationsPage](https://assets.gtx.dev/docs/sanity-translations-page.png)

The Translations page is a Sanity page that provides a site-wide view of the translations across your entire site.
From this central management page, you can:

* Bulk generate translations for all documents
* Bulk import translations for all documents
* Bulk import translations for specific documents
* Repair language references and links to other documents
* Bulk publish translations for every document

## Supported content types

The plugin handles most Sanity schema types.

You can configure custom types with [custom serialisers](/docs/sanity/guides/serialization).

Fields such as slugs can be configured with `dedupeFields` so new translated documents start with a source-derived value and a unique locale suffix, such as `about-es` or `about-fr`.

## Next steps

* [Quickstart](/docs/sanity/guides/quickstart) - Get started with installation and setup
* [Configuration Guide](/docs/sanity/guides/configuration) - Customise plugin behaviour
* [Serialization Guide](/docs/sanity/guides/serialization) - Define custom serialisation rules