All posts
Web design & development

Headless CMS Localization: How Sanity, Storyblok and Contentful Handle i18n

Headless CMS localization compared: how Sanity, Storyblok and Contentful handle field-level vs document-level translation, fallbacks and editor workflow.

By Mehdi Hassan8 min read

The short answer

Headless CMS localization works in two models: field-level, where one entry holds every language, and document-level, where each language is its own linked entry. Contentful is built around field-level locales with fallbacks, Storyblok offers both field-level and folder-level translation out of the box, and Sanity lets you choose either model through official plugins.

Key takeaways

  • Pick the localization model first (field-level or document-level), then the CMS that fits it.
  • Field-level suits shared layouts translated line by line; document-level suits regional teams writing their own pages.
  • Fallbacks decide what visitors see when a translation is missing, so define them before editors start.
  • Sanity gives the most modeling freedom, Storyblok the most ready-made editor workflow, Contentful the most structure.
  • Check locale counts and plan limits on each vendor's pricing page; they change and vary by plan.

Part of Multilingual Website Guide: Strategy, Structure and SEO

Which headless CMS handles localization best?

No single headless CMS handles localization best for every team; the right one depends on whether you translate fields or whole pages, and who does the translating. Storyblok is the easiest start for marketers, Sanity is the most flexible for unusual content models, and Contentful is the most structured for larger organizations with many locales.

This comparison is narrower than our general best headless CMS for marketing teams guide. It looks only at how each CMS models translated content, falls back when a translation is missing, and shapes an editor's day. For the strategy above it, which languages to launch and how to structure URLs, start with our multilingual website guide.

Product details here reflect each vendor's documentation as of 2026. Plans and limits change, so confirm locale counts and pricing on each vendor's site before you choose.

What is the difference between field-level and document-level localization?

Field-level localization stores every language inside one entry, with a value per locale for each translatable field. Document-level localization creates a separate entry per language and links the versions together. The first keeps structure identical across languages; the second lets each language diverge.

Factor

Field-level

Document-level

Where translations live

One entry, a value per locale per field

One entry per locale, linked

Shared fields

Images, prices and references set once

Duplicated or referenced per entry

Layout per language

Same structure in every locale

Each locale can add or drop sections

Publishing

Often all locales together, depending on the CMS

Each locale on its own schedule

Best for

Translated sites with one central team

Regional teams writing their own pages

Main risk

Entries get crowded with many locales

Versions drift out of sync

Most marketing sites are a mix. Product pages and navigation translate line by line, while blog posts and regional landing pages are written per market. A CMS that supports both models, or lets you choose per content type, saves you from forcing everything into one shape. Our article on localization vs translation explains why the regional pages usually need rewriting rather than translating.

How does Sanity handle localization?

Sanity handles localization through your schema, so you choose field-level, document-level or both per content type. Sanity's localization documentation describes the two official plugins: one for document-level translation and one for field-level arrays.

  • Document-level: the document internationalization plugin adds a language field and links each translation to the others, so you can query a page in every language. Each version publishes independently.
  • Field-level: the internationalized array plugin turns a field into an array of language and value pairs, edited inline. Sanity's docs note that with field-level data, all languages publish together.
  • Fallbacks: there's no built-in fallback setting. You write it into the query, typically with GROQ's coalesce() to return the base language when a translation is missing.
  • Limits to know: Sanity's docs warn that storing each language as its own object key adds attributes per language and counts against attribute limits; the array approach avoids that.

The trade-off is that a developer designs the editing experience. That's a strength when your content model is unusual, and a cost when you wanted localization that works on day one. If you're weighing Sanity against Storyblok more broadly, our Sanity vs Storyblok comparison covers editing, pricing and visual editing. Our Sanity integration page shows how we wire it into a Next.js site.

How does Storyblok handle localization?

Storyblok handles localization with translation models built into the product: field-level translation inside one story, and folder-level translation with a separate folder tree per language. Teams with very different regional sites can also run separate spaces.

Field-level translation suits sites where every page exists in every language with the same layout. You mark fields as translatable, and editors switch language inside the visual editor and translate in place; untranslated fields show the default language's content. Folder-level translation suits markets that need different pages or section orders, since each language's folder holds its own stories. Storyblok supports translated slugs for field-level setups through its Translatable Slugs app; check its current docs for setup.

The draw for marketers is that translating happens in the same visual editor they already use, with the page previewed in each language. Our guide to live preview and visual editing explains why that matters for catching long strings before they ship.

How does Contentful handle localization?

