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

Author: pedrobonamin

plugins/@sanity/document-internationalization/README.md

@@ -55,31 +55,31 @@ This plugin uses [sanity-plugin-internationalized-array](https://github.com/sani
 
 **Important:** When configuring the migration, include `'translation.metadata'` in the document types so that your translation metadata documents are migrated:
 
-### 1. Backup your data.
+### 1. Backup your data
 
 You can manually backup your data using the sanity CLI.
 
-```
+```bash
 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:
 
-```
+```bash
 sanity dataset export production ./backups/backup-2026-02-16.tar.gz
 ```
 
 If you ever need to restore, use the import command:
 
-```
+```bash
 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
+Or you can use the backup service, read more in the [Content Lake backups documentation](https://www.sanity.io/docs/content-lake/backups).
 
-### 2. Update your GROQ queries.
+### 2. Update your GROQ queries
 
 Use a backwards compatible query until your migration is ready and has been executed.
 
@@ -128,14 +128,7 @@ Previously we updated the GROQ queries to support both locations for the languag
 
 ## Upgrade from V1
 
-If upgrading from a previous version (v1), please see the [upgrade documentation](https://github.com/sanity-io/document-internationalization/blob/main/docs/00-upgrade-from-v1.md) in the original repository.
-And change `_key: doc[LANGUAGE_FIELD]` to `language: doc[LANGUAGE_FIELD]` in https://github.com/sanity-io/document-internationalization/blob/main/scripts/createMetadata.ts#L80
-
-```diff
-// https://github.com/sanity-io/document-internationalization/blob/main/scripts/createMetadata.ts#L80
--  _key: doc[LANGUAGE_FIELD]
-+  language: doc[LANGUAGE_FIELD]
-```
+If upgrading from a previous version (v1), please see the [upgrade documentation](https://github.com/sanity-io/plugins/blob/main/plugins/%40sanity/document-internationalization/docs/00-upgrade-from-v1.md) in this repository.
 
 ## Install
 
@@ -392,15 +385,16 @@ This means if you have 100 documents and they are all translated into 3 language
 
 ## Documentation
 
-For more advanced topics see the [original repository documentation](https://github.com/sanity-io/document-internationalization/tree/main/docs).
+For more advanced topics see the [repository documentation](https://github.com/sanity-io/plugins/tree/main/plugins/%40sanity/document-internationalization/docs).
 
-- [Upgrade from v1](https://github.com/sanity-io/document-internationalization/blob/main/docs/00-upgrade-from-v1.md)
-- [Creating translations of singleton documents](https://github.com/sanity-io/document-internationalization/blob/main/docs/01-singleton-documents.md)
-- [Importing and creating documents](https://github.com/sanity-io/document-internationalization/blob/main/docs/02-importing-and-creating-documents.md)
-- [Deleting translated documents](https://github.com/sanity-io/document-internationalization/blob/main/docs/03-deleting-translated-documents.md)
-- [Importing plugin components](https://github.com/sanity-io/document-internationalization/blob/main/docs/04-importing-plugin-components.md)
-- [Allowing the same slug on different language versions](https://github.com/sanity-io/document-internationalization/blob/main/docs/05-allowing-the-same-slug-for-translations.md)
-- [Remove default new document template](https://github.com/sanity-io/document-internationalization/blob/main/docs/06-remove-default-new-document-template.md)
+- [Upgrade from v1](https://github.com/sanity-io/plugins/blob/main/plugins/%40sanity/document-internationalization/docs/00-upgrade-from-v1.md)
+- [Creating translations of singleton documents](https://github.com/sanity-io/plugins/blob/main/plugins/%40sanity/document-internationalization/docs/01-singleton-documents.md)
+- [Importing and creating documents](https://github.com/sanity-io/plugins/blob/main/plugins/%40sanity/document-internationalization/docs/02-importing-and-creating-documents.md)
+- [Deleting translated documents](https://github.com/sanity-io/plugins/blob/main/plugins/%40sanity/document-internationalization/docs/03-deleting-translated-documents.md)
+- [Importing plugin components](https://github.com/sanity-io/plugins/blob/main/plugins/%40sanity/document-internationalization/docs/04-importing-plugin-components.md)
+- [Allowing the same slug on different language versions](https://github.com/sanity-io/plugins/blob/main/plugins/%40sanity/document-internationalization/docs/05-allowing-the-same-slug-for-translations.md)
+- [Remove default new document template](https://github.com/sanity-io/plugins/blob/main/plugins/%40sanity/document-internationalization/docs/06-remove-default-new-document-template.md)
+- [Duplicating translated documents](https://github.com/sanity-io/plugins/blob/main/plugins/%40sanity/document-internationalization/docs/07-duplicating-translated-documents.md)
 
 ## License
 

plugins/@sanity/document-internationalization/docs/00-upgrade-from-v1.md

@@ -0,0 +1,217 @@
+# Upgrading from v1 of @sanity/document-internationalization
+
+## Where you are now:
+
+**I'm on Sanity Studio v3 and upgrading from plugin v1.0.0 and above**
+
+- You will need to perform a content migration to upgrade. See ["Upgrading from v1 to v2"](#upgrading-from-v1-to-v2)
+- Your queries will also need to change, as translation references have moved. See ["Upgrading from v1 to v2"](#upgrading-from-v1-to-v2) below for migration guidance, including query updates.
+
+**I'm on Sanity Studio v3 but will stay with the older plugin for now**
+
+- Please refer to the [v1 branch](https://github.com/sanity-io/document-internationalization/tree/v1)
+- Install from `v1.0.0` and above
+- This version of the plugin will not be updated with new features
+
+**I'm on Sanity Studio v2**
+
+- Please refer to the [studio-v2 branch](https://github.com/sanity-io/document-internationalization/tree/studio-v2)
+- Install from `v0.0.0` and above
+- This version of the plugin will not be updated with new features
+- You will not need to perform a content migration to move to Sanity Studio v3, if you install the v1 plugin.
+
+### Upgrading from v1 to v2
+
+Upgrading from v1 to v2 of this plugin will require:
+
+1. Migrations of internationalized documents in your dataset
+2. Updates to your `sanity.config.ts` plugins array
+3. Updated queries in your front-end application(s)
+
+We have provided migration scripts and guidance on this page. Please submit an issue if anything is unclear.
+
+### How v2 is different from v1
+
+A complete rewrite of the original Document Internationalization plugin, exclusively for Sanity Studio v3. Major **benefits** from the previous versions include:
+
+- Create new documents in any language and link translated references later
+- Translation references are written to a separate "meta" document
+- Updates to one translation no longer affect the change history of others
+- Does not require custom - nor modify the built-in - [Document Actions](https://www.sanity.io/docs/document-actions)
+- Changes made to one translation do not patch changes to other documents
+- Configurable "language" field on documents
+- Built-in static and parameterized initial value templates for new documents
+
+## 1. Migrating content
+
+In this repository are two scripts to help migrate content. One is required, the other is not.
+
+### 1.1 Required: `createMetadata.ts`
+
+Please backup your dataset before running migration scripts.
+
+Instructions for how to perform this migration are written in the script itself: [scripts/createMetadata.ts](../scripts/createMetadata.ts)
+
+The [createMetadata.ts](../scripts/createMetadata.ts) script will look for all documents of a specific `_type` that contain the previous plugin's `__i18n_refs` array of references. Those arrays were written by the plugin and should look like this:
+
+```json
+"__i18n_refs": [
+  {
+    "_key": "en_GB",
+    "_ref": "32cb7277-1cfb-4ab1-ae1e-ab844dc8ab72__i18n_en_GB",
+    "_type": "reference",
+  },
+  {
+    "_key": "no",
+    "_ref": "32cb7277-1cfb-4ab1-ae1e-ab844dc8ab72__i18n_nl",
+    "_type": "reference",
+  },
+],
+```
+
+The script will create a new `translation.metadata` document which contains the `__i18n_refs` array of references in a field named `translations`.
+
+(This is the new way to query for translations of a document – to find the `translation.metadata` document that references it, and then look through the `translations` array.)
+
+The benefits of this method include no longer needing document actions to write changes to content documents – and being able to start documents in any language and attach translations.
+
+The resultant document looks like this:
+
+```json
+{
+  "_id": "b4ed5f0b-8e01-44b7-ac4c-09f2fb233b26",
+  "_type": "translation.metadata",
+  "translations": [
+    {
+      "_key": "kjjNvZHK8Y2QpTEf3K5jc",
+      "_type": "internationalizedArrayReferenceValue",
+      "language": "en",
+      "value": {
+        "_ref": "32cb7277-1cfb-4ab1-ae1e-ab844dc8ab72__i18n_en_GB",
+        "_type": "reference"
+      }
+    },
+    {
+      "_key": "9Hw3I5BNXZ72mCfJW6Pq1",
+      "_type": "internationalizedArrayReferenceValue",
+      "language": "no",
+      "value": {
+        "_ref": "32cb7277-1cfb-4ab1-ae1e-ab844dc8ab72__i18n_nl",
+        "_type": "reference"
+      }
+    }
+  ]
+}
+```
+
+The previous `__i18n_refs` and `__i18n_base` fields will be removed from the document.
+
+Make sure to configure the new plugin with your existing `languageField` setting, or run the script below to rewrite the name of that field.
+
+### 1.2 Optional: `renameLanguageField.ts`
+
+Please backup your dataset before running migration scripts.
+
+Instructions for how to perform this migration are written in the script itself: [scripts/renameLanguageField.ts](../scripts/renameLanguageField.ts)
+
+The previous plugin by default would write fields with double underscore prefixes (example: `__lang`) which did not work with GraphQL deployments.
+
+For data hygiene, you may prefer to have a normalized field name for the language field in your translated documents. The default field name for a document's language in the new plugin is `language`.
+
+[This script will update the field name](../scripts/renameLanguageField.ts) `__i18n_lang` to `language` or can be customized to use the field name you used in the previous version of the plugin.
+
+## 2. Updating `sanity.config.ts`
+
+### 2.1 Install the new version of the plugin
+
+```sh
+npm install @sanity/document-internationalization@latest
+```
+
+### 2.2 Update your plugins array
+
+The previous version of the plugin recommended you wrap your plugins array and modify your desk structure using the `withDocumentI18nPlugin()` function. This is no longer required.
+
+Update your plugins array to load the plugin like you would any other. For configuration options see the [plugin README](../README.md).:
+
+>
+
+```ts
+// ./sanity.config.ts
+
+import {createSchema} from '@sanity/schema'
+import {documentInternationalization} from '@sanity/document-internationalization'
+// ...all other imports
+
+export default defineConfig({
+  // ... all other settings
+  plugins: [
+    // ... all other plugins
+    // Remove `withDocumentI18nPlugin` wrapper function
+    deskTool(),
+    documentInternationalization({
+      // See the README and notes below for configuration options
+    }),
+  ],
+})
+```
+
+Your existing plugin configuration might look something like this. See comments below for which field names require updates and which are no longer necessary or relevant.
+
+```js
+// Old plugin configuration
+
+documentI18n({
+  // Change to `supportedLanguages`
+  "languages": [
+    { "title": "English (US)", "id": "en-us" },
+    { "title": "Dutch (NL)", "id": "nl-nl" }
+  ],
+  // Change to `weakReferences`, example:
+  // weakReferences: true | false (default false)
+  "referenceBehavior": "strong",
+  // Change to `languageField`, example:
+  // languageField: 'language' (default 'language')
+  "fieldNames": {
+    "lang": "__i18n_lang",
+    "references": "__i18n_refs",
+    "baseReference": "__i18n_base"
+  }
+  // Remove: There is no enforced "base language" in this new version
+  "base": "en-us",
+  // Remove: Deterministic _id strings are no longer supported
+  // as documents could be created in any language first
+  // and querying by _id strings is unreliable and slow
+  "idStructure": "delimiter",
+  // Remove: No longer necessary
+  "withTranslationsMaintenance": false,
+})
+```
+
+The new config would look like this:
+
+```js
+// New plugin configuration
+
+documentInternationalization({
+  // Required:
+  supportedLanguages: [
+    {title: 'English (US)', id: 'en-us'},
+    {title: 'Dutch (NL)', id: 'nl-nl'},
+  ],
+  schemaTypes: ['page'],
+  // Optional:
+  weakReferences: false, // default false
+  languageField: 'language', // default "language"
+})
+```
+
+### 2.3 Cleanup schema
+
+You can now remove the `i18n` key from all document schemas, as the schema types the plugin is enabled on are now configured in the plugin function.
+
+## 3. Updating queries
+
+The previous version of the plugin wrote language details to document `_id`s. This behavior was changed in a previous version of the plugin. Matching against the string `_id` of a document is an unreliable and slow way to query for documents.
+
+See the [GROQ examples in the README](../README.md#querying-with-groq) and [GraphQL examples in the README](../README.md#querying-with-graphql) for how to query for translations.

plugins/@sanity/document-internationalization/docs/01-singleton-documents.md

@@ -0,0 +1,66 @@
+# Creating translations of singleton documents
+
+![Singleton documents](./img/singletons-list.png)
+
+Singleton documents in Sanity are usually created with the [Structure Builder](https://www.sanity.io/docs/structure-builder-reference) by creating a `S.documentListItem()` with a predetermined ID.
+
+This isn't enough when it comes to translated documents as you need to create an ID for each document and bind them together with a translations metadata document.
+
+For translated singletons you will need to:
+
+1. Run a script to create the documents in advance
+2. Update your Desk Structure to use a list of documents that know these created IDs
+
+## 1. Create the documents
+
+Instructions for how to perform this migration are written in the script itself: [scripts/createSingletons.ts](../scripts/createSingletons.ts)
+
+This script will create a document for each singleton you need, and a translations document that will be used to bind them together.
+
+If you add more languages later you may need to adapt this script to check first for the existence of the translations metadata document and append the new translations to it.
+
+## 2. Update your Desk Structure
+
+At this time it's not possible to re-use the `supportedLanguages` array passed into the plugin configuration for this step, so this will not work for languages called from an async function.
+
+In the example below, we re-use the same arrays of SINGLETONS and LANGUAGES as the creation script to render a new list for every "singleton" and a new item inside it for every "language" version.
+
+This will render list items as shown in the screenshot above.
+
+```ts
+const SINGLETONS = [
+  {id: 'home', _type: 'page', title: 'Home'},
+  {id: 'login', _type: 'page', title: 'Login'},
+]
+const LANGUAGES = [
+  {id: `en`, title: `English`},
+  {id: `fr`, title: `French`},
+]
+
+export const structure: StructureResolver = (S) =>
+  S.list()
+    .title('Content')
+    .items([
+      ...SINGLETONS.map((singleton) =>
+        S.listItem()
+          .title(singleton.title)
+          .id(singleton.id)
+          .child(
+            S.list()
+              .title(singleton.title)
+              .id(singleton.id)
+              .items(
+                LANGUAGES.map((language) =>
+                  S.documentListItem()
+                    .schemaType(singleton._type)
+                    .id(`${singleton.id}-${language.id}`)
+                    .title(`${singleton.title} (${language.id.toLocaleUpperCase()})`)
+                )
+              )
+              .canHandleIntent(
+                (intentName, params) => intentName === 'edit' && params.id.startsWith(singleton.id)
+              )
+          )
+      ),
+      // ...other list items
+```