Translate quick start

Learn to translate documents with Agent Actions Translate.

Translate is a Sanity Agent 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).

Prerequisites:

• @sanity/client v7.1.0 or higher and an environment to run client requests.
• API Version vX is required for any requests to the Agent Actions APIs.
• Optional: In Node.js v23.6 and above, you can run the TypeScript examples below 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. The examples below 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.

Agent Actions requires an uploaded, up to date schema. If you've deployed recently, you can check for a list of uploaded schemas by running the following command from your project directory:

sanity schema list

Copy the schema ID, which you'll need for the third step. If you don't see a schema or want to deploy the latest version, redeploy your studio to Sanity or deploy the schema.

To deploy your studio and schema together, run the following from your project directory:

sanity deploy

To deploy just the schema without your studio, run the following:

sanity schema deploy

Then, run the sanity schema list command again and copy the schema ID associated with your workspace, dataset, and project.

You can learn more about schema deployment here.

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

// instruction.ts

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

export const client = createClient({
    projectId: '<project-id>',
    dataset: '<datset-name>', // such as 'production'
    apiVersion: 'vX',
    token: '<editor-token>'
})

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

// ...
const generateClient = client.withConfig({
  token: '<your-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. In this example, we'll use 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({
  // Replace with your schema ID
  schemaId: "sanity.workspace.schema.default",

  // Tell the client the ID of the document to use as the source.
  documentId: "<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.

In this example, we tell Translate to use a formal tone:

await client.agent.action.translate({
  // Replace with your schema ID
  schemaId: "sanity.workspace.schema.default",

  // Tell the client the ID of the document to use as the source.
  documentId: "<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({
  // Replace with your schema ID
  schemaId: "sanity.workspace.schema.default",

  // Tell the client the ID of the document to use as the source.
  documentId: "<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'
  }
});

In this example, we use a constant type parameter to assign the string "formal" to the tone key. Then, we pass it into the style guide as $tone. This is just 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.