Nuclear Powered Mushroom

    @sanity/language-filter
    TypeScript icon, indicating that this package has built-in type declarations

    3.0.0 • Public • Published

    @sanity/language-filter

    This is a Sanity Studio v3 plugin. For the v2 version, please refer to the v2 version.

    Field-level translation filter Plugin for Sanity.io

    A Sanity plugin that supports filtering localized fields by language

    Language Filter UI

    What this plugin solves

    There are two popular methods of internationalization in Sanity Studio:

    • 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
    • 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

    This plugin adds features to the Studio to improve handling field-level translations.

    • A "Filter Languages" button to show/hide fields in an object of language-specific fields
    • Configuration to set "default" languages which are always visible

    For document-level translations you should use the @sanity/document-internationalization plugin.

    Installation

    npm install --save @sanity/language-filter
    

    or

    yarn add @sanity/language-filter
    

    Usage

    Add it as a plugin in sanity.config.ts (or .js), and configure it:

     import {defineConfig} from 'sanity'
     import {languageFilter} from '@sanity/language-filter'
    
     export const defineConfig({
         //...
         plugins: [
            languageFilter({
                supportedLanguages: [
                  {id: 'nb', title: 'Norwegian (Bokmål)'},
                  {id: 'nn', title: 'Norwegian (Nynorsk)'},
                  {id: 'en', title: 'English'},
                  {id: 'es', title: 'Spanish'},
                  {id: 'arb', title: 'Arabic'},
                  {id: 'pt', title: 'Portuguese'},
                  //...
                ],
                // Select Norwegian (Bokmål) by default
                defaultLanguages: ['nb'],
                // Only show language filter for document type `page` (schemaType.name)
                documentTypes: ['page'],
                filterField: (enclosingType, field, selectedLanguageIds) =>
                  !enclosingType.name.startsWith('locale') || selectedLanguageIds.includes(field.name),
           })
         ]
     })
    

    Config properties:

    • supportedLanguages is an array of languages with id and title. If your localized fields are defined using our recommended way described here (https://www.sanity.io/docs/localization), you probably want to share this list of supported languages between this config and your schema.
    • defaultLanguages (optional) is an array of strings where each entry must match an id from the supportedLanguages array. These languages will be listed by default and will not be possible to unselect. If no defaultLanguages is configured, all localized fields will be selected by default.
    • documentTypes (optional) is an array of strings where each entry must match a name from your document schemas. If defined, this property will be used to conditionally show the language filter on specific document schema types. If undefined, the language filter will show on all document schema types.
    • filterField (optional) is a function that must return true if the field should be displayed. It is passed the enclosing type (e.g the object type containing the localized fields, the field, and an array of the currently selected language ids. This function is called for all fields and in objects for documents that have language filter enabled. Default: !enclosingType.name.startsWith('locale') || selectedLanguageIds.includes(field.name)

    Changes in V3

    documentTypes

    Language filter can now be enabled/disabled directly from a schema, using options.languageFilter: boolean. When documentTypes is omitted from plugin config, use options.languageFilter: false in a document-definition to hide the filter button. When documentTypes is provided in plugin config, use options.languageFilter: true in a document-definition to show the filter button.

    Example:

    export const myDocumentSchema = {
      type: 'document',
      name: 'my-enabled-language-filter-document',
      /** ... */
      options: {
        // show language filter for this document type, regardless of how documentTypes for the plugin is configured
        languageFilter: true
      }
    }

    State management

    Selected languages are now stored as langs url-param state; this allows users to copy paste a url in the studio with the currently selected languages preselected.

    Previously this state was stored in localstorage.

    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.

    Keywords

    none

    Install

    npm i @sanity/language-filter

    DownloadsWeekly Downloads

    1,378

    Version

    3.0.0

    License

    MIT

    Unpacked Size

    97.2 kB

    Total Files

    21

    Last publish

    Collaborators

    • svirs
    • josh_sanity_io
    • joneidejohnsen
    • nina.andal
    • rankers
    • snorreeb
    • mattcraig
    • vincentquigley
    • stipsan
    • michael-sanity
    • rubioz
    • tonina
    • ritasdias
    • simeonsanity
    • kmelve
    • bjoerge
    • rexxars
    • skogsmaskin
    • simenss
    • robinpyon
    • mariuslundgard
    • sanity-io
    • evenw
    • radhe_sanity
    • rbotten
    • vicbergquist
    • judofyr
    • obliadp
    • dcilke
    • fredcarlsen
    • jorn_georg
    • hermanw
    • mikolajsanity
    • sgulseth
    • atombender