Sanity Quickstart

Prerequisites: Sanity Studio v3+, existing Sanity project

Installation

Install the gt-sanity package in your Sanity studio directory:

npm install gt-sanity

yarn add gt-sanity

bun add gt-sanity

pnpm add gt-sanity

Configuration

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'] // Replace with your target locales
    })
  ]
})

In your Studio folder, create a file called populateSecrets.js with the following content:

populateSecrets.js

import { getCliClient } from 'sanity/cli';

const client = getCliClient({ apiVersion: '2025-09-15' });

client.createOrReplace({
  // The `.` in this _id will ensure the document is private
  // even in a public dataset!
  _id: 'generaltranslation.secrets',
  _type: 'generaltranslationSettings',
  secret: process.env.GT_API_KEY,
  project: process.env.GT_PROJECT_ID,
});

Next, get a production API key at dash.generaltranslation.com.

Run the script with your credentials:

GT_API_KEY=your-api-key GT_PROJECT_ID=your-project-id npx sanity exec populateSecrets.js --with-user-token

Verify that the document was created using the Vision Tool in the Studio and query *[_id == 'generaltranslation.secrets'].

Note: If you have multiple datasets, you'll have to do this across all of them.

If the document was found in your dataset(s), delete populateSecrets.js.

These credentials will be stored in your Sanity database. By default, they are stored in the generaltranslation.secrets document, which is private by default, even in a public dataset. However, if you have concerns about this being exposed to authenticated users of your studio, you can control access to this path with role-based access control.

Configure your document structure to include the translations view:

sanity.config.ts

import { defineConfig } from 'sanity'
import { structureTool } from 'sanity/structure'
import { gtPlugin, TranslationsTab } from 'gt-sanity'

export default defineConfig({
  // ... your config
  plugins: [
    structureTool({
      structure: (S) =>
        S.list()
          .title('Content')
          .items(S.documentTypeListItems()),
      defaultDocumentNode: (S, { schemaType }) => {
        return S.document().views([
          S.view.form(),
          S.view
            .component(TranslationsTab)
            .title('General Translation')
        ])
      }
    }),
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'zh', 'ja'] // Replace with your target locales
    })
  ]
})

Usage

Once configured, you can translate documents directly from your Sanity Studio:

Open any document in your Studio
Click the General Translation tab
Select target languages
Click Generate Translations to send content for translation
By default, the plugin will automatically import the translations as back into your document, as soon as they are ready.
Additionally, imported documents will be automatically scanned for references to other documents, and will be automatically patched to point to the correct translations for those documents.

Next steps

Configuration Guide - Customize plugin behavior
Serialization Guide - Custom serialization rules
API Reference - Full configuration options

Prerequisites: Sanity Studio v3+, existing Sanity project

Installation

Install the gt-sanity package in your Sanity studio directory:

npm install gt-sanity

yarn add gt-sanity

bun add gt-sanity

pnpm add gt-sanity

Configuration

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'] // Replace with your target locales
    })
  ]
})

In your Studio folder, create a file called populateSecrets.js with the following content:

populateSecrets.js

import { getCliClient } from 'sanity/cli';

const client = getCliClient({ apiVersion: '2025-09-15' });

client.createOrReplace({
  // The `.` in this _id will ensure the document is private
  // even in a public dataset!
  _id: 'generaltranslation.secrets',
  _type: 'generaltranslationSettings',
  secret: process.env.GT_API_KEY,
  project: process.env.GT_PROJECT_ID,
});

Next, get a production API key at dash.generaltranslation.com.

Run the script with your credentials:

GT_API_KEY=your-api-key GT_PROJECT_ID=your-project-id npx sanity exec populateSecrets.js --with-user-token

Verify that the document was created using the Vision Tool in the Studio and query *[_id == 'generaltranslation.secrets'].

Note: If you have multiple datasets, you'll have to do this across all of them.

