Sanity Studio localization is a content-model decision before it becomes a translation task. This Sanity multilingual translation guide explains document-level internationalization, field-level localized arrays, GROQ retrieval, Portable Text, linked language variants, source changes, and international SEO. It is written for editors and developers building a world-facing publication, course site or content application where language variants must remain identifiable, reviewable and correct.
To translate Sanity content professionally, decide whether one document should hold several localized fields or whether each language needs an independently publishable document. Sanity’s documentation describes both approaches and recommends document internationalization for linked translated documents, while internationalized arrays are useful for localized fields. The correct query depends on the chosen schema: filtering one language’s field array is different from fetching a separate language document and its translation metadata.
Quick guide: choose field-level or document-level localization by content type; define explicit language identifiers; separate shared facts from translated prose; link corresponding documents where appropriate; preserve Portable Text references and annotations; query only the intended language through GROQ; review draft and published versions separately; test routes, slugs and alternate links; approve critical meaning before publishing; maintain regression cases as languages and schemas change.
Quick answer: translation must survive the whole publishing path
The useful question is not simply whether Sanity can store another language. It is whether a reader who opens the target route receives the intended version of every important instruction, follows correct links, and understands what action is available. Begin with a small set of entries, one target locale and a written expected result. Recreate the journey after each change rather than guessing from an editing screen.
Translation should protect facts as well as fluency. Keep record identifiers, dates, prices, measured values, legal conditions and source references attached to their actual owners. Give translated prose enough space to be natural, but do not invent permissions, guarantees or benefits. Where the underlying facts differ by market, document that as an approved localized content decision, not an accidental consequence of translation.
Definition lock: the essential concepts and their boundaries
Sanity’s Content Lake stores structured documents according to schemas that a project defines. Sanity Studio provides editing tools; its interface language is not the same thing as the language of the published content. Field-level localization stores variants together, whereas document-level localization typically permits independent publication and translations related by references or metadata. This guide treats those approaches as distinct architectures rather than interchangeable interface preferences.
For this guide, a locale is a configured language or language-region selection; a translation is approved content intended to preserve the source’s relevant meaning for that audience; a fallback is a defined substitute when a requested value is unavailable; and a published result is what a permitted external reader can actually obtain. These words describe different decisions. A fallback may be technically permitted but editorially unsuitable. A published record may exist without a valid route. A fluent translation may still contain an incorrect factual condition.
One realistic example to carry through the guide
Imagine a global online course catalogue. One course has a stable course ID, price and instructor reference, but its title, description, lesson summaries, FAQs, and public slug must be localized. Some small labels can share a field-level localized array; long lessons written in Portable Text may need separately published documents. The implementation must ensure that a learner changing language remains on the same course and never sees the wrong language of safety instructions.
A practical vocabulary before you start
- Document-level localization
- Internationalized array
- Language field
- Translation metadata
- GROQ
- Portable Text
- Draft document
- Localized slug
Do not memorize these terms as isolated labels. For every one, identify its corresponding item in your own project. Ask who owns it, where it is configured, what could go wrong, and how to confirm the result from outside the editor. A glossary becomes genuinely useful when it connects words to observable behavior.
Twenty detailed lessons for Sanity multilingual publishing
1. Choose the Sanity localization model
Sanity supports field-level localized values and document-level separate translations; the project selects according to editing and publication needs.
A translation project becomes easier when it defines the complete reader task rather than a vague quantity of words. List the actions a visitor must complete, the decisions that depend on the text, and the consequences of a misunderstanding. This makes priorities visible: an inaccurate eligibility rule is more urgent than an awkward decorative headline. A usable scope names the content owner, language reviewer, developer, release environment, and the place where a reader will see the result.
What can go wrong: A team stores a whole long-form lesson in a shared field despite needing separate release dates by locale. Look at the real reader’s first decision before tuning the text. A sentence can be grammatical yet leave someone uncertain about what happens next. Read the source and target in context, ask what choice each permits, and note any new promise that appears only in translation. When an essential qualification is absent, pause publication and resolve it with the person who owns the underlying rule.
What to do: Use document-level records for independently published long text and field-level values for suitable shared records. Start with a deliberately small specimen that contains ordinary prose, a link, a conditional instruction, and a visible call to action. Walk through its origin, stored representation, API or template, and final rendering. Write down which layer is responsible at each stage. If the same words appear on another page, identify whether they are shared content or a copied entry. You want a reproducible map before scaling the number of target-language items.
Acceptance evidence: Each content type has a documented rationale for its translation model. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
2. Define consistent language identifiers
Document language fields or localized array items need a stable locale convention across schemas, queries and routes.
Locale codes are routing and data-selection keys, not decorative flags. The project may distinguish a language from a market, and may also maintain region-specific variants. The distinction matters when two audiences use similar vocabulary but different conventions for dates, formal address, units, or legal statements. Build a locale inventory with the exact codes supported by the configured system and by the application consuming it. Do not assume that a label in an editing interface establishes the language of the public page.
What can go wrong: One query expects fr while another document stores fr-FR, making a translation appear absent. Keep locale selection visible during investigation. If a test passes only while logged in as an editor, repeat it in a public or appropriately restricted client. Compare the requested language, returned language, and displayed language; they should not be inferred from one another. Record the full path from request to rendered phrase rather than a screenshot without context.
What to do: Choose supported identifiers and validate them in Studio schemas and client requests. Document a source locale, the intended target, regional variants, default behavior, and the list of markets where each variant may appear. Have someone test the exact code through the delivery route rather than accepting a country dropdown as proof. Try a language the site does not support and record the expected safe result. A project that cannot describe its own locale matrix will struggle to diagnose apparently random translation errors.
Acceptance evidence: The same locale choice resolves correctly in authoring and delivery. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
3. Separate shared course data from localized text
Fields such as course IDs and entitlement rules should not be duplicated casually with every translated title.
Structured content has two kinds of information: facts that should remain the same everywhere, and presentation or explanation that must change for a particular audience. A product identifier, event timestamp, membership entitlement, or database relationship often belongs to the first category. A title, introduction, instruction, text alternative, or locally approved claim may belong to the second. Translating a shared identifier can create two apparent objects where only one should exist.
What can go wrong: A French document receives a different enrollment identifier and appears to be a separate course. Ask whether a proposed translation changes a value, a label, or an identity. Human-readable labels can change; keys and relationships often cannot. When the wrong field has been edited, restore the original data first and then place the localized wording where the model expects it. Documentation should identify this boundary for every editor who touches the record.
What to do: Reference a shared course identity while translating descriptions and reader-facing instructions. For each field, assign one of three treatments: shared and immutable, localized with a named owner, or conditionally localized under market rules. Record why the treatment was chosen. If a value is shared but looks like prose, consider whether it is actually an internal key. If a value is localized but carries a business fact, require the fact owner to review the target version. This prevents both accidental divergence and unhelpfully literal copy.
Acceptance evidence: Changing language preserves course identity and the actual entitlement. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
4. Connect language versions reliably
Sanity’s document internationalization approach can link translated documents through translation metadata references.
The notion of one article or item can become complicated when multiple language versions exist. Editors need to know which translated records belong together, which identifier survives a language switch, and how a new revision is tied to its source. A missing or duplicated relationship can send a reader to an unrelated page even if every sentence has been translated beautifully. Translation identity is a content-model property as much as a linguistic property.
What can go wrong: An editor copies an English article but fails to place it in the correct translation group. Test the relationship in both directions. Switching from the source to the target should reach the intended item; switching back should not create a duplicate or lose the reader’s place. Broken reverse navigation usually points to an identity or relation problem. Fix the mapping centrally and verify several specimens before relying on special-case redirects.
What to do: Create and inspect the translation relationship using the project’s installed plugin and schema. Draw a small relationship graph with one source item and two target versions. Include their identifiers, states, slugs, and the shared business object. Simulate a source update and ask how the target versions are flagged for review. Then simulate the deletion or unpublication of a translation. The expected action should be explicit, not inferred from the visible title. This diagram often reveals problems before the first API request is written.
Acceptance evidence: The language switch returns a corresponding document, not an approximate title match. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
5. Understand internationalized arrays
The internationalized-array plugin stores language values in array items rather than generating a new top-level field per language.
Field-level decisions influence both editorial usability and technical complexity. A single field may contain a short label, a long explanation, or an entire rich-text document. Those formats require different checks for length, links, headings, embedded references, and translation context. More locale fields do not automatically mean better localization; excessive duplication raises maintenance cost. Equally, forcing all languages into one field can make independent review and publication impossible.
What can go wrong: A developer reads the first array element as though array order identifies the locale. Remember that the reader is not looking at a data model. They see a button, paragraph, photograph or route, often on a narrow screen. Translation quality therefore includes clarity, sensible line breaks, accessible labels, and the preservation of necessary qualifiers. A shorter target is not automatically better; a longer target is not automatically worse.
What to do: Select values by their language marker and check the installed plugin version. Make a field inventory using real examples instead of an abstract schema. For a call-to-action button, check space and verb choice. For a warning, check scope and exceptions. For long-form text, check links, quotations, and heading structure. Separate the decisions about storage from decisions about editorial approval. A technically convenient representation is useful only when the team can reliably maintain and retrieve the right meaning.
Acceptance evidence: Reordering array elements does not change which language is displayed. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
6. Respect schema and plugin version differences
Recent internationalized-array versions represent language in a dedicated field, while older versions used item keys.
Relations create much of the usefulness of a structured website. Articles refer to authors and categories; products refer to variants; guides link to other guides. Some relations should stay shared, while others should select a language version. A localized title with a reference to the wrong-language destination can produce a seamless-looking but misleading reading experience. Translators should therefore understand links as claims about identity and context, not as punctuation around prose.
What can go wrong: A migration copies old filtering logic and reads the wrong array fields after an upgrade. Check the destination as carefully as the visible link. A related item might be unavailable in a target language, outdated, private, or contextually different. Decide whether readers should receive an explicit explanation, a permitted fallback, or no link. The chosen behavior should be stable across navigation menus, inline links, recommendations and search results.
What to do: Review the version-specific data shape and migrate or support legacy data deliberately. Choose a sample item with a parent, a related item, and a call-to-action destination. Record the expected destination for each supported locale. Test what happens when the related translation does not yet exist. A sensible system might retain a documented safe fallback or suppress the link, depending on the audience and risk. It should not silently send someone to a different subject. Link checks belong in the translation review, not only in engineering.
Acceptance evidence: Queries return the correct language for both current and verified legacy test records. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
7. Design fallback as an explicit GROQ choice
Sanity schemas and queries determine how missing localized values are handled; there is no universal fallback policy for every custom model.
Fallback means a system supplies a value from another language or source when the requested one is missing. It is useful for continuity, but can conceal incomplete translation coverage. Fallback behavior may depend on whether the field is absent, empty, unpublished, or explicitly cleared. These states are not interchangeable. A page that looks complete at a glance can still contain a mixture of languages, particularly in rich text, metadata, error messages, or navigation.
What can go wrong: A generic coalesce expression shows English legal copy inside an otherwise French release. Create a tiny matrix of present, missing, empty and withdrawn values. The same-looking blank space can represent a deliberate choice, an unavailable translation, a failed query, or an unpublished version. Test each state through the actual delivery path. Then give editors a way to see which policy was applied so that a fallback cannot disguise a critical omission.
What to do: Permit fallback only for approved field categories and communicate unavailable content clearly. Prepare four fixtures: translated text, missing field, intentionally blank field, and a withdrawn translation. Test all four in preview and in the publicly served content. Record the actual source of every rendered value. If fallback is allowed, define where it is acceptable and how editors discover it. If fallback is forbidden for legal notices or safety instructions, configure or enforce a publication gate. Treat fallback as a policy that must be explained, not a rescue mechanism that needs no oversight.
Acceptance evidence: Sensitive fields do not silently fall back to unreviewed language. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
8. Translate Portable Text without losing structure
Portable Text stores blocks, marks and references that may carry meaningful navigation or annotations.
Rich text is not just a bag of words. Headings, annotations, hyperlinks, code fragments, embedded assets, and references carry meaning and sometimes behavior. A language model or translator may preserve the visible sentence but lose a linked condition or change the order of a list. When text is stored as structured blocks, the translation process should protect that structure while giving the language natural room to expand or contract.
What can go wrong: A translated lesson drops the link annotation attached to an important citation. Inspect structure as well as text. Where an element contains a link, list marker, citation or embedded reference, confirm both the translated explanation and the retained machine-readable relationship. A field can validate successfully while readers are sent to the wrong instruction. Include a keyboard and mobile check when the format is interactive.
What to do: Keep block structure and references while revising language naturally; test the renderer. Use a test article containing a heading, an external link, an internal link, a quote, bold emphasis, and a numbered process. Compare the source and target at the structured-content level before opening the webpage. Then check the rendered page with a keyboard and screen reader where available. Verify that the link destination still matches the translated description. An intact JSON or block tree is necessary, but it is not enough: a structurally valid sentence can still communicate the wrong instruction.
Acceptance evidence: Quotations, lists, inline marks and link destinations survive target-language publication. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
9. Treat images and asset descriptions separately
A Sanity asset reference can be shared while localized captions and alternative descriptions live in your schema.
Images, files, video captions, and text alternatives are part of a localized page. An image may be language-neutral, may contain embedded words, or may communicate a culturally specific example. A translated article with an untranslated diagram or missing caption is not fully understandable. Metadata such as alt text and download names may be stored separately from the main article, so an editor can easily miss them.
What can go wrong: A reused photograph receives an English alt description on a Spanish lesson page. Use one asset that contains visible wording and one that is language-neutral. Their proper treatment may differ. A language-neutral photograph can often be shared, but the alt text still needs review; a diagram containing words may require a separate localized version. Check the published file itself, not only the editor’s preview title.
What to do: Model and review accessible description fields by language where needed. Classify each asset as reusable, language-specific, or in need of replacement. Check whether the system supports a localized asset field or requires a separate object. Confirm that a target page never shows the source-language accessibility description for a substantially different target-language image. In a demonstration, verify the actual file displayed, the caption, the alt description, the download label, and the link destination rather than checking only the asset record.
Acceptance evidence: The actual image, translated caption and text alternative agree. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
10. Build Studio views for translators
A content model may be technically sound but hard to use if editors cannot find the correct language variant.
The best workflow makes the unfinished state visible. Translation passes through preparation, assignment, drafting, review, approval, and release. Those states should not be confused with a content platform’s technical draft and publish toggles, which may have different meanings. A translated paragraph can be linguistically approved while its destination link is still unresolved. A reliable workflow therefore records both language quality and delivery readiness.
What can go wrong: A French translator edits an English record because Studio navigation does not expose locale visibly. Use a real handoff record. It should reveal which source text was reviewed, who approved the wording, what remains uncertain, and which page should be tested. A status such as ‘complete’ without those details gives false confidence. The record need not be bureaucratic: one clear page of evidence can prevent many hours of investigation.
What to do: Use language fields, grouped views and clear document titles or plugin controls. Give each item a small status record: source version, target locale, translator, reviewer, outstanding questions, release approval, and last verified rendering. When the source changes, flag the target for review even if the platform itself still labels it published. Use explicit handoffs and one accountable final owner. Without that separation, teams often mistake the fact that a field was saved for the far stronger claim that readers can trust it.
Acceptance evidence: A reviewer can find and identify the intended source and target documents without guesswork. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
11. Track source revisions and target review
Independent language documents can remain published after their shared source has materially changed.
Changes in a source language create a subtle problem: an existing target translation may still be grammatical but no longer accurate. A policy can acquire one exception, a feature can change name, or a pricing condition can be narrowed. Automated systems often see these as strings, but readers experience them as promises. Translation maintenance must connect target approval to the exact meaning and version of the source.
What can go wrong: An enrollment rule is updated in English while an older translated lesson promises the previous rule. Compare source revisions semantically. A changed adjective may be editorial; a changed condition about eligibility, safety or cost may require immediate target review. Highlight the changed meaning and ask the translator to revise the smallest complete unit that still makes sense. This is more efficient than blindly redoing every language after any edit.
What to do: Record source revisions and reopen impacted translations for targeted approval. When a source entry changes, capture the changed fields and the reason. Classify changes as cosmetic, factual, instructional, or legally significant. Reopen only affected target content, but test the surrounding journey to make sure the revised wording does not conflict with older labels. Keep a changelog comprehensible to a translator rather than only a developer. This reduces rework and makes regressions traceable.
Acceptance evidence: The target’s review state identifies the source version it accurately reflects. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
12. Query field-level locales with GROQ
A localized array needs a query that selects the requested language’s array item or value.
An API response is not the page a reader sees. It might expose the correct language while a frontend requests the default, caches an old item, or selects the first relation returned. Every technical translation guide must distinguish storage, retrieval, transformation, routing, and rendering. Different teams own those layers, so evidence must travel with the defect report. Otherwise each team can correctly say its own component works while the final experience remains wrong.
What can go wrong: A frontend asks for title and receives the entire array, then displays an arbitrary element. Use a controlled request and record its parameters. Verify the entry identifier, locale, selected fields, response status and whether the value is published. Only then examine the application output. Separating these checks makes a wrong-language page actionable: the team can name the layer that first produced the unexpected result.
What to do: Write and test a parameterized GROQ selection for the configured array shape. Test one entry by requesting the source locale, the target locale, and an unsupported locale in a controlled environment. Compare identifiers, field presence, and value origin. Then inspect the rendered route using the same entry. Capture timestamps, API parameters, response status, cache behavior, and the visible output. A documented example is more valuable than a generic claim that an endpoint is multilingual.
Acceptance evidence: The query returns one correct target-language title per requested locale. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
13. Query document-level translations with GROQ
Separate language documents are commonly filtered by a language field and associated through translation metadata references.
Selecting the correct locale requires more than rendering a selector. The site may infer language from a path, a domain, user preference, a browser header, or a request parameter. Those signals can conflict. A user who manually changes language should not be forced back by a background redirect. The application needs a clear precedence rule and a stable way to keep page identity across languages.
What can go wrong: A query finds the current document but offers language links to unrelated revisions. Test language choice as a continuous interaction. Start on a deeply nested target page, switch languages, follow an internal link, and refresh. If the requested language disappears, note exactly where. A durable route should describe both content identity and the chosen locale, while respecting any deliberate user preference rules.
What to do: Filter by document language and resolve the intended translation relationship. Walk through three routes: a new visitor entering from search, a returning visitor following a bookmark, and a reader switching language while on a deeply nested item. Observe the route, content, navigation labels, and next click in each case. If no translation exists, show a deliberate explanation or documented fallback. A selector that merely changes its own label without changing the item content is not localization.
Acceptance evidence: Each returned alternate page has the correct shared content identity. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
14. Build localized slugs with uniqueness rules
Separate localized documents may need their own slugs; a single string may not be globally unique across variants.
International search depends on content, URLs, and discoverability working together. A localized title may need a locally natural search phrase rather than a literal translation. A slug is a technical route, and an alternate-language annotation is a relationship between real pages. Neither should claim that a page exists when it does not. The content platform may store descriptions and slugs, but the website usually controls canonical URLs, sitemaps, and alternate links.
What can go wrong: Two translated lessons generate identical routes or one target slug overwrites a source route. SEO work begins with a real localized page, not a speculative alternate link. Search intent should sound natural to the target audience, with complete answers on the page. Inspect the actual title tag, description, route, canonical, alternate URLs and indexability. Never use international metadata to paper over a page whose essential content is still missing.
What to do: Define uniqueness for the chosen document scope and route structure. Write the principal search intent for each locale in the reader’s own language. Review title, summary, heading hierarchy, route, visible content, and links together. Confirm that the published frontend emits truthful canonical and hreflang signals if those are implemented. Avoid creating target URLs before the translation is substantive. Test a real URL in a browser and inspect its source; a correct CMS record does not guarantee a crawlable page.
Acceptance evidence: Every published language route resolves to exactly one intended document. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
15. Add international SEO in the consuming site
Sanity stores content; frontend code determines canonical links, hreflang, sitemap and route handling.
Permissions protect the integrity of translations. Content editors may be able to update a title without permission to approve a legal policy, and a machine integration should not automatically publish every target version. Public API access must be the minimum required to deliver published content. Drafts, personal information, internal notes, and unpublished translations should not leak merely because they sit in a related collection.
What can go wrong: The French page exists but publishes a canonical pointing to the wrong language version. Run role tests with real restricted permissions. Administrators can accidentally hide the fact that an integration has excessive access or that a translator cannot actually save a required field. Test both success and refusal. A good permissions model makes the legitimate task possible while preventing updates to identity, private drafts and unrelated locales.
What to do: Validate actual page-source metadata and use only published alternate destinations. Define separate responsibilities for source owners, translators, reviewers, publishers, and application integrations. Test each role with an account that has those exact privileges, not an administrator account. Include negative tests: a translator should not modify an operational identifier, a public request should not fetch drafts, and a reviewer should not accidentally publish unrelated locales. Role design is incomplete until those denials are observed.
Acceptance evidence: Search engines and readers can discover genuine corresponding language pages. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
16. Manage draft and published document states
Document-level localization permits language versions to be published independently, unlike a single shared field-level record.
Publication is a state transition, not simply a button press. Depending on the system, a localized field may share its parent record’s publication state, or each language record may be released independently. The difference affects launch dates, approvals, and rollback. Teams should also distinguish publishing content from invalidating a cache or deploying a frontend that can display it.
What can go wrong: An editor assumes approving a single locale inside a shared published document releases it separately. Carry the exact approval into delivery. Publishing a record may not update a deployed frontend or flush a cache, and preview can show content that visitors are not allowed to see. After release, fetch the public URL in a clean context and confirm the same source version, locale and meaning. Include a rollback path when a serious mistake appears.
What to do: Map approval workflow to the model’s real publication semantics. Build a release checklist using a single target entry. Verify the latest source version, language approval, required fields, links, locale routing, and live API response. Publish only the intended content, then fetch a fresh public page outside the editor. Check the previous language and an unrelated item to catch collateral changes. Record the result, the time and the responsible owner. If any critical condition fails, make the reversal procedure clear.
Acceptance evidence: The intended locale becomes public without unintentionally exposing incomplete variants. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
17. Use AI-assisted translation as a draft
Sanity offers optional AI Assist translation workflows, with plan and configuration requirements that should be checked.
Machine translation and AI can accelerate drafts but cannot define correctness by themselves. Structured fields may include placeholders, technical identifiers, product terms, citations, and policy qualifications that should be protected. Even a fluent draft may reverse a negation or make an optional action sound compulsory. The review standard should depend on the consequence of the words, not on whether a system generated them quickly.
What can go wrong: An automatic translation changes a course code or removes a condition about certification. Keep automated translation subordinate to the source record and approved glossary. Validate numbers, negation, conditional clauses, units, links, identifiers and region-specific claims before considering style. If the original is unclear, fix the source or request clarification from its owner; a fluent target cannot repair an unresolved factual ambiguity.
What to do: Protect identifiers, inspect nested content and require qualified review of consequential statements. For a controlled test, translate a short text containing a number, a URL, a condition, a disclaimer, and a term from an approved glossary. Compare the target to the source and mark factual omissions and additions. Ask a qualified reviewer to resolve ambiguity. Store accepted terminology and source version, but do not treat the output of one automated pass as publication approval. Automation belongs inside an accountable workflow.
Acceptance evidence: The approved output preserves structured data and source obligations. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
18. Test the entire localized course journey
A correct GROQ query can still feed a frontend with broken locale state, stale routes or mixed-language components.
Quality assurance must test both language and application behavior. Linguistic checks cover meaning, register, terminology, completeness, numbers, and readability. Technical checks cover fields, links, routing, permissions, rendering, directionality, and publication state. The distinction matters when a sentence is correct in a record but absent on the page, or when the webpage displays a plausible sentence from an unintended locale.
What can go wrong: A learner reads French lessons but a progress message or next-lesson link appears in English. Test a happy path and a failure path. The happy path proves that a complete translation can work; the failure path reveals what the product does when a field, relation or permission is missing. Both are needed for a trustworthy release. Give severe defects explicit owners and avoid declaring success until the reader-facing consequence has been checked.
What to do: Follow one route through course page, lesson, navigation, enrollment and confirmation. Create an evidence sheet for each locale: item identifier, source version, expected text, actual API output, visible page, reviewer, and decision. Include difficult examples such as long titles, blank values, nested links, right-to-left layouts, and a late source revision. Assign severity based on likely reader harm. An untranslated decorative tagline should not have the same priority as a mistranslated safety instruction or purchase commitment.
Acceptance evidence: The student completes the journey without an unexplained change of language. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
19. Watch dataset and deployment behavior
Caching and frontend deployment can obscure the effect of published Sanity changes.
The first release teaches the team where language actually flows through its product. Instead of celebrating the number of strings translated, monitor missing-content reports, wrong-language routes, broken links, support queries, and search impressions by locale. Read qualitative feedback: a visitor may complete a task yet still misunderstand a warning. Numbers are useful when paired with a concrete investigation of the reader journey.
What can go wrong: An editor sees a new target lesson in Studio while the live route still renders the previous version. Use support tickets and analytics to choose the next regression case. A surge of wrong-language exits might reflect routing, while confused questions about a policy might reflect wording. Investigate with a traceable example rather than treating every metric change as proof of translation quality. Publish a correction only after the responsible layer has been identified.
What to do: Trace published document, query, cache, route and rendered page in sequence. Track a small set of quality signals before and after the release. Investigate a surprising change by inspecting route, entry, source revision, and content delivery. Avoid drawing a conclusion about language quality from traffic alone; seasonality, campaigns, and product changes also influence it. Fix confirmed causes, then add that case to regression testing. Quality improves when real failures become durable learning rather than isolated support tickets.
Acceptance evidence: A fresh public request shows the intended approved revision. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
20. Govern schema migrations and new locales
Adding a language or changing the array/plugin structure can affect every existing localized document.
Localization becomes sustainable when there is an owner for changes after launch. New fields, revised source articles, deleted relations, plugin upgrades, and new locales can invalidate old assumptions. A translation system therefore needs documentation that an editor can understand without having built the original application. It also needs a simple way to stop publication when important meaning cannot be verified.
What can go wrong: A localization plugin upgrade changes filtering assumptions without changing the visible UI. Make the system understandable to the next editor. Record what is localized, what stays shared, which locale is the default, how missing values behave, and how a target page is approved. Revisit these decisions when the model or application changes. This is the practical difference between a one-off translation campaign and a maintainable multilingual publication.
What to do: Run a small regression set across known document and field-level examples after schema changes. Maintain a living record of locale rules, content ownership, approved terminology, fallback policy, release procedure, and unresolved exceptions. Review it when the schema or frontend changes. Keep a small regression collection of known difficult items and run it after upgrades. A professional translation operation is not one that never encounters errors; it is one that detects, explains, repairs, and learns from errors before readers are misled.
Acceptance evidence: Old languages and links remain correct while new ones are introduced. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
Twelve real-world diagnostic case files
The following case files are practical exercises for teams publishing with Sanity. Each begins with a reader-visible problem, then separates language, data, and delivery causes. They are illustrative situations rather than claims about the configuration of every installation. The diagnostic rule is to locate the first stage where expected meaning and observed meaning diverge.
Case 1: Choose the Sanity localization model
Starting symptom: A team stores a whole long-form lesson in a shared field despite needing separate release dates by locale.
An editorial team believes every page is covered because a dashboard shows a translation percentage. The first investigation should ask what the dashboard counts: text fields, published records, whole pages, or links. Build a single reader journey and enumerate every visible message. A percentage is a useful workload indicator but cannot establish that the journey works.
Resolution exercise: Use document-level records for independently published long text and field-level values for suitable shared records. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: Each content type has a documented rationale for its translation model.
Case 2: Define consistent language identifiers
Starting symptom: One query expects fr while another document stores fr-FR, making a translation appear absent.
A locale code appears valid but renders the wrong regional spelling. Compare language codes, market identifiers, browser preferences, and the actual API request. The remedy may be a route or selection rule, not a new translation. Keep a screenshot of the requested route and a record of the content field that supplied the text.
Resolution exercise: Choose supported identifiers and validate them in Studio schemas and client requests. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: The same locale choice resolves correctly in authoring and delivery.
Case 3: Separate shared course data from localized text
Starting symptom: A French document receives a different enrollment identifier and appears to be a separate course.
A translator changes a technical key because it resembles a word. A visible label improves, but another integration stops finding the record. Restore the shared identifier and move translated wording to the field intended for presentation. Add a field description so the next editor can distinguish a system identifier from reader-facing language.
Resolution exercise: Reference a shared course identity while translating descriptions and reader-facing instructions. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: Changing language preserves course identity and the actual entitlement.
Case 4: Connect language versions reliably
Starting symptom: An editor copies an English article but fails to place it in the correct translation group.
Two language pages stop linking to each other after a source article is duplicated. Compare the stored relation, translation group, and URL mapping. Fix the identity relationship rather than adding a hard-coded hyperlink only to the page that failed. Then test another item to prove the relation model, not just one exception, is correct.
Resolution exercise: Create and inspect the translation relationship using the project’s installed plugin and schema. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: The language switch returns a corresponding document, not an approximate title match.
Case 5: Understand internationalized arrays
Starting symptom: A developer reads the first array element as though array order identifies the locale.
A long translated heading breaks the mobile layout. Shortening it at random could delete an important condition. First check the content meaning, then the design allowance, line wrapping, and device width. A suitable result communicates the same condition naturally even when it uses more words than the original.
Resolution exercise: Select values by their language marker and check the installed plugin version. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: Reordering array elements does not change which language is displayed.
Case 6: Respect schema and plugin version differences
Starting symptom: A migration copies old filtering logic and reads the wrong array fields after an upgrade.
A related article appears in the source language when a target-language version is unavailable. Decide whether that destination should be hidden, explained, or deliberately offered as a fallback. Do not silently imply it is a translated article. Test the navigation from the user’s actual starting page.
Resolution exercise: Review the version-specific data shape and migrate or support legacy data deliberately. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: Queries return the correct language for both current and verified legacy test records.
Case 7: Design fallback as an explicit GROQ choice
Starting symptom: A generic coalesce expression shows English legal copy inside an otherwise French release.
A field is explicitly blank but the team expected the default language to appear. Inspect the platform’s treatment of absent values versus empty strings and unpublished variations. Use a clearly documented policy instead of guessing. Build fixtures for each state so later changes cannot silently reverse the intended behavior.
Resolution exercise: Permit fallback only for approved field categories and communicate unavailable content clearly. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: Sensitive fields do not silently fall back to unreviewed language.
Case 8: Translate Portable Text without losing structure
Starting symptom: A translated lesson drops the link annotation attached to an important citation.
A link survives translation but points to an outdated procedure. The problem is not a missing word; it is a broken promise about where the reader will go. Check both the link text and the destination’s current content and locale. A technically successful URL response does not prove that the destination is appropriate.
Resolution exercise: Keep block structure and references while revising language naturally; test the renderer. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: Quotations, lists, inline marks and link destinations survive target-language publication.
Case 9: Treat images and asset descriptions separately
Starting symptom: A reused photograph receives an English alt description on a Spanish lesson page.
An image contains an English instruction while the page text is in another language. Audit image alternatives, captions, and attached downloads. Either select a language-specific asset or provide a clear accessible explanation, depending on the material. Test what the user actually sees, not merely the metadata stored in the CMS.
Resolution exercise: Model and review accessible description fields by language where needed. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: The actual image, translated caption and text alternative agree.
Case 10: Build Studio views for translators
Starting symptom: A French translator edits an English record because Studio navigation does not expose locale visibly.
An editor marks a translation finished while the source is still under revision. Compare source version and target approval date. Explain the unfinished dependency and hold publication if the meaning may change. Status labels must describe the real workflow; they should not hide uncertainty by presenting a draft as final.
Resolution exercise: Use language fields, grouped views and clear document titles or plugin controls. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: A reviewer can find and identify the intended source and target documents without guesswork.
Case 11: Track source revisions and target review
Starting symptom: An enrollment rule is updated in English while an older translated lesson promises the previous rule.
A source policy acquires an exception after translations were approved. Identify every affected locale and every place the condition appears. Reopen those items for targeted review, then verify the visible path a reader follows. Do not assume a fluent older translation still conveys the amended rule.
Resolution exercise: Record source revisions and reopen impacted translations for targeted approval. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: The target’s review state identifies the source version it accurately reflects.
Case 12: Query field-level locales with GROQ
Starting symptom: A frontend asks for title and receives the entire array, then displays an arbitrary element.
The API returns the expected target-language text but the browser shows the source. Trace parameters, cache keys, application route state, and component rendering. Identify the first layer where the requested locale disappears. Fix that layer and record the reproducing request rather than rewriting a correct translation.
Resolution exercise: Write and test a parameterized GROQ selection for the configured array shape. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: The query returns one correct target-language title per requested locale.
Worked example: from one entry to a verified multilingual page
Create an English course document and a French counterpart in a staging dataset or clearly separated test scope. Join them using the chosen language relationship, publish only the reviewed target, then query both languages explicitly. Inspect any Portable Text blocks, internal references and localized slugs. Switch language from a deep course route in the frontend, verify that both variants refer to the same stable course ID, and check that missing translations lead to documented behavior rather than an unrelated course.
Write down the intended public sentence before opening the editing interface. Mark each part that expresses a rule, a quantity, a relationship, a date, or a condition. These are the parts most likely to cause harm if their meaning changes. Next, create the target text using the available editor workflow. Review it beside the source with a person who understands the original instruction. Read both versions without their headings and ask whether they would lead a reasonable reader to the same relevant decision.
Now inspect the structured record. Confirm that the translation belongs to the correct underlying item and requested language. Check what happens if one target field is missing, if a relation is unpublished, and if a visitor follows a bookmark instead of starting at the homepage. Request the content through the application or API exactly as the public client will request it. Compare the response with the intended wording, then view the final page on a narrow screen and with a keyboard where possible.
Finally, check the title and description that the published page presents to search engines, the destination of every important link, and any alternate-language relationship. The reader should not be redirected to an unrelated object or an unapproved target page. Only after these checks should the target page be called complete. Save a compact test record containing locale, item ID, route, source revision, reviewer, and outcome; it will become a reusable regression test.
A quality rubric that distinguishes serious failures from cosmetic issues
Treat a changed meaning about eligibility, health, safety, payment, rights, privacy or physical access as critical. A missing instruction that prevents a task is high priority. Incorrect locale routing, missing linked records and wrong-language search descriptions deserve investigation even when the wording itself is fluent. Minor punctuation or layout differences may be lower priority, provided they do not conceal qualifications. Assign severity from the reader’s likely consequence, not the number of characters affected.
Score an item against six independent questions: Is the meaning faithful? Is the language natural and suitable for its audience? Are identities, numbers and relationships intact? Does the requested locale return the right version? Is the published journey accessible and usable? Can the team reproduce the result after another update? A professional review should record a clear answer and evidence for each question rather than an overall percentage with no explanation.
A four-week implementation and learning plan
Week 1 — Map and model
Inventory current languages, source owners, records, localized fields, relationships and public routes. Choose ten representative entries containing simple text, long instructions, one missing value, a relation, and a media asset. Establish the locale matrix and a glossary. End the week with a single approved test specimen, not an estimate of translated volume.
For Sanity, attach the actual locale selection, content identifiers and verification requests to this week’s findings. If a problem cannot be reproduced, collect the reader’s route, time and observed wording before changing production content. A small, verified release gives the next group of translators a trustworthy example to copy.
Week 2 — Translate and review
Translate the representative items with context visible to the editor. Check conditions, numbers, abbreviations, references, headings and accessibility wording. Have reviewers explain the target reader’s likely interpretation. Hold back any source passage whose meaning is unresolved. Create a clear list of fields and links that still require technical work.
For Sanity, attach the actual locale selection, content identifiers and verification requests to this week’s findings. If a problem cannot be reproduced, collect the reader’s route, time and observed wording before changing production content. A small, verified release gives the next group of translators a trustworthy example to copy.
Week 3 — Test delivery and failure paths
Query source and target locales, inspect API responses, verify frontend routes and alternate-language navigation, then test incomplete records. Include preview versus published behavior, right-to-left text where relevant, mobile width and a public permission check. Turn each discovered fault into one documented regression case with an owner.
For Sanity, attach the actual locale selection, content identifiers and verification requests to this week’s findings. If a problem cannot be reproduced, collect the reader’s route, time and observed wording before changing production content. A small, verified release gives the next group of translators a trustworthy example to copy.
Week 4 — Publish a controlled release
Release one complete target-language journey with sign-off from content, language and technical owners. Inspect the public page and critical next action, not merely the CMS save screen. Track reports of wrong-language text and broken routes. Review what should be added to the glossary, documentation and next release checklist.
For Sanity, attach the actual locale selection, content identifiers and verification requests to this week’s findings. If a problem cannot be reproduced, collect the reader’s route, time and observed wording before changing production content. A small, verified release gives the next group of translators a trustworthy example to copy.
Practice exercises with model answers
Exercise 1: One field is not localized
Ask whether the field was configured as shared, whether the target value is missing, and whether a fallback is hiding the gap. Answer: preserve the source if it is a genuine shared fact; otherwise make the field eligible for translation and test its public value. In your Sanity project, write the item identifier, requested locale, expected outcome and evidence needed to prove the answer. The exercise is complete only when another person can repeat your observation.
Exercise 2: A language switch goes to another item
Check the translation relationship or shared identity, not merely whether two titles look alike. Answer: repair the identity mapping and test language switching in both directions on more than one item. In your Sanity project, write the item identifier, requested locale, expected outcome and evidence needed to prove the answer. The exercise is complete only when another person can repeat your observation.
Exercise 3: A translated button opens source-language instructions
Inspect the destination content and route for an approved target version. Answer: link to the correct localized destination or disclose a deliberate fallback, then test the reader’s next action. In your Sanity project, write the item identifier, requested locale, expected outcome and evidence needed to prove the answer. The exercise is complete only when another person can repeat your observation.
Exercise 4: A source qualification changes after release
Compare source revisions and identify the affected target languages. Answer: reopen relevant translations, confirm the meaning with the source owner, and verify the visible page before approving the new revision. In your Sanity project, write the item identifier, requested locale, expected outcome and evidence needed to prove the answer. The exercise is complete only when another person can repeat your observation.
Exercise 5: The CMS preview and public page disagree
Compare draft and published state, API selection, permissions, cache and frontend rendering. Answer: locate the first layer where the expected locale or version diverges, rather than translating the sentence again. In your Sanity project, write the item identifier, requested locale, expected outcome and evidence needed to prove the answer. The exercise is complete only when another person can repeat your observation.
Frequently asked questions
What does professional translation mean in a structured CMS?
It means preserving approved meaning and relationships through authoring, API delivery, routing and the published reader journey. A page is not complete merely because a field contains target-language words. For Sanity, verify the specific data model and installed release rather than assuming another platform behaves identically.
Must every field be translated?
No. Stable identifiers and shared operational facts should normally remain stable. Reader-facing wording and locally relevant explanations may need translation or market-specific approval. The classification belongs in the content model and editorial rules. For Sanity, verify the specific data model and installed release rather than assuming another platform behaves identically.
How should we select the first target language?
Consider a documented audience need, an available reviewer, the amount of existing content and the technical effort required. Start with one complete journey and a verified locale code before expanding the whole catalogue. For Sanity, verify the specific data model and installed release rather than assuming another platform behaves identically.
Can we use automatic translation?
It can help prepare drafts when configured and allowed. Review every consequential condition, number, named entity, linked destination, legal statement and accessibility instruction. Automation cannot grant publication approval. For Sanity, verify the specific data model and installed release rather than assuming another platform behaves identically.
How should an unavailable translation appear?
Choose an explicit policy: a clearly identified fallback, a message that the translation is unavailable, or a withheld page. Do not silently imply complete target-language coverage when a critical field is missing. For Sanity, verify the specific data model and installed release rather than assuming another platform behaves identically.
Should a language switch keep the user on the same content?
Normally yes, when an equivalent translated item exists. That requires a stable identity relationship and deliberate route mapping; matching only the visible title is unreliable. For Sanity, verify the specific data model and installed release rather than assuming another platform behaves identically.
Are translated slugs enough for international SEO?
No. Search success requires meaningful localized content, an accessible route, appropriate metadata, working links and truthful alternate-language signals generated by the site. For Sanity, verify the specific data model and installed release rather than assuming another platform behaves identically.
Why do drafts appear correct while the public page is wrong?
Editors may see preview versions, while public requests use published data, different permissions or caches. Compare the specific request, response, route and rendering to find where the values diverge. For Sanity, verify the specific data model and installed release rather than assuming another platform behaves identically.
How do we handle a source change?
Record what changed and why, identify affected target versions, re-review the altered meaning, then retest the published journey. Minor formatting and substantive obligations should receive different review priority. For Sanity, verify the specific data model and installed release rather than assuming another platform behaves identically.
Who should approve a translation?
Language specialists review meaning and natural expression. The content or business owner verifies factual rules; technical owners verify delivery, routing and permissions. One accountable release owner joins those decisions. For Sanity, verify the specific data model and installed release rather than assuming another platform behaves identically.
What should we test before publishing?
Check locale, identity, shared fields, complete meaning, rich text, assets, links, permissions, API output, route, SEO metadata, mobile layout and a negative case. Keep concise evidence for each result. For Sanity, verify the specific data model and installed release rather than assuming another platform behaves identically.
What makes a guide useful after launch?
A named owner, glossary, locale policy, regression examples, change log and a method for escalating defects. Sustainable localization is a process of correcting observed failures, not only creating translated text. For Sanity, verify the specific data model and installed release rather than assuming another platform behaves identically.
Official documentation and connected learning
The authoritative source for platform mechanics is the maintained product documentation. Features, permissions and interface labels can change across releases. Use the documentation for your installed version and test the actual workflow in your project. References: Sanity content localization; Sanity AI-assisted translation.
For the larger principles of translation accuracy and ethical publishing, continue with Master Art of Translation | The Complete System for Moving Meaning Between Languages and the Translate Like a Pro | Series Index. The previous platform-specific guide on HCL Commerce multilingual catalog and search addresses a different environment; this article focuses on Sanity content architecture, delivery, editorial control and reader verification.