Contentful handles localization at the field level: you define locales for a space, enable localization on each field that needs it, and every entry then holds a value per locale for those fields. Fields you leave unlocalized, such as a product SKU or a shared image, are set once for every language.

Each locale can have a fallback locale, so a missing translation in, say, Swiss German can fall back to German and then to English, and the delivery API returns the fallback's value. That chain is Contentful's strongest localization feature for organizations with regional variants. Document-level patterns are possible by modeling a page per locale and linking them, but you build that yourself. Our Contentful integration page covers how we connect it to a front end.

How do Sanity, Storyblok and Contentful compare for localization?

Storyblok gives editors the most finished translation workflow, Contentful gives the most structured field-level model with fallback chains, and Sanity gives developers the most freedom to model each content type differently. The table summarizes what changes day to day.

Factor

Sanity

Storyblok

Contentful

Field-level

Yes, via official plugin

Yes, built in

Yes, the core model

Document-level

Yes, via official plugin

Yes, folder-level

Possible, modeled by hand

Fallbacks

Written in queries

Default language for untranslated fields

Per-locale fallback chains

Editor workflow

Custom, shaped by developers

Translate inside the visual editor

Structured forms per locale

Setup effort

Highest

Lowest

Medium

Best fit

Unusual models, developer-led teams

Marketing-led sites

Larger orgs with regional variants

For example, suppose a SaaS site launches in English, German and Japanese

Hypothetical example: a SaaS marketing site has 15 product pages, a pricing page and a blog. Product pages are translated line by line, the blog is written separately per market, and the Japanese team wants its own case studies.

On Contentful, product pages and pricing fit the field-level model well, with German falling back to English while translations catch up. The Japanese case studies become their own entries tagged by market.

On Storyblok, product pages use field-level translation and the blog and case studies use folder-level, so each market writes in its own folder.

On Sanity, product pages use the internationalized array plugin, while blog posts and case studies use document internationalization so each publishes on its own schedule.

All three can do it. The difference is how much is ready to use versus built by a developer.

How does headless CMS localization connect to your front end?

The CMS stores translations; the front end decides URLs, hreflang and what happens when a locale is missing. In a headless setup, none of the three CMSs generates hreflang for you, so your site code builds it from the same locale list the CMS uses.

  1. Define the locale list once

    Keep one source of truth for locales and map CMS locale codes to URL prefixes such as /de/ and /ja/.

  2. Fetch content per locale

    Query each page by locale and apply your fallback rule, either the CMS's chain or your own query logic.

  3. Translate slugs

    Store a slug per locale in the CMS so URLs read naturally in each language.

  4. Generate hreflang and sitemaps

    Build alternates from the locales a page actually exists in, so missing translations don't produce broken links. Our hreflang guide covers the rules.

Our Next.js i18n guide walks through the routing side, and our headless CMS development service is where we do both halves together. If you're new to the architecture, what a headless CMS is is a quick primer.

Frequently asked questions

Can you switch from field-level to document-level localization later?
Yes, but it's a content migration, not a setting. Every entry has to be split into one entry per language, or merged the other way, and references and slugs remapped. Script it and test on a copy of the dataset. It's far cheaper to choose the model per content type before editors start translating.
Do headless CMSs include machine translation?
Most offer machine translation through apps, plugins or integrations with translation services rather than as a core feature, and what's available changes often. Treat it as a first draft. Headlines, calls to action and pricing copy still need a fluent reviewer, so plan who reviews each locale before you decide how much to automate.
How should translation management systems fit in?
A translation management system sits beside the CMS: content is sent out for translation, translators work in the system, and finished strings come back into the right locale fields. All three CMSs connect to common translation services through apps or APIs. It makes sense once you have professional translators or several languages; a small team can translate in the CMS directly.
What happens to SEO if a translation is missing?
That depends on your fallback rule. If the page falls back to English at a German URL, you serve English content under a German address, which confuses visitors and search engines. Usually it's better not to publish the German URL until it's translated, and to leave it out of the hreflang set until then.
Is a headless CMS overkill for a two-language site?
Often, yes. If the site is small and the team wants to edit visually, a builder with native localization may be simpler and cheaper to run. A headless CMS earns its cost when content is structured, shared across several channels, or expected to grow into many locales with separate regional teams.

· CEO & Design Director

Copywriter, designer and developer, and founder of Designify Studio. Over five years, 60+ projects across 14+ industries, for startups that have raised $300M+.

Want this done for you? Website, $8,000.

A multi-page marketing site, written and designed by us, developed in Next.js and animated. $8,000, one-time, up to 6 pages. Book a free 30-minute call to see if it fits.

Schedule Call