Skip to content

How do I set up localized content in Sanity (field-level vs document-level)?

0repliesLast updated: Nov 13, 2026

I need my Sanity content in several languages. What are the ways to model localized content, how do I set up the schema and plugins for each, and how do I query one locale with a fallback language in GROQ? I'd also like to know which approach to pick and how AI translation fits in.
AI Update

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-levelDocument-level
StorageOne document, one array item per languageOne document per language
PublishingAll languages publish togetherEach language publishes on its own
Best forDocuments that mix shared fields (price, image) with translated onesDocuments 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'}]}),
      ],
    }),
  ],
})

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

assist({translate: {
  styleguide: 'Formal and precise.',
  document: {languageField: 'language', documentTypes: ['article']},
}})

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.

Related contributions