What this plugin solves

Many projects use both

Upgrade

Install

npm install --save @sanity/document-internationalization

Usage

Basic configuration

// sanity.config.tsimport{defineConfig}from'sanity'import{documentInternationalization}from'@sanity/document-internationalization'exportconstdefineConfig({// ... all other configplugins:[// ... all other pluginsdocumentInternationalization({// Required configurationsupportedLanguages:[{id:'es',title:'Spanish'},{id:'en',title:'English'}],schemaTypes:['lesson'],})]})

Advanced configuration

// sanity.config.tsimport{defineConfig}from'sanity'import{documentInternationalization}from'@sanity/document-internationalization'exportconstdefineConfig({// ... all other configplugins:[// ... all other pluginsdocumentInternationalization({// Required// Either: an array of supported languages...supportedLanguages:[{id:'nb',title:'Norwegian (Bokmål)'},{id:'nn',title:'Norwegian (Nynorsk)'},{id:'en',title:'English'}],// ...or a function that takes the client and returns a promise of an array of supported languages// MUST return an "id" and "title" as strings// Note: Async language configuration cannot create templates for new documents// supportedLanguages: (client) => client.fetch(`*[_type == "language"]{id, title}`),// Required// Translations UI will only appear on these schema typesschemaTypes:['lesson'],// Optional// Customizes the name of the language fieldlanguageField:`language`,// defauts to "language"// Optional// Keep translation.metadata references weakweakReferences:true,// defaults to false// Optional// Adds UI for publishing all translations at once. Requires access to the Scheduling API// https://www.sanity.io/docs/scheduling-apibulkPublish:true,// defaults to false// Optional// Adds additional fields to the metadata documentmetadataFields:[defineField({name:'slug',type:'slug'}),],// Optional// Define API Version for all queries// https://www.sanity.io/docs/api-versioningapiVersion:'2025-02-19',// Optional// Enable "manage translations" button without creating a translated version. Helpful if you have// pre-existing documents that you need to tie together through the metadata documentallowCreateMetaDoc:true,// defaults to false// Optional// Callback function that runs after a translation document has been created// Note: Defaults to nullcallback:({        sourceDocument,// The document in the original language        newDocument,// The newly created translation of the source document        sourceLanguageId,// The id of the original language        destinationLanguageId,// The id of the destination language        metaDocumentId,// The id of the meta document referencing the document translations        client// Sanity client}){// Your function implementation}})]})

Language field

// ./schema/lesson.ts// ...all other settingsdefineField({// should match 'languageField' plugin configuration setting, if customizedname:'language',type:'string',readOnly:true,hidden:true,})

Excluding fields

defineField({name:'title',title:'Title',type:'string',options:{documentInternationalization:{exclude:true,},},}),

Querying translations

Querying with GROQ

// All `lesson` documents of a single language*[_type=="lesson"&&language==$language]{title,slug,language,// Get the translations metadata// And resolve the `value` reference field in each array item"_translations":*[_type=="translation.metadata"&&references(^._id)].translations[].value->{    title,    slug,    language},}

Querying with GraphQL

# In this example we retrieve a lesson by its `slug.current` field valuequeryGetLesson($language:String!,$slug:String!) {allLesson(limit:1where: {language: {eq:$language},slug: {current: {eq:$slug}}}  ) {_idtitlelanguageslug {current    }  }}# And then can run this query to find translation metadata documents that use its IDqueryGetTranslations($id:ID!) {allTranslationMetadata(where: {_: {references:$id}}) {translations {_keyvalue {titleslug {current        }      }    }  }}

Note on document quotas

Documentation

License

Develop & test

Release new version