Field-level vs document-level localization
Field-level. With field-level localization, all languages are published at the same time. Storing translations as array items with language and value fields avoids creating a new dataset attribute for each added language. The internationalized-array plugin works with any field type and is meant for field-level translations.
Document-level. Document-level localization lets each language version be published on its own schedule. Sanity recommends document-level localization for rich text written in Portable Text. The @sanity/document-internationalization plugin sets a language field on documents and keeps the translations together in a linked document. It relies on the internationalized-array plugin, which moved the language identifier from _key to a language field in v5.
At query time, coalesce() in GROQ can fall back to another language when a translation is missing. Setup details for both methods are in Sanity's localization documentation.
Translation workflow options
Webhooks. GROQ-powered webhooks can send documents to an external translation service through its API.
Adapter plugins. Sanity offers adapter plugins for translation services, including Transifex and Smartling.
AI Assist. For full-document translation, AI Assist reads a configured language field to decide the target language. AI Assist translation is a paid feature on the Growth plan and above.
Translating the Studio interface is separate from localizing content and is done by installing a language plugin such as @sanity/locale-de-de. Sanity's course defines localization as adapting content and UI to one language, while internationalization prepares the front end for many languages.
If one Studio also serves several sites, read how to manage multiple websites from one Sanity instance. For the CMS basics, see what Sanity is and how it works.
How Pagepro sets up localization on Sanity
On Sanity development projects, Pagepro uses document-level localization for pages. Before translation starts, Pagepro audits fields with maxLength rules, because text in longer languages breaks them. The team also makes the Presentation preview locale-aware, since links inside a translated document's preview resolve to the base locale by default.
Sources
- LocalizationSanity · sanity.io
- @sanity/document-internationalization READMESanity · github.com
- Content translation with AI AssistSanity · sanity.io
- Localizing Sanity StudioSanity · sanity.io
- Localization course: IntroductionSanity · sanity.io