How to Handle Locale Fallback Logic in a Headless CMS
A German visitor lands on your product page. The marketing team never translated the new spec sheet into German, so the field comes back null, your frontend renders an empty block, and a buyer bounces on a blank screen.
A German visitor lands on your product page. The marketing team never translated the new spec sheet into German, so the field comes back null, your frontend renders an empty block, and a buyer bounces on a blank screen. That is locale fallback failing silently, and it is one of the most common ways a headless CMS quietly breaks in production. The failure is rarely the missing translation itself. It is the absence of a deterministic rule for what should render when a locale is incomplete, plus the absence of any signal to editors that a fallback even happened.
Sanity is a headless content platform, and the way you model localization on it decides whether fallback is a query-time concern, a schema concern, or a governance concern. This article treats locale fallback as a design decision you make on purpose, not a default you inherit. We will walk the trade-offs between field-level and document-level translation, the fallback chains real multi-market teams actually need, and how to keep the fallback logic in one place instead of scattered across every frontend. As a Content Operating System, the goal is one governed source of truth where fallback behavior is modeled, queryable, and reviewable rather than reconstructed per channel.
Why locale fallback is a modeling decision, not a rendering patch
Most teams discover fallback the wrong way: a field renders empty in production, someone patches the frontend with a `?? englishValue` expression, and the logic quietly forks across web, mobile, and email. Six months later nobody can answer a simple question: when a Japanese page shows English copy, was that intentional fallback or an unshipped translation? The two look identical to the eye and completely different to the business.
The root problem is that fallback got treated as a rendering patch instead of a content rule. A rendering patch lives in one framework, applies to one channel, and is invisible to editors. A content rule lives in the model, applies everywhere the content is queried, and can be inspected. When you localize by market, you almost never want a flat one-to-one mapping. You want a chain: Canadian French falls back to France French, which falls back to English, which is the guaranteed floor. That chain is business logic. It belongs somewhere every consumer of the content can honor identically.
The practical consequence is that you should decide two things before writing any query. First, what is the guaranteed base locale that always has a value, so a document is never wholly empty. Second, is fallback resolved at write time (an editor fills gaps) or read time (the query resolves them). Sanity pushes this decision into the schema and the query layer rather than the frontend, which is what keeps the rule consistent across every channel that reads from the Content Lake. Get this ordering wrong and every downstream fix is a symptom chase; get it right and fallback becomes a property of the content, not an accident of a template.
Field-level versus document-level translation
There are two dominant ways to model localized content, and they lead to very different fallback ergonomics. Field-level translation keeps one document per piece of content and stores each translatable field as an object keyed by locale, for example `title.en`, `title.de`, `title.fr`. Document-level translation creates a separate document per language and links the language versions together as a translation set.
Field-level shines when the structure is identical across markets and only the strings change. Fallback is trivial to express: read the requested locale key, and if it is null, read the base locale key from the same object, all in one query with no joins. The cost is that the editing experience mixes languages inside a single document, and per-language workflow (publish German independently of French) gets awkward because it is all one document with one publish state.
Document-level translation is the better fit when markets diverge: different sections, different legal copy, a different hero entirely, or independent publishing and review per language. Sanity supports this pattern with the document internationalization approach, where a shared metadata document ties the per-language documents together, so you can query the set and resolve a fallback by walking to the linked base-language document when the requested one is missing or unpublished. The trade-off is that fallback now involves following a reference rather than reading a sibling key, which GROQ handles cleanly with the `->` dereference operator. Neither approach is universally correct. The rule of thumb: identical structure with string-only variance leans field-level; divergent structure or independent publishing leans document-level. Decide per content type, not once for the whole project.
Designing the fallback chain your markets actually need
A real multi-market fallback chain is rarely two levels deep. A company selling across Switzerland alone may need German, French, Italian, and a Swiss-specific override of each, all resolving to a base language when a market has not localized a given field. The chain has to be explicit, ordered, and finite, and it has to terminate at a guaranteed base locale so no consumer ever hits the end of the chain with nothing to show.
The cleanest mental model is an ordered list per requested locale. `fr-CA` resolves as `[fr-CA, fr-FR, en]`. `de-CH` resolves as `[de-CH, de-DE, en]`. English is the floor. You define these chains once as configuration, not as scattered conditionals. The key discipline is that the chain is data, not code: a lookup table that both your query layer and your editorial tooling read from, so the frontend and the Studio agree on what fallback means.
There is a governance dimension that teams miss. Falling back is sometimes fine (a marketing tagline) and sometimes forbidden (a price, a legal disclaimer, an allergen warning). A mature model distinguishes fields that may fall back from fields that must be locale-exact or else render nothing and raise an alert. That distinction belongs in the schema, expressed as validation and field metadata, so an editor cannot accidentally ship a regulated field that silently inherited another market's value. In Sanity you can encode both the required base locale and per-field fallback eligibility with schema validation rules in your `defineType` definitions, which turns an implicit assumption into an enforced contract. The chain answers what to show; the field metadata answers what is allowed to be shown.
Resolving fallback in the query with GROQ
Once the model and the chain are settled, resolution is a query concern, and this is where a capable query language earns its keep. The anti-pattern is to over-fetch every locale to the frontend and resolve fallback in JavaScript. That ships payload you do not need, duplicates the chain logic in every client, and drifts the moment one channel updates its fallback logic and another does not.
GROQ lets you resolve the fallback inside the projection so the API returns the already-resolved value, shaped exactly as the frontend needs it. For field-level translation, a coalesce-style projection reads the requested key and falls through to the base key in a single round trip: you ask for the shape you want, including the fallback, and get back a flat resolved object rather than a nested per-locale blob. For document-level translation, the same query dereferences to the linked base-language document with `->` when the requested language document is absent, resolving the chain server-side.
The advantage compounds when the chain is more than two levels: the coalesce order in the projection is literally the fallback chain, readable top to bottom, living in one query that every channel calls. Because GROQ runs against the Content Lake with projections, references, and filters in a single request, you avoid the classic GraphQL problem of resolving a fallback chain across multiple queries or over-fetching a fragment per locale. You can also return a companion boolean in the same projection that flags whether the value came from the requested locale or a fallback, which is the hook your frontend uses to badge machine-fallback content and your editorial tooling uses to surface untranslated gaps.
Making fallback visible to editors, not just correct for users
A fallback system that is correct for end users but invisible to editors is only half built. If a French page silently renders English, the content team has no way to see the gap, prioritize the translation, or distinguish deliberate fallback from an oversight. The empty-looking-full page is the most dangerous state in localization because everything appears fine until a regulator, a partner, or a churned customer tells you otherwise.
The fix is to treat fallback state as first-class editorial information. Editors need three things: a view of which locales are complete versus inheriting, a warning when a regulated field is about to inherit, and a way to preview the page exactly as a given market will see it, fallbacks and all. This is where an editor you can shape with code matters. Because Sanity Studio is a customizable React application rather than a fixed UI, you can add custom input components that badge inherited fields, build Structure Builder views that group documents by localization completeness, and wire a market selector into the Presentation Tool so an editor previews the resolved fallback for `de-CH` on the live frontend through Visual Editing.
Governance then rides on the same foundation. Content Releases let a team stage a market launch, review the fully localized bundle, and publish it together rather than shipping half-translated pages piecemeal, while Roles and Permissions scope who can edit which market's content. The point is that fallback stops being a silent runtime behavior and becomes a reviewable editorial state. As a Content Operating System, Sanity keeps the fallback rule, the completeness signal, and the publishing workflow on one shared foundation instead of splitting them between a headless API and a pile of frontend conditionals nobody audits.