sanity-plugin-internationalized-array 4.0.3 → 5.0.0-canary.0

package/README.md

@@ -1,6 +1,6 @@
 # sanity-plugin-internationalized-array
 
-A plugin to register array fields with a custom input component to store field values in multiple languages, queryable by using the language ID as an array `_key`.
+A plugin to register array fields with a custom input component to store field values in multiple languages, queryable by using a dedicated `language` field.
 
 ![Screenshot of an internationalized input](./img/internationalized-array.png)
 
@@ -15,6 +15,7 @@ A plugin to register array fields with a custom input component to store field v
   - [Usage with @sanity/language-filter](#usage-with-sanitylanguage-filter)
   - [Shape of stored data](#shape-of-stored-data)
   - [Querying data](#querying-data)
+  - [Migrate from v4 to v5](#migrate-from-v4-to-v5)
   - [Migrate from objects to arrays](#migrate-from-objects-to-arrays)
     - [Why store localized field data like this?](#why-store-localized-field-data-like-this)
   - [License](#license)
@@ -42,18 +43,18 @@ Add it as a plugin in sanity.config.ts (or .js):
 import {defineConfig} from 'sanity'
 import {internationalizedArray} from 'sanity-plugin-internationalized-array'
 
- export const defineConfig({
+export default defineConfig({
   // ...
   plugins: [
     internationalizedArray({
       languages: [
         {id: 'en', title: 'English'},
-        {id: 'fr', title: 'French'}
+        {id: 'fr', title: 'French'},
       ],
       defaultLanguages: ['en'],
       fieldTypes: ['string'],
-    })
-  ]
+    }),
+  ],
 })
 ```
 
@@ -143,16 +144,16 @@ The "Add all languages" button can be hidden with `buttonAddAll`.
 import {defineConfig} from 'sanity'
 import {internationalizedArray} from 'sanity-plugin-internationalized-array'
 
- export const defineConfig({
+export default defineConfig({
   // ...
   plugins: [
     internationalizedArray({
       // ...other config
       buttonLocations: ['field', 'unstable__fieldAction', 'document'], // default ['field']
       buttonAddAll: false, // default true
-      languageDisplay: 'codeOnly' // codeOnly (default) | titleOnly | titleAndCode
-    })
-  ]
+      languageDisplay: 'codeOnly', // codeOnly (default) | titleOnly | titleAndCode
+    }),
+  ],
 })
 ```
 
@@ -164,7 +165,7 @@ For more control over the `value` field, you can pass a schema definition into t
 import {defineConfig} from 'sanity'
 import {internationalizedArray} from 'sanity-plugin-internationalized-array'
 
- export const defineConfig({
+ export default defineConfig({
   // ...
   plugins: [
     internationalizedArray({
@@ -280,75 +281,163 @@ If you have many languages and authors that predominately write in only a few, [
 
 ![Internationalized array field filtered with language-filter](https://github.com/sanity-io/language-filter/assets/9684022/4b402520-4128-4e6e-af07-960a10be397e)
 
-Configure both plugins in your sanity.config.ts file:
+The plugin includes built-in integration with `@sanity/language-filter`.
+To enable it, add `languageFilter.documentTypes` in the plugin config for the document types that should show the filter.
 
 ```ts
-// ./sanity.config.ts
-
-import {defineConfig, isKeySegment} from 'sanity'
-import {languageFilter} from '@sanity/language-filter'
+import {defineConfig} from 'sanity'
+import {internationalizedArray} from 'sanity-plugin-internationalized-array'
 
 export default defineConfig({
-  // ... other config
+  // ...
   plugins: [
-    // ... other plugins
-    languageFilter({
-      // Use the same languages as the internationalized array plugin
-      supportedLanguages: SUPPORTED_LANGUAGES,
-      defaultLanguages: [],
-      documentTypes: ['post'],
-      filterField: (enclosingType, member, selectedLanguageIds) => {
-        // Filter internationalized arrays
-        if (
-          enclosingType.jsonType === 'object' &&
-          enclosingType.name.startsWith('internationalizedArray') &&
-          'kind' in member
-        ) {
-          // Get last two segments of the field's path
-          const pathEnd = member.field.path.slice(-2)
-          // If the second-last segment is a _key, and the last segment is `value`,
-          // It's an internationalized array value
-          // And the array _key is the language of the field
-          const language =
-            pathEnd[1] === 'value' && isKeySegment(pathEnd[0]) ? pathEnd[0]._key : null
-
-          return language ? selectedLanguageIds.includes(language) : false
-        }
-
-        // Filter internationalized objects if you have them
-        // `localeString` must be registered as a custom schema type
-        if (enclosingType.jsonType === 'object' && enclosingType.name.startsWith('locale')) {
-          return selectedLanguageIds.includes(member.name)
-        }
-
-        return true
+    internationalizedArray({
+      languages: [
+        {id: 'en', title: 'English'},
+        {id: 'fr', title: 'French'},
+      ],
+      defaultLanguages: ['en'],
+      fieldTypes: ['string'],
+      languageFilter: {
+        documentTypes: ['internationalizedPost', 'lesson'],
       },
     }),
   ],
 })
 ```
 
+If you need more control, you can continue using `@sanity/language-filter` directly and pass `internationalizedArrayLanguageFilter` from this package as your `filterField`.
+
 ## Shape of stored data
 
-The custom input contains buttons which will add new array items with the language as the `_key` value. Data returned from this array will look like this:
+The custom input contains buttons which will add new array items with a random `_key` and the language stored in a dedicated `language` field. Data returned from this array will look like this:
 
 ```json
 "greeting": [
-  { "_key": "en", "value": "hello" },
-  { "_key": "fr", "value": "bonjour" },
+  { "_key": "abc123", "language": "en", "value": "hello" },
+  { "_key": "def456", "language": "fr", "value": "bonjour" },
 ]
 ```
 
 ## Querying data
 
-Using GROQ filters you can query for a specific language key like so:
+Using GROQ filters you can query for a specific language like so:
 
 ```js
 *[_type == "person"] {
-  "greeting": greeting[_key == "en"][0].value
+  "greeting": greeting[language == "en"][0].value
 }
 ```
 
+## Migrate from v4 to v5
+
+v5 stores the language identifier on a dedicated `language` field instead of `_key`.
+
+### 1. Backup your data.
+
+You can manually backup your data using the sanity CLI.
+
+```
+sanity dataset export production
+```
+
+This creates a production.tar.gz file in your current directory containing all your documents and assets.
+
+You can also specify a custom filename and location:
+
+```
+sanity dataset export production ./backups/backup-2026-02-16.tar.gz
+```
+
+If you ever need to restore, use the import command:
+
+```
+sanity dataset import backup-2026-02-16.tar.gz production
+```
+
+Or you can use the backup service, read more at https://www.sanity.io/docs/content-lake/backups
+
+### 2. Update your GROQ queries.
+
+Use a backwards compatible query until your migration is ready and has been executed.
+
+```diff
+*[_type == "person"] {
+-  "greeting": greeting[_key == "en"][0].value
++  "greeting": greeting[language == "en" || _key == "en"][0].value
+}
+```
+
+### 3. Data migration
+
+The package exports a migration helper that you can run with the [migration CLI](https://www.sanity.io/docs/cli-reference/cli-migration).
+
+Create a migration file in your project and export it:
+
+```ts
+// ./migrations/migrateToLanguageField.ts
+import {migrateToLanguageField} from 'sanity-plugin-internationalized-array/migrations'
+
+// Add the document types that contain internationalized arrays.
+// Example: ['internationalizedPost', 'translation.metadata']
+const DOCUMENT_TYPES: string[] = []
+
+export default migrateToLanguageField(DOCUMENT_TYPES)
+```
+
+Then verify your migration with a dry run:
+
+```bash
+pnpm sanity migration run migrateToLanguageField
+```
+
+Once ready, run the migration:
+
+```bash
+pnpm sanity migration run migrateToLanguageField --no-dry-run
+```
+
+**If you use [@sanity/document-internationalization](https://github.com/sanity-io/plugins/tree/main/plugins/@sanity/document-internationalization):** Include `'translation.metadata'` in your migration's document types so that the `translations` array on metadata documents is migrated
+And update `@sanity/document-internationalization` to `v6`
+
+### 4. Update your GROQ queries
+
+Previously we updated the GROQ queries to support both locations for the language field. Once migration is complete, update the GROQ queries again to only use `language` and remove the dependency on `_key`.
+
+```diff
+*[_type == "person"] {
+-  "greeting": greeting[language == "en" || _key == "en"][0].value
++  "greeting": greeting[language == "en"][0].value
+}
+```
+
+## Usage with language filter
+
+The plugin now includes built-in integration with `@sanity/language-filter`.
+To enable it, add `languageFilter.documentTypes` in the plugin config for the document types that should show the filter.
+
+```ts
+import {defineConfig} from 'sanity'
+import {internationalizedArray} from 'sanity-plugin-internationalized-array'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    internationalizedArray({
+      languages: [
+        {id: 'en', title: 'English'},
+        {id: 'fr', title: 'French'},
+      ],
+      defaultLanguages: ['en'],
+      fieldTypes: ['string'],
+      languageFilter: {
+        documentTypes: ['internationalizedPost', 'lesson'],
+      },
+    }),
+  ],
+})
+```
+
 ## Migrate from objects to arrays
 
 [See the migration script](./migrations/transformObjectToArray.ts) inside `./migrations/transformObjectToArray.ts` of this plugin.

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as sanity0 from "sanity";
 import { FieldDefinition, Rule, RuleTypeConstraint, SanityClient } from "sanity";
+import { FilterFieldFunction } from "@sanity/language-filter";
 type Language = {
   id: Intl.UnicodeBCP47LocaleIdentifier;
   title: string;
@@ -25,13 +26,15 @@ type ArrayConfig = {
  * @deprecated Use InternationalizedArrayItem instead
  */
 type Value = {
-  _key: string;
+  _key: string; /** Language identifier (e.g., 'en', 'fr'). Added in v5. */
+  language: string;
   value?: unknown;
 };
 declare function isInternationalizedArrayItemType(type: string): type is InternationalizedArrayItem['_type'];
 type InternationalizedArrayItem<T = unknown> = {
   _key: string;
-  value?: T;
+  value?: T; /** Language identifier (e.g., 'en', 'fr'). Added in v5. */
+  language: string;
   /**
    * string that starts with "internationalizedArray" and ends with "Value"
    */
@@ -134,15 +137,50 @@ type PluginConfig = {
    * @defaultValue 'code'
    * */
   languageDisplay?: LanguageDisplay;
+  /**
+   * Configure the language filter for the plugin by providing the document types that should show the filter.
+   * ```tsx
+   * {
+   *   languageFilter: {
+   *     documentTypes: ['internationalizedPost', 'lesson']
+   *   }
+   * }
+   * ```
+   */
+  languageFilter?: {
+    documentTypes: string[];
+  };
 };
 declare const clear: () => void;
-declare const internationalizedArray: sanity0.Plugin<PluginConfig>;
 /**
  * The field name used to identify the language of an internationalized array item.
  *
- * In v4.x this was '_key', in v5+ this will be 'language'.
- * Having this as a constant makes the codebase easier to maintain.
+ * In v4.x this was '_key', in v5+ this is 'language'.
+ * ```ts
+ * {
+ *    "description": [
+ *      {
+ *        "_key": "kjjNvZHK8Y2QpTEf3K5jc",
+ *        "_type": "internationalizedArrayTextValue",
+ *        "language": "en"
+ *        "value": "This is the description in English"
+ *      },
+ *      {
+ *        "_key": "kjjNvZHK8Y2QpTEf3K5jc",
+ *        "_type": "internationalizedArrayTextValue",
+ *        "language": "es"
+ *        "value": "This is the description in Spanish"
+ *      },
+ *    ]
+ * }
+ * ```
+ */
+declare const LANGUAGE_FIELD_NAME: "language";
+declare const internationalizedArray: sanity0.Plugin<PluginConfig>;
+/**
+ * Default filter function for the internationalized array field.
+ * It filter the field base on the `language` value of the object.
  */
-declare const LANGUAGE_FIELD_NAME: "_key";
-export { AllowedType, ArrayConfig, InternationalizedArrayItem, LANGUAGE_FIELD_NAME, Language, LanguageCallback, LanguageDisplay, PluginConfig, Value, clear, internationalizedArray, isInternationalizedArrayItemType };
+declare const internationalizedArrayLanguageFilter: FilterFieldFunction;
+export { AllowedType, ArrayConfig, InternationalizedArrayItem, LANGUAGE_FIELD_NAME, Language, LanguageCallback, LanguageDisplay, PluginConfig, Value, clear, internationalizedArray, internationalizedArrayLanguageFilter, isInternationalizedArrayItemType };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/cache.ts","../src/plugin.tsx","../src/constants.ts"],"mappings":";;KAEY,QAAA;EACV,EAAA,EAAI,IAAA,CAAK,4BAAA;EACT,KAAA;AAAA;AAAA,KAGU,WAAA;AAAA,KAEA,WAAA;EACV,IAAA;EACA,IAAA,EAAM,WAAA;EACN,SAAA,EAAW,QAAA;EACX,KAAA;EACA,KAAA;EACA,MAAA;EACA,QAAA;EACA,UAAA,GAAa,IAAA,GAAO,IAAA;EACpB,KAAA;IAAA,CAAU,GAAA;IAAuB,OAAA;MAAA,CAAW,GAAA;IAAA;EAAA;AAAA;;;;KAMlC,KAAA;EACV,IAAA;EACA,KAAA;AAAA;AAAA,iBAGc,gCAAA,CACd,IAAA,WACC,IAAA,IAAQ,0BAAA;AAAA,KAIC,0BAAA;EACV,IAAA;EACA,KAAA,GAAQ,CAAA;EAvBR;;;EA2BA,KAAA;AAAA;AAAA,KAGU,gBAAA,IACV,MAAA,EAAQ,YAAA,EACR,aAAA,EAAe,MAAA,sBACZ,OAAA,CAAQ,QAAA;AAAA,KAED,eAAA;AAAA,KAEA,YAAA;EAjCuB;;;;EAsCjC,UAAA;EAhCe;;;;AAKjB;;;;;;;;EAwCE,MAAA,GAAS,MAAA;EAlCC;;;;;;;;;;;AASZ;;;;;;;;;;;;;;;;EAqDE,SAAA,EAAW,QAAA,KAAa,gBAAA;EAhDd;;;;;AAEZ;;;EAuDE,gBAAA;EATW;;;;;;;;;;;;;;;;;;;;;;;EAkCX,UAAA,YAAsB,kBAAA,GAAqB,eAAA;EC3FhC;;;;EDgGX,eAAA;;AE3HF;;;EFgIE,YAAA;EEhIiC;;ACLnC;;EH0IE,eAAA,GAAkB,eAAA;AAAA;AAAA,cC1GP,KAAA;AAAA,cC3BA,sBAAA,EAAsB,OAAA,CAAA,MAAA,CAAA,YAAA;;;AFXnC;;;;cGMa,mBAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/cache.ts","../src/constants.ts","../src/plugin.tsx","../src/utils/internationalizedArrayLanguageFilter.ts"],"mappings":";;;KAEY,QAAA;EACV,EAAA,EAAI,IAAA,CAAK,4BAAA;EACT,KAAA;AAAA;AAAA,KAGU,WAAA;AAAA,KAEA,WAAA;EACV,IAAA;EACA,IAAA,EAAM,WAAA;EACN,SAAA,EAAW,QAAA;EACX,KAAA;EACA,KAAA;EACA,MAAA;EACA,QAAA;EACA,UAAA,GAAa,IAAA,GAAO,IAAA;EACpB,KAAA;IAAA,CAAU,GAAA;IAAuB,OAAA;MAAA,CAAW,GAAA;IAAA;EAAA;AAAA;;;;KAMlC,KAAA;EACV,IAAA,UARwB;EAUxB,QAAA;EACA,KAAA;AAAA;AAAA,iBAGc,gCAAA,CACd,IAAA,WACC,IAAA,IAAQ,0BAAA;AAAA,KAIC,0BAAA;EACV,IAAA;EACA,KAAA,GAAQ,CAAA,EAxBR;EA0BA,QAAA;EAxBA;;;EA4BA,KAAA;AAAA;AAAA,KAGU,gBAAA,IACV,MAAA,EAAQ,YAAA,EACR,aAAA,EAAe,MAAA,sBACZ,OAAA,CAAQ,QAAA;AAAA,KAED,eAAA;AAAA,KAEA,YAAA;EArC6C;AAMzD;;;EAoCE,UAAA;EAnCA;;;;;AAMF;;;;;;;EA0CE,MAAA,GAAS,MAAA;EAxC0B;AAIrC;;;;;;;;;;;;AAWA;;;;;;;;;;;;;;EAqDE,SAAA,EAAW,QAAA,KAAa,gBAAA;EAlDL;;AAErB;;;;;AAEA;EAuDE,gBAAA;;;;;;;;;;;;;;;;;;;;;;;;EAyBA,UAAA,YAAsB,kBAAA,GAAqB,eAAA;EA2BzC;;;;EAtBF,eAAA;EClGD;;;;EDuGC,YAAA;EExHW;;;;EF6HX,eAAA,GAAkB,eAAA;;AGvIpB;;;;;;ACPA;;;EJyJE,cAAA;IACE,aAAA;EAAA;AAAA;AAAA,cC1HS,KAAA;;;;ADtCb;;;;;;;;;;AAKA;;;;;AAEA;;;;;cEgBa,mBAAA;AAAA,cCVA,sBAAA,EAAsB,OAAA,CAAA,MAAA,CAAA,YAAA;;;;AHbnC;cIMa,oCAAA,EAAsC,mBAAA"}