feat!(i18n-array): Move language identifier from _key to dedicated language field

[pedrobonamin]

Description

fixes #528
fixes #571

New major versions for @sanity/document-internationalization and **sanity-internationalized-array**

This PR migrates both sanity-plugin-internationalized-array and @sanity/document-internationalization to store the language identifier in a dedicated language field instead of using _key for this purpose.

When a field has outdated data a warning banner will render to alert users.

Why

Sanity uses _key internally for array item identity, diffing, and reordering. Storing the language ID there caused issues with:

• Array reordering and diffing in the Studio
• Portable Text operations that rely on stable keys
• Copy/paste operations between documents where keys could collide

Data format change

Before (v4):

{"_key": "en", "_type": "internationalizedArrayStringValue", "value": "hello"}

After (v5):

{"_key": "abc123", "_type": "internationalizedArrayStringValue", "language": "en", "value": "hello"}

How to upgrade

1. Update GROQ queries from _key == "en" to language == "en" || _key == "en" until the migration is completed.

2. Run the new bundled migration helper to update existing documents. Create a migration file in your project that imports from sanity-plugin-internationalized-array/migrations, configures your documentTypes, and exports the migration:

   // ./migrations/migrateToLanguageField.ts
   import {migrateToLanguageField} from 'sanity-plugin-internationalized-array/migrations'
   export default migrateToLanguageField(['yourType'])
   

   npx sanity migration run migrateToLanguageField
   

   Verify everything looks as expected

   npx sanity migration run migrateToLanguageField  --dry-run=false
   

3. Update any custom code that reads _key as the language identifier to use the language field instead.

4. Remove _key == "en" from your queries once migration is complete, since language is now stored in language.

We have also added a SKILL to guide your AI agents helping you to migrate your queries and usage of the _key identifier to a language.
See the skill here

What to review

Testing

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
plugins-studio	Ready	Preview, Comment	Feb 19, 2026 10:30am

[changeset-bot]

🦋 Changeset detected

Latest commit: 9daaaad

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@sanity/document-internationalization	Major
sanity-plugin-internationalized-array	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​sanity/​util@​5.8.1 ⏵ 5.10.0	+1
	npm/​groq@​5.6.0 ⏵ 5.9.0
	npm/​@​sanity/​language-filter@​4.0.6 ⏵ 4.1.0	+8		+1	+2
	npm/​@​sanity/​vision@​5.9.0 ⏵ 5.10.0
	npm/​sanity@​5.8.1 ⏵ 5.10.0	+1
	npm/​@​sanity/​client@​7.14.1 ⏵ 7.15.0	+1			+3

View full report

[github-actions]

Preview this PR with pkg.pr.new

Using pnpm

📦 sanity-plugin-internationalized-array

pnpm install https://pkg.pr.new/sanity-io/plugins/sanity-plugin-internationalized-array@9daaaade093d295f9eb42ec07138b7276c637b6c

📦 @sanity/document-internationalization

pnpm install https://pkg.pr.new/sanity-io/plugins/@sanity/document-internationalization@9daaaade093d295f9eb42ec07138b7276c637b6c

Using npm

📦 sanity-plugin-internationalized-array

npm install https://pkg.pr.new/sanity-io/plugins/sanity-plugin-internationalized-array@9daaaade093d295f9eb42ec07138b7276c637b6c

📦 @sanity/document-internationalization

npm install https://pkg.pr.new/sanity-io/plugins/@sanity/document-internationalization@9daaaade093d295f9eb42ec07138b7276c637b6c

View Commit (9daaaad)