Document Internationalization Plugin for Sanity.io
This is a Sanity Studio v3 plugin. For the v2 version, please refer to the v2-branch.
What this plugin solves
There are two popular methods of internationalization in Sanity Studio:
- Document-level translation
- A unique document version for every language
- Joined together by references and/or a predictable
_id
- Best for documents that have unique, language-specific fields and no common content across languages
- Best for translating content using Portable Text
- Field-level translation
- A single document with many languages of content
- Achieved by mapping over languages on each field, to create an object
- Best for documents that have a mix of language-specific and common fields
- Not recommended for Portable Text
This plugin adds features to the Studio to improve handling document-level translations.
- A Language Selector to create and browse language-specific versions of each Document
- Document Actions to update base and translated documents to ensure references stay in tact
- Document Badges to highlight the language version of a document
For field-level translations you should use the @sanity/language-filter plugin.
Many projects use both!
An example of document-level translation could be a lesson
schema, the title
, slug
and content
fields would be unique in every language.
A good use of field-level translation could be a person
schema. It could have the same name
and image
in every language, but only the biography
would need translating.
Installation
From the same directory as the Studio run:
npm install --save @sanity/document-internationalization
or
yarn add @sanity/document-internationalization
The plugin is now installed, but you will need to complete the following steps to see the Document Translation UI:
Setup next steps
- Enabling and configuring the plugin
To declare available Languages and other settings - Activating internationalization on schema
To enable all the above features on schema - Customise Desk Structure
To filter documents down to the base language version
Other documentation
- Known Caveats
- Data structure
- Translation Maintenance
- GraphQL support
- Advanced languages
- Usage with custom publish action
- If you don't see the plugin document actions
- GROQ query examples
Migrating from sanity-plugin-intl-input
While most of the UI is the same in the official version of this plugin there are some breaking changes you should be aware of before migrating:
Coming from sanity-plugin-intl-input
License
MIT-licensed. See LICENSE.
Develop & test
This plugin uses @sanity/plugin-kit with default configuration for build & watch scripts.
See Testing a plugin in Sanity Studio on how to run this plugin with hotreload in the studio.
Release new version
Run "CI & Release" workflow. Make sure to select the main branch and check "Release new version".
Semantic release will only release on configured branches, so it is safe to run release on any branch.