Translate quick start

Learn to translate documents with the Translate Agent Actions action.

Translate is a Sanity Agent Actions action that lets you programmatically run schema-aware AI translations on Sanity documents. You can run translations from anywhere you can execute code, such as Sanity Functions, custom components, webhook listeners, CI/CD pipelines, migration scripts, and more.

In this guide, you'll first use Translate to convert a document into a new language. You'll use @sanity/client to create the translation requests (you can also make requests using the HTTP API directly).

• @sanity/client v7.1.0 or later and an environment to run client requests.
• API version vX is required for all requests to the Agent Actions API.
• Optional: In Node.js v23.6 or later, you can run this guide's TypeScript examples without additional servers or build processes. Alternatively, you can use earlier versions with an experimental flag. Converting the examples to JavaScript is okay too.
• sanity CLI v3.88.0 or later.
• A Sanity project for testing. This guide's examples use details from the sample "Movies" studio schema that you can select when initializing a new project.
  • A read/write API token to authenticate requests.
  • A valid projectId and dataset name.

Translate requires an uploaded schema. If you've deployed recently, you can check for a list of uploaded schemas by running the schemas list command. If you don't see a schema or want to deploy the latest version, redeploy your studio to Sanity or deploy the schema:

npx sanity@latest schemas list

npx sanity@latest deploy

npx sanity@latest schemas deploy

Copy the schema ID, which you'll need for making Agent Actions requests.

For more information, see Deploy a schema.

Import and configure @sanity/client with the projectId, dataset, API token, and an apiVersion of vX:

import { createClient } from "@sanity/client";

export const client = createClient({
  projectId: 'YOUR_PROJECT_ID',
  dataset: 'production',
  apiVersion: 'vX',
  token: process.env.SANITY_API_TOKEN
})

If you're already using the client elsewhere in an application, you can reuse its base configuration. To adjust the token or the API version, use the withConfig method to create a new client based on your existing one. For example:

// ...
const translateClient = client.withConfig({
  token: process.env.SANITY_API_TOKEN,
})

It's common to want a complete, translated version of a document. To achieve this with Translate:

• Provide a source documentId of the original document.
• Define the fromLanguage. This is optional, but it avoids the AI interpreting the document as a language other than the one you expect.
• Define the toLanguage that you want the document translated into.
• Set the operation. Operations tell Agent Actions what to do. This example uses create. Learn more about operations.

Here's a minimal example that uses an existing English language document to create a new translation in Greek:

await client.agent.action.translate({
  schemaId: "YOUR_SCHEMA_ID",

  // Tell the client the ID of the document to use as the source.
  documentId: "YOUR_DOCUMENT_ID",

  // Set the operation mode
  targetDocument: { operation: "create" },

  // Set the 'from' and 'to' language
  fromLanguage: {id: "en-US", title: "English"},
  toLanguage: {id: "el-GR", title: "Greek"},
});

This creates a new draft document based on the source (documentId).

If you're familiar with the other Agent Actions, styleGuide is Translate's version of instruction. It lets you add additional context and guidance beyond setting a target language.

This example tells Translate to use a formal tone:

await client.agent.action.translate({
  schemaId: "YOUR_SCHEMA_ID",

  // Tell the client the ID of the document to use as the source.
  documentId: "YOUR_DOCUMENT_ID",

  // Set the operation mode
  targetDocument: { operation: "create" },

  // Set the 'from' and 'to' language
  fromLanguage: {id: "en-US", title: "English"},
  toLanguage: {id: "el-GR", title: "Greek"},

  styleGuide: "Use a formal tone when translating.",
});

You can also pass information into the style guide with styleGuideParams:

await client.agent.action.translate({
  schemaId: "YOUR_SCHEMA_ID",

  // Tell the client the ID of the document to use as the source.
  documentId: "YOUR_DOCUMENT_ID",

  // Set the operation mode
  targetDocument: { operation: "create" },

  // Set the 'from' and 'to' language
  fromLanguage: {id: "en-US", title: "English"},
  toLanguage: {id: "el-GR", title: "Greek"},

  // Use `styleGuide` instead of instruction for Translate
  styleGuide: "Use a $tone tone when translating.",
  styleGuideParams: {
    tone: 'formal'
  }
});

This example uses a constant type parameter to assign the string "formal" to the tone key, then passes it into the style guide as $tone. This is one type of parameter. You can do everything from including full documents to making GROQ queries. Learn more about passing parameters into style guides.

To learn more about what you can do with Translate, explore the other guides and resources available for Agent Actions.