If the document was found in your dataset(s), delete populateSecrets.js.

Configure your document structure to include the translations view:

sanity.config.ts

import { defineConfig } from 'sanity'
import { structureTool } from 'sanity/structure'
import { gtPlugin, TranslationsTab } from 'gt-sanity'

export default defineConfig({
  // ... your config
  plugins: [
    structureTool({
      structure: (S) =>
        S.list()
          .title('Content')
          .items(S.documentTypeListItems()),
      defaultDocumentNode: (S, { schemaType }) => {
        return S.document().views([
          S.view.form(),
          S.view
            .component(TranslationsTab)
            .title('General Translation')
        ])
      }
    }),
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'zh', 'ja'] // Replace with your target locales
    })
  ]
})

Usage

Once configured, you can translate documents directly from your Sanity Studio:

Open any document in your Studio
Click the General Translation tab
Select target languages
Click Generate Translations to send content for translation
By default, the plugin will automatically import the translations as back into your document, as soon as they are ready.
Additionally, imported documents will be automatically scanned for references to other documents, and will be automatically patched to point to the correct translations for those documents.

Next steps

Configuration Guide - Customize plugin behavior
Serialization Guide - Custom serialization rules
API Reference - Full configuration options

Prerequisites: Sanity Studio v3+, existing Sanity project

Installation

Install the gt-sanity package in your Sanity studio directory:

npm install gt-sanity

yarn add gt-sanity

bun add gt-sanity

pnpm add gt-sanity

Configuration

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'] // Replace with your target locales
    })
  ]
})

In your Studio folder, create a file called populateSecrets.js with the following content:

populateSecrets.js

import { getCliClient } from 'sanity/cli';

const client = getCliClient({ apiVersion: '2025-09-15' });

client.createOrReplace({
  // The `.` in this _id will ensure the document is private
  // even in a public dataset!
  _id: 'generaltranslation.secrets',
  _type: 'generaltranslationSettings',
  secret: process.env.GT_API_KEY,
  project: process.env.GT_PROJECT_ID,
});

Next, get a production API key at dash.generaltranslation.com.

Run the script with your credentials:

GT_API_KEY=your-api-key GT_PROJECT_ID=your-project-id npx sanity exec populateSecrets.js --with-user-token

Verify that the document was created using the Vision Tool in the Studio and query *[_id == 'generaltranslation.secrets'].

Note: If you have multiple datasets, you'll have to do this across all of them.

If the document was found in your dataset(s), delete populateSecrets.js.

Configure your document structure to include the translations view:

sanity.config.ts

import { defineConfig } from 'sanity'
import { structureTool } from 'sanity/structure'
import { gtPlugin, TranslationsTab } from 'gt-sanity'

export default defineConfig({
  // ... your config
  plugins: [
    structureTool({
      structure: (S) =>
        S.list()
          .title('Content')
          .items(S.documentTypeListItems()),
      defaultDocumentNode: (S, { schemaType }) => {
        return S.document().views([
          S.view.form(),
          S.view
            .component(TranslationsTab)
            .title('General Translation')
        ])
      }
    }),
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'zh', 'ja'] // Replace with your target locales
    })
  ]
})

Usage

Once configured, you can translate documents directly from your Sanity Studio:

Open any document in your Studio
Click the General Translation tab
Select target languages
Click Generate Translations to send content for translation
By default, the plugin will automatically import the translations as back into your document, as soon as they are ready.
Additionally, imported documents will be automatically scanned for references to other documents, and will be automatically patched to point to the correct translations for those documents.

Next steps

Configuration Guide - Customize plugin behavior
Serialization Guide - Custom serialization rules
API Reference - Full configuration options

Sanity Quickstart

Installation

Configuration

Usage

Next steps

On this page

Sanity Quickstart

Installation

Configuration

Usage

Next steps

On this page

Sanity Quickstart

Installation

Configuration

Usage

Next steps

On this page