Translate cheat sheet

Common patterns and examples for using Translate.

Translate offers an interface to translate Sanity documents using large language models (LLMs). This document showcases a collection of common patterns and concepts.

Prerequisites:

• Complete the Translate quick start.
• @sanity/client v7.1.0 or later and an environment to run client requests.
• API version vX is required for any requests to the Agent Actions API.

Many examples in this document use @sanity/client and expect that you've installed and configured it for your project. If your client is named something other than client, update the code examples accordingly.

Here's an example of the client implementation:

import { createClient } from "@sanity/client";
export const client = createClient({
  projectId: 'YOUR_PROJECT_ID',
  dataset: 'production',
  apiVersion: 'vX',
  token: process.env.SANITY_API_TOKEN
})

Then, import client into the file where you call Translate.

Translate can be told to leave certain words or phrases untranslated. Supply an array of strings to the protectedPhrases property, and the model is instructed not to translate any of them that appear in the input. Requires @sanity/client v7.1.0 or later, with the client configured for API version vX:

await client.agent.action.translate({
  // Replace with your schema ID
  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"},

  // Words and phrases to leave untranslated
  protectedPhrases: [
    "Sanity",
    "Media Library",
    "Agent Actions"
  ]
});

Set a field in the new document to record its language. This matters for routing and automation, where a check against a field determines the document's language. Target the field explicitly with languageFieldPath. Translate sets that field to the same value as the toLanguage ID.

For example, if your document has a language field where editors select the document language, set languageFieldPath to language. Requires @sanity/client v7.1.0 or later, with the client configured for API version vX:

await client.agent.action.translate({
  // Replace with your schema ID
  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" },

  // Tell Translate to set this field to the target language,
  // in this case, 'el-GR'.
  languageFieldPath: "language",

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

In addition to the patterns on this page, there are many common patterns that apply to all Agent Actions.