chore(i18n): add docs and scripts folders, update readme links

[pedrobonamin]

Description

Add docs and scripts folders, update readme links

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	May 4, 2026 10:18am

[changeset-bot]

⚠️ No Changeset found

Latest commit: 52a7e12

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[Copilot]

Pull request overview

This PR adds in-repo migration scripts and advanced documentation for @sanity/document-internationalization, while updating README links so the plugin’s guidance lives alongside the code in the monorepo.

Changes:

• Add reusable migration/setup scripts for upgrading metadata, renaming the language field, and creating translated singleton documents.
• Add a new docs/ section covering upgrade paths, singleton patterns, importing, deletion, custom component usage, slug behavior, template filtering, and duplication.
• Update README documentation links to point at the new in-repo docs location.

Reviewed changes

Copilot reviewed 12 out of 17 changed files in this pull request and generated 18 comments.

Show a summary per file

File	Description
plugins/@sanity/document-internationalization/scripts/renameLanguageField.ts	Adds a CLI migration script for renaming the legacy language field.
plugins/@sanity/document-internationalization/scripts/createSingletons.ts	Adds a helper script for creating translated singleton documents and metadata.
plugins/@sanity/document-internationalization/scripts/createMetadata.ts	Adds a migration script to create translation.metadata documents from v1-style refs.
plugins/@sanity/document-internationalization/docs/img/singletons-list.png	Screenshot for singleton-document docs.
plugins/@sanity/document-internationalization/docs/img/new-document-filtered.png	Screenshot for filtered new-document template docs.
plugins/@sanity/document-internationalization/docs/img/new-document-default.png	Screenshot for default new-document template docs.
plugins/@sanity/document-internationalization/docs/img/duplicate-document-action.png	Screenshot for duplicate-with-translations docs.
plugins/@sanity/document-internationalization/docs/07-duplicating-translated-documents.md	Documents duplicating translated documents.
plugins/@sanity/document-internationalization/docs/06-remove-default-new-document-template.md	Documents how to filter out the default template entry.
plugins/@sanity/document-internationalization/docs/05-allowing-the-same-slug-for-translations.md	Documents slug uniqueness behavior for translated docs.
plugins/@sanity/document-internationalization/docs/04-importing-plugin-components.md	Documents exported hooks/components for custom Studio integrations.
plugins/@sanity/document-internationalization/docs/03-deleting-translated-documents.md	Documents deletion flows for translated docs and metadata.
plugins/@sanity/document-internationalization/docs/02-importing-and-creating-documents.md	Documents the expected document shape and an import script example.
plugins/@sanity/document-internationalization/docs/01-singleton-documents.md	Documents the singleton translation pattern and desk structure example.
plugins/@sanity/document-internationalization/docs/00-upgrade-from-v1.md	Adds a migration guide from the legacy v1 plugin.
plugins/@sanity/document-internationalization/README.md	Updates README links to point at the new docs/scripts in this repo.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[pedrobonamin]

@copilot apply changes based on the comments in this thread

[Copilot]

@copilot apply changes based on the comments in this thread

All review feedback has been applied in commit a513c90:

• Scripts (createSingletons.ts, createMetadata.ts): translation items in metadata now include the required language field and _type: 'internationalizedArrayReferenceValue' matching the v6 plugin schema. The two separate transactions in createMetadata.ts are merged into one atomic transaction to prevent orphaned metadata documents if a patch fails. Fixed Langage typo.
• Docs links: All old github.com/sanity-io/document-internationalization links replaced with relative in-repo paths.
• Metadata examples (00-upgrade-from-v1.md, 02-importing-and-creating-documents.md): updated to show the correct v6 shape with language field and _type.
• 01-singleton-documents.md: hardcoded .schemaType('page') replaced with .schemaType(singleton._type).
• 02-importing-and-creating-documents.md: fixed missing comma after _type in JSON and after translations.map() in TypeScript.
• 03-deleting-translated-documents.md: replaced deprecated DeleteTranslationAction with useDeleteTranslationAction.
• 04-importing-plugin-components.md: DocumentInternationalizationMenu example now uses useSchema() to pass the full schema type object instead of a plain string.
• 05-allowing-the-same-slug-for-translations.md: added _type == $type filter to the GROQ query.
• 07-duplicating-translated-documents.md: replaced deprecated DuplicateWithTranslationsAction with useDuplicateWithTranslationsAction and defined translatedSchemaTypes to fix the undefined reference.
• README.md: added the missing link to 07-duplicating-translated-documents.md.

[pedrobonamin]

@copilot in the examples we are still using _key: en or _key: <language> replace those for random values so we guide people against using key to store the langauge, check all the examples added in this pr

[Copilot]

@copilot in the examples we are still using _key: en or _key: <language> replace those for random values so we guide people against using key to store the langauge, check all the examples added in...

Done in commit 4aa57cf. All _key values that were set to a language code are now replaced with random values:

• createMetadata.ts and createSingletons.ts: import randomKey from @sanity/util/content and use randomKey(12) for translation item _keys. The destructured _key from old v1 refs (which stored the language as _key) is renamed to legacyKey to clarify it's only being read as the language value, not reused as the new _key.
• 00-upgrade-from-v1.md and 02-importing-and-creating-documents.md: JSON examples now show realistic random strings (e.g. "kjjNvZHK8Y2QpTEf3K5jc") instead of "en" / "no" for _key.
• 02-importing-and-creating-documents.md TypeScript example: imports randomKey and uses randomKey(12) instead of doc.language for _key.

[bjoerge]

Thanks @pedrobonamin !

[Copilot]

Pull request overview

Copilot reviewed 12 out of 17 changed files in this pull request and generated 8 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[pedrobonamin]

@copilot lint is failing https://github.com/sanity-io/plugins/actions/runs/25310569446/job/74196220899?pr=866, fix

[Copilot]

@copilot lint is failing https://github.com/sanity-io/plugins/actions/runs/25310569446/job/74196220899?pr=866, fix

Fixed in commit 042b5e2. All 18 lint errors addressed:

• createMetadata.ts: import type for Reference/SanityDocumentLike; removed unused createTransaction/commitTransaction helpers (logic was already inlined); inlined tx.commit() call
• renameLanguageField.ts: import type for SanityDocumentLike; removed createTransaction/commitTransaction helpers with implicit any params; inlined the transaction reduce + commit
• createSingletons.ts: flatMap instead of .map().flat(); direct await instead of .then(); void createSingletons().catch(...) at the call site; typed flatMap<{_id: string; _type: string; [key: string]: unknown}> to fix the createOrReplace argument type error

[pedrobonamin]

@copilot lint keeps failing

[Copilot]

@copilot lint keeps failing

Fixed in commit af39fbb. Two remaining issues addressed:

1. Spread in map (1 error): Refactored buildMetadata in createMetadata.ts to use block-body map callbacks with if-statements for conditional _weak assignment and .concat() instead of spread for building the translations array — avoiding all spread operations inside .map() callbacks.

2. Unused eslint-disable directives (3 warnings treated as errors with --deny-warnings): The no-process-exit rule is in the restriction category which is not enabled in .oxlintrc.json (only correctness, suspicious, perf are active). Removed the // eslint-disable-next-line no-process-exit comments from all three scripts.