@sanity/document-internationalization 2.0.0-studio-v3-plugin-v2.13 → 2.0.0-studio-v3-plugin-v2.14

package/README.md

@@ -1,62 +1,59 @@
 # @sanity/document-internationalization
 
+All new rewrite exclusively for Sanity Studio v3!
+
 - [@sanity/document-internationalization](#sanitydocument-internationalization)
-  - [Upgrading](#upgrading)
+  - [What this plugin solves](#what-this-plugin-solves)
+    - [Many projects use both!](#many-projects-use-both)
+  - [Upgrade](#upgrade)
   - [Install](#install)
   - [Usage](#usage)
     - [Basic configuration](#basic-configuration)
     - [Advanced configuration](#advanced-configuration)
     - [Language field](#language-field)
-  - [Importing plugin components](#importing-plugin-components)
-    - [useDocumentInternationalizationContext](#usedocumentinternationalizationcontext)
-    - [DocumentInternationalizationMenu](#documentinternationalizationmenu)
-  - [Code examples](#code-examples)
+  - [Querying translations](#querying-translations)
     - [Querying with GROQ](#querying-with-groq)
     - [Querying with GraphQL](#querying-with-graphql)
-    - [Allowing the same slug on different language versions](#allowing-the-same-slug-on-different-language-versions)
-  - [Deleting documents](#deleting-documents)
-    - [Deleting a single translated document](#deleting-a-single-translated-document)
-    - [Deleting all translations](#deleting-all-translations)
   - [Note on document quotas](#note-on-document-quotas)
+  - [Documentation](#documentation)
   - [License](#license)
   - [Develop \& test](#develop--test)
     - [Release new version](#release-new-version)
 
-This is the all-new, **Sanity Studio v3 exclusive version** of @sanity/document-internationalization released as v2.0.0
+![v3 Studio with @sanity/document-internationalization v1 Installed](./docs/img/sanity-document-internationalization-v2.png)
 
-![v3 Studio with @sanity/document-internationalization v1 Installed](/img/sanity-document-internationalization-v2.png)
+## What this plugin solves
 
-A complete rewrite of the original Document Internationalization plugin, exclusively for Sanity Studio v3. Major **benefits** from the previous versions include:
+There are two popular methods of internationalization in Sanity Studio:
 
-- 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
+- **Document-level translation**
+  - A unique document version for every language
+  - Joined together by references in a `translation.metadata` document
+  - Best for documents that have unique, language-specific fields and no common content across languages
+  - Best for translating content using Portable Text
+- **Field-level translation**
+  - A single document with many languages of content
+  - Achieved by mapping over languages on each field
+  - Best for documents that have a mix of language-specific and common fields
+  - Not recommended for Portable Text
 
-## Upgrading
+This plugin adds features to the Studio to improve handling **document-level translations**.
 
-If this is your first time installing Document Internationalization, skip to the [Install](#install) section.
+- A Language Selector to create and browse language-specific versions of a Document
+- Hooks and components to use throughout your custom components to handle translations
+- Document Badges to highlight the language version of a document
 
-**I'm on Sanity Studio v3 and upgrading from plugin v1.0.0 and above**
+For **field-level translations** you should use the [sanity-plugin-internationalized-array](https://github.com/sanity-io/sanity-plugin-internationalized-array).
 
-- You will need to perform a content migration to upgrade. [See the plugin upgrade documentation](./docs/00-upgrade-from-v1.md)
-- Your queries will also need to change, as translation references have moved. See the [Querying](#querying-with-groq) and [Querying with GraphQL](#querying-with-graphql) sections below. [GraphQL](#)
+### Many projects use both!
 
-**I'm on Sanity Studio v3 but will stay with the older plugin for now**
+An example of **document-level** translation could be a `lesson` schema, the `title`, `slug` and `content` fields would be unique in every language.
 
-- Please refer to the [v2 branch](https://github.com/sanity-io/document-internationalization/tree/studio-v2)
-- Install from `v1.0.0` and above
-- This version of the plugin will not be updated with new features
+A good use of **field-level** translation could be a `person` schema. It could have the same `name` and `image` in every language, but only the `biography` would need translating.
 
-**I'm on Sanity Studio v2**
+## Upgrade
 
-- 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.
+See the Upgrade Guide for [v1](./docs/00-upgrade-from-v1.md) for instructions on how to upgrade from the original Document Internationalization plugin.
 
 ## Install
 
@@ -64,19 +61,16 @@ If this is your first time installing Document Internationalization, skip to the
 npm install --save @sanity/document-internationalization@studio-v3-plugin-v2
 ```
 
-or
-
-```
-yarn add @sanity/document-internationalization@studio-v3-plugin-v2
-```
-
 ## Usage
 
 Add it as a plugin in `sanity.config.ts` (or .js):
 
 ### Basic configuration
 
-The only required configuration is the `supportedLanguages` array and the `schemaTypes` array.
+The only required configuration is:
+
+- The `supportedLanguages` array and
+- The `schemaTypes` array
 
 ```ts
 // sanity.config.ts
@@ -135,7 +129,7 @@ export const createConfig({
       languageField: `language` // defauts to "language"
 
       // Optional
-      // Keep translations.metadata references weak
+      // Keep translation.metadata references weak
       weakReferences: true // defaults to false
 
       // Optional
@@ -160,7 +154,7 @@ export const createConfig({
 
 ### Language field
 
-The schema types that use document internationalization must also have a `string` field type with the same name configured in the `languageField` setting. Unless you want content creators to be able to change the language of a document, you may hide this field since the plugin will handle writing patches to it.
+The schema types that use document internationalization must also have a `string` field type with the same name configured in the `languageField` setting. Unless you want content creators to be able to change the language of a document, you may hide or disable this field since the plugin will handle writing patches to it.
 
 ```ts
 // ./schema/lesson.ts
@@ -175,44 +169,7 @@ defineField({
 })
 ```
 
-## Importing plugin components
-
-Some components and functions from the plugin are exported for you to use throughout the Studio. For example, a custom Tool that lists documents but also needs to pull from available languages, create new translations, show the language of an existing document and link to the metadata document.
-
-![custom-tool](https://github.com/sanity-io/document-internationalization/assets/9684022/66c1cd3d-a964-4632-b57c-998a49a2c9b6)
-
-### useDocumentInternationalizationContext
-
-The `useDocumentInternationalizationContext` hook can be used to access all plugin configuration values, including the result of `supportedLanguages` if it is an async function.
-
-```tsx
-import {useDocumentInternationalizationContext} from '@sanity/document-internationalization'
-
-export function MyComponent({doc}: {doc: SanityDocument}) {
-  const {languageField} = useDocumentInternationalizationContext()
-
-  return <Badge>{doc[languageField] ?? `No Language`}</Badge>
-}
-```
-
-### DocumentInternationalizationMenu
-
-The menu button shown at the top of documents can be imported anywhere and requires the published document ID of a document and its schema type to set the language of the document and handle creating new translations and the metadata document.
-
-```tsx
-import {DocumentInternationalizationMenu} from '@sanity/document-internationalization'
-
-export function MyComponent({_id, _type}) {
-  return (
-    <DocumentInternationalizationMenu
-      documentId={_id.replace(`drafts.`, ``)}
-      schemaType={_type}
-    />
-  )
-}
-```
-
-## Code examples
+## Querying translations
 
 ### Querying with GROQ
 
@@ -221,12 +178,11 @@ To query a single document and all its translations, we use the `references()` f
 ```json5
 // All `lesson` documents of a single language
 *[_type == "lesson" && language == $language]{
-  // Just these fields
   title,
   slug,
   language,
   // Get the translations metadata
-  // And resolve the `value` field in each array item
+  // And resolve the `value` reference field in each array item
   "_translations": *[_type == "translation.metadata" && references(^._id)].translations[].value->{
     title,
     slug,
@@ -271,86 +227,6 @@ query GetTranslations($id: ID!) {
 }
 ```
 
-### Allowing the same slug on different language versions
-
-Often your translated documents will share the same slug. You might wish to move this into the metadata document itself using the `metadataFields` option in the plugin. Alternatively, you can customize the `isUnique` function on a [slug type field](https://www.sanity.io/docs/slug-type#isUnique-**3dd89e75a768**).
-
-```ts
-// Add the isUnique option to your slug field
-defineField({
-  name: 'slug',
-  type: 'slug',
-  options: {
-    isUnique: isUniqueOtherThanLanguage
-  },
-}),
-
-// Create the function
-// This checks that there are no other documents
-// With this published or draft _id
-// Or this schema type
-// With the same slug and language
-export async function isUniqueOtherThanLanguage(slug: string, context: SlugValidationContext) {
-  const {document, getClient} = context
-  if (!document?.language) {
-    return true
-  }
-  const client = getClient({apiVersion: '2023-04-24'})
-  const id = document._id.replace(/^drafts\./, '')
-  const params = {
-    draft: `drafts.${id}`,
-    published: id,
-    language: document.language,
-    slug,
-  }
-  const query = `!defined(*[
-    !(_id in [$draft, $published]) &&
-    slug.current == $slug &&
-    language == $language
-  ][0]._id)`
-  const result = await client.fetch(query, params)
-  return result
-}
-```
-
-## Deleting documents
-
-### Deleting a single translated document
-
-By default, this plugin creates a strong reference between a document and its connected translation metadata document. Because reference integrity is maintained by the API, you cannot delete a document that has a strong reference to it. To offset this difficulty, the plugin exports a document action that will allow you to remove the translation reference from the action, before proceeding to delete the document. It is not added by default to your schema types.
-
-![delete translation document action](https://github.com/sanity-io/document-internationalization/assets/9684022/edccb456-f6e1-4782-9602-b279e9689357)
-
-Import into your Studio's config file
-
-```ts
-import {
-  documentInternationalization,
-  DeleteTranslationAction,
-} from '@sanity/document-internationalization'
-
-export default defineConfig({
-  // ...all other config
-  document: {
-    actions: (prev, {schemaType}) => {
-      // Add to the same schema types you use for internationalization
-      if (['page'].includes(schemaType)) {
-        // You might also like to filter out the built-in "delete" action
-        return [...prev, DeleteTranslationAction]
-      }
-
-      return prev
-    },
-  },
-})
-```
-
-### Deleting all translations
-
-The metadata document also contains a "Delete all translations" document action which is queued by default for only that schema type. It will delete all of the documents in the `translations` array of references, as well as the metadata document itself.
-
-![delete all translations document action](https://github.com/sanity-io/document-internationalization/assets/9684022/fda956f1-26e7-430a-aeef-1db4166e9cd6)
-
 ## Note on document quotas
 
 In previous versions of this plugin, translations were stored as an array of references on the actual documents. This required a base language, lead to messy transaction histories and made deleting documents difficult.
@@ -359,6 +235,17 @@ In this version of the plugin, translations of a document are stored as an array
 
 This means if you have 100 documents and they are all translated into 3 languages, you will have 400 documents. Keep this in mind for extremely high-volume datasets.
 
+## Documentation
+
+For more advanced topics see the documentation. For installation see [Usage](#usage).
+
+- [Upgrade from v1](./docs/00-upgrade-from-v1.md)
+- [Creating translations of singleton documents](./docs/01-singleton-documents.md)
+- [Importing and creating documents](./docs/02-importing-and-creating-documents.md)
+- [Deleting translated documents](./docs/03-deleting-translated-documents.md)
+- [Importing plugin components](./docs/04-importing-plugin-components.md)
+- [Allowing the same slug on different language versions](./docs/05-allowing-the-same-slug-on-different-language-versions.md)
+
 ## License
 
 [MIT](LICENSE) © Sanity.io

package/lib/index.esm.js

@@ -364,12 +364,27 @@ function LanguageManage(props) {
     id
   } = props;
   const open = useOpenInNewPane(id, METADATA_SCHEMA_NAME);
-  return /* @__PURE__ */jsx(Button, {
-    disabled: !id,
-    mode: "ghost",
-    text: "Manage Translations",
-    icon: CogIcon,
-    onClick: () => open()
+  return /* @__PURE__ */jsx(Tooltip, {
+    content: id ? null : /* @__PURE__ */jsx(Box, {
+      padding: 2,
+      children: /* @__PURE__ */jsx(Text, {
+        muted: true,
+        size: 1,
+        children: "Document has no other translations"
+      })
+    }),
+    fallbackPlacements: ["right", "left"],
+    placement: "top",
+    portal: true,
+    children: /* @__PURE__ */jsx(Stack, {
+      children: /* @__PURE__ */jsx(Button, {
+        disabled: !id,
+        mode: "ghost",
+        text: "Manage Translations",
+        icon: CogIcon,
+        onClick: () => open()
+      })
+    })
   });
 }
 function createReference(key, ref, type) {
@@ -635,15 +650,15 @@ function DocumentInternationalizationMenu(props) {
     }
     return valid;
   }, [supportedLanguages]);
-  const content = /* @__PURE__ */jsx(Card, {
+  const content = /* @__PURE__ */jsx(Box, {
+    padding: 1,
     children: error ? /* @__PURE__ */jsx(Card, {
       tone: "critical",
-      padding: 2,
+      padding: 1,
       children: /* @__PURE__ */jsx(Text, {
         children: "There was an error returning translations metadata"
       })
     }) : /* @__PURE__ */jsxs(Stack, {
-      padding: 1,
       space: 1,
       children: [/* @__PURE__ */jsx(LanguageManage, {
         id: metadata == null ? void 0 : metadata._id