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"},
});

Each successful Translate request costs one AI credit, the same as any other Agent Actions request. A request translates one source document (documentId) into one language (toLanguage), so cost depends on how many documents and languages you translate, not on how long the documents are or how many words they contain. For credit pricing and spending limits, see How AI Credits work.

To estimate a job, multiply the number of documents by the number of target languages. For example, translating 200 documents into 5 languages takes 1,000 requests and costs 1,000 credits. Requests that return an error don't consume credits.

Translate generates new translations. If you already have translated content, such as reviewed translations from another tool or a translation vendor, write it to your dataset directly instead of running it through Translate again. Creating and patching documents with the client or a migration script are regular API writes and don't consume AI credits.

Match the structure Translate would create. For example, if you set languageFieldPath to language for new translations, set the same field on imported documents:

await client.createOrReplace({
  _id: "YOUR_TRANSLATED_DOCUMENT_ID",
  _type: "movie",
  // Set the same language field that Translate sets with languageFieldPath
  language: "el-GR",
  title: "Ο Νονός",
});

For larger imports, see Import data and the Content migration cheat sheet.

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