iainvdw / document-internationalization

sanity.io plugin for authoring multiple language versions of a complete document

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

1. Enabling and configuring the plugin
   To declare available Languages and other settings
2. Activating internationalization on schema
   To enable all the above features on schema
3. Customise Desk Structure
   To filter documents down to the base language version

Other documentation

1. Known Caveats
2. Data structure
3. Translation Maintenance
4. GraphQL support
5. Advanced languages
6. Usage with custom publish action
7. If you don't see the plugin document actions
8. 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.