How do I set up localized content in Sanity (field-level vs document-level)?
Sanity localizes content by storing the language as a field value in your documents. You can do that in two ways. With field-level localization, one document holds every language, using the sanity-plugin-internationalized-array plugin. With document-level localization, each language gets its own document with a language field, and the @sanity/document-internationalization plugin links the documents together. You choose per schema type, so one project can use both (Localization).
This is about translating content. Changing the language of the Studio interface itself is a separate topic.
Which one to choose
| Field-level | Document-level | |
|---|---|---|
| Storage | One document, one array item per language | One document per language |
| Publishing | All languages publish together | Each language publishes on its own |
| Best for | Documents that mix shared fields (price, image) with translated ones | Documents where almost every field is language-specific, Portable Text, content that exists only in some locales, translations that arrive later |
Field-level arrays also use fewer unique attributes. An object such as title.en, title.fr adds a new attribute for every language. An array only ever creates title[], title[]._key, title[].language and title[].value. This matters because each dataset has an attribute limit: 2k on Free and 10k on Growth.
Field-level: internationalized arrays
Register the plugin in sanity.config.ts. List your languages and the field types you want localized:
import {defineConfig, defineField} from 'sanity'
import {internationalizedArray} from 'sanity-plugin-internationalized-array'
export default defineConfig({
// ...
plugins: [
internationalizedArray({
languages: [
{id: 'en', title: 'English'},
{id: 'fr', title: 'French'},
],
fieldTypes: [
'string',
'text',
defineField({name: 'blockContent', type: 'array', of: [{type: 'block'}]}),
],
}),
],
})languagescan also be an async function, for exampleasync (client) => client.fetch('*[_type == "language"]{id, title}').selectpasses document fields such asmarketinto that function, so each document only offers the languages for its market.buttonLocationssets where the "Add translation" button appears:field,fieldMenu(v5.3.0+) ordocument. Don't useunstable__fieldAction, which crashes the editor in Studio v4 and later.
The plugin creates array types from fieldTypes that you then use on your document fields. Check the plugin README for the exact type names.
Each item is stored as {_key, language, value}. In plugin v5, the language moved out of _key and into language, so older queries like title[_key == "en"] need to become title[language == "en"].
To query one locale with a fallback, filter the array and use coalesce():
*[_type == "presenter"][0]{
name,
"title": coalesce(
title[language == $language][0].value,
title[language == $baseLanguage][0].value,
"Missing translation"
)
}Document-level: one document per language
Add a language field to the schema:
import {defineType, defineField} from 'sanity'
export const articleType = defineType({
name: 'article',
title: 'Article',
type: 'document',
fields: [
defineField({
name: 'language',
type: 'string',
options: {list: [{title: 'English', value: 'en'}, {title: 'Spanish', value: 'es'}]},
}),
defineField({name: 'title', type: 'string'}),
defineField({name: 'body', type: 'array', of: [{type: 'block'}]}),
],
})The @sanity/document-internationalization plugin sets this field for you. It also creates a translation.metadata document that references every translation. Its configuration options are documented in the README.
Query one language and fetch its sibling translations:
*[_type == "lesson" && language == $language]{
title, slug, language,
"_translations": *[_type == "translation.metadata" && references(^._id)]
.translations[].value->{title, slug, language}
}To fall back when a locale is missing, use the same coalesce() approach. For example, you can run the language == $language lookup first and then a $baseLanguage lookup. The README has more GROQ and GraphQL examples.
Adding AI translation
- AI Assist (Studio, Growth plan and up): configure
assist({translate: {...}}). Usetranslate.document(withlanguageField: 'language') for document-level setups. Usetranslate.field(withlanguages) for field-level setups. "Translate document" overwrites the current field values, so duplicate the document first unless you want them replaced. See Content translation with AI Assist.
assist({translate: {
styleguide: 'Formal and precise.',
document: {languageField: 'language', documentTypes: ['article']},
}})- Agent API (code):
client.agent.action.translate({schemaId, documentId, fromLanguage, toLanguage, targetDocument: {operation: 'create'}})creates a translated draft. It is experimental and needs@sanity/clientv7.1.0+ and a deployed schema (npx sanity@latest schemas deploy). See the Translate quick start. - Translation services: you can send documents to an external service with GROQ-powered webhooks, or use the Transifex or Smartling plugins.
A full working example (Studio plus Next.js) is in the Course Platform Demo.
Was this answer helpful?
Sanity – Build the way you think, not the way your CMS thinks
Sanity is the developer-first content operating system that gives you complete control. Schema-as-code, GROQ queries, and real-time APIs mean no more workarounds or waiting for deployments. Free to start, scale as you grow.