@sanity/assist 1.2.13 → 1.2.15-lang.1

package/src/translate/paths.test.ts

@@ -0,0 +1,87 @@
+import {describe, expect, test} from 'vitest'
+import {Schema} from '@sanity/schema'
+import {defineType, ObjectSchemaType, pathToString, SanityDocumentLike, typed} from 'sanity'
+import {
+  defaultLanguageOutputs,
+  getDocumentMembersFlat,
+  getTranslationMap,
+  TranslationMap,
+} from './paths'
+
+describe('paths', () => {
+  test('should return internationalizedArrayString paths and find translation mappings', () => {
+    const docSchema: ObjectSchemaType = Schema.compile({
+      name: 'test',
+      types: [
+        defineType({
+          type: 'document',
+          name: 'article',
+          fields: [
+            {type: 'string', name: 'title'},
+            {
+              type: 'object',
+              name: 'localeTitle',
+              fields: [
+                {type: 'string', name: 'en'},
+                {type: 'string', name: 'no'},
+              ],
+            },
+            {
+              type: 'array',
+              name: 'translations',
+              of: [
+                {
+                  type: 'object',
+                  name: 'internationalizedArrayString',
+                  fields: [{type: 'string', name: 'value'}],
+                },
+              ],
+            },
+          ],
+        }),
+      ],
+    }).get('article')
+
+    const doc: SanityDocumentLike = {
+      _id: 'na',
+      _type: 'article',
+      title: 'some title',
+      translations: [
+        {
+          _type: 'internationalizedArrayString',
+          _key: 'en',
+          value: 'some string',
+        },
+        {
+          _type: 'internationalizedArrayString',
+          _key: 'nb',
+        },
+      ],
+    }
+
+    const members = getDocumentMembersFlat(doc, docSchema)
+    expect(members.map((p) => pathToString(p.path))).toEqual([
+      'title',
+      'localeTitle',
+      'localeTitle.en',
+      'localeTitle.no',
+      'translations',
+      'translations[_key=="en"]',
+      'translations[_key=="en"].value',
+      'translations[_key=="nb"]',
+      'translations[_key=="nb"].value',
+    ])
+
+    const transMap = getTranslationMap(docSchema, members, 'en', ['nb'], defaultLanguageOutputs)
+
+    expect(transMap).toEqual(
+      typed<TranslationMap[]>([
+        {
+          inputLanguageId: 'en',
+          inputPath: ['translations', {_key: 'en'}],
+          outputs: [{id: 'nb', outputPath: ['translations', {_key: 'nb'}]}],
+        },
+      ])
+    )
+  })
+})

package/src/translate/paths.ts

@@ -0,0 +1,151 @@
+import {
+  isDocumentSchemaType,
+  isKeySegment,
+  ObjectSchemaType,
+  Path,
+  pathToString,
+  SanityDocumentLike,
+} from 'sanity'
+import {extractWithPath} from '@sanity/mutator'
+import {DocumentMember, TranslationOutputsFunction, TranslationOutput} from './types'
+
+export interface TranslationMap {
+  inputLanguageId: string
+  inputPath: Path
+  outputs: TranslationOutput[]
+}
+
+const MAX_DEPTH = 6
+
+export function getDocumentMembersFlat(doc: SanityDocumentLike, schemaType: ObjectSchemaType) {
+  if (!isDocumentSchemaType(schemaType)) {
+    console.error(`Schema type is not a document`)
+    return []
+  }
+
+  return extractPaths(doc, schemaType, [], MAX_DEPTH)
+}
+
+function extractPaths(
+  doc: SanityDocumentLike,
+  schemaType: ObjectSchemaType,
+  path: Path,
+  maxDepth: number
+): DocumentMember[] {
+  if (path.length >= maxDepth) {
+    return []
+  }
+
+  return schemaType.fields.reduce<DocumentMember[]>((acc, field) => {
+    const fieldPath = [...path, field.name]
+    const fieldSchema = field.type
+    const thisFieldWithPath: DocumentMember = {
+      path: fieldPath,
+      name: field.name,
+      schemaType: fieldSchema,
+    }
+
+    if (fieldSchema.jsonType === 'object') {
+      const innerFields = extractPaths(doc, fieldSchema, fieldPath, maxDepth)
+
+      return [...acc, thisFieldWithPath, ...innerFields]
+    } else if (
+      fieldSchema.jsonType === 'array' &&
+      fieldSchema.of.length &&
+      fieldSchema.of.some((item) => 'fields' in item)
+    ) {
+      const {value: arrayValue} = extractWithPath(pathToString(fieldPath), doc)[0] ?? {}
+
+      let arrayPaths: DocumentMember[] = []
+      if ((arrayValue as any)?.length) {
+        for (const item of arrayValue as any[]) {
+          const arrayItemSchema = fieldSchema.of.find((t) => t.name === item._type)
+          if (item._key && arrayItemSchema) {
+            const itemPath = [...fieldPath, {_key: item._key}]
+            const innerFields = extractPaths(
+              doc,
+              arrayItemSchema as ObjectSchemaType,
+              itemPath,
+              maxDepth
+            )
+            arrayPaths = [
+              ...arrayPaths,
+              {path: itemPath, name: item._key, schemaType: arrayItemSchema},
+              ...innerFields,
+            ]
+          }
+        }
+      }
+
+      return [...acc, thisFieldWithPath, ...arrayPaths]
+    }
+
+    return [...acc, thisFieldWithPath]
+  }, [])
+}
+
+export const defaultLanguageOutputs: TranslationOutputsFunction = function (
+  member,
+  enclosingType,
+  translateFromLanguageId,
+  translateToLanguageIds
+) {
+  if (
+    member.schemaType.jsonType === 'object' &&
+    member.schemaType.name.startsWith('internationalizedArray')
+  ) {
+    const pathEnd = member.path.slice(-1)
+
+    const language = isKeySegment(pathEnd[0]) ? pathEnd[0]._key : null
+    return language === translateFromLanguageId
+      ? translateToLanguageIds.map((translateToId) => ({
+          id: translateToId,
+          outputPath: [...member.path.slice(0, -1), {_key: translateToId}],
+        }))
+      : undefined
+  }
+
+  if (enclosingType.jsonType === 'object' && enclosingType.name.startsWith('locale')) {
+    return translateFromLanguageId === member.name
+      ? translateToLanguageIds.map((translateToId) => ({
+          id: translateToId,
+          outputPath: [...member.path.slice(0, -1), translateToId],
+        }))
+      : undefined
+  }
+
+  return undefined
+}
+
+export function getTranslationMap(
+  documentSchema: ObjectSchemaType,
+  documentMembers: DocumentMember[],
+  translateFromLanguageId: string,
+  outputLanguageIds: string[],
+  langFn: TranslationOutputsFunction
+): TranslationMap[] {
+  const translationMaps: TranslationMap[] = []
+  for (const member of documentMembers) {
+    const parentPath = member.path.slice(0, -1)
+    const enclosingType =
+      documentMembers.find((m) => pathToString(m.path) === pathToString(parentPath))?.schemaType ??
+      documentSchema
+
+    const translations = langFn(
+      member,
+      enclosingType,
+      translateFromLanguageId,
+      outputLanguageIds
+    )?.filter((translation) => translation.id !== translateFromLanguageId)
+
+    if (translations) {
+      translationMaps.push({
+        inputLanguageId: translateFromLanguageId,
+        inputPath: member.path,
+        outputs: translations,
+      })
+    }
+  }
+
+  return translationMaps
+}

package/src/translate/types.ts

@@ -0,0 +1,159 @@
+import {Path, SanityClient, SchemaType} from 'sanity'
+
+export interface Language {
+  id: string
+  title?: string
+}
+
+export interface DocumentMember {
+  schemaType: SchemaType
+  path: Path
+  name: string
+}
+
+export interface TranslationOutput {
+  /** Language id */
+  id: string
+  outputPath: Path
+}
+
+export type TranslationOutputsFunction = (
+  documentMember: DocumentMember,
+  enclosingType: SchemaType,
+  translateFromLanguageId: string,
+  translateToLanguageIds: string[]
+) => TranslationOutput[] | undefined
+
+export type LanguageCallback = (
+  client: SanityClient,
+  selectedLanguageParams: Record<string, unknown>
+) => Promise<Language[]>
+
+export interface FieldTranslationConfig {
+  /**
+   * `documentTypes` should be an array of strings where each entry must match a name from your document schemas.
+   *
+   * If defined, matching document will get a "Translate fields" instruction added.
+   **/
+  documentTypes?: string[]
+
+  /**
+   *
+   * Used for display strings in the Studio, and to determine languages for field level translations
+   *
+   * If the studio is using the sanity-plugin-internationalized-array plugin, this
+   * should be set to the same configuration.
+   */
+  languages: Language[] | LanguageCallback
+
+  /**
+   * API version for client passed to LanguageCallback for languages
+   * https://www.sanity.io/docs/api-versioning
+   * @defaultValue '2022-11-27'
+   */
+  apiVersion?: string
+
+  /**
+   * Specify fields that should be available in the languages callback:
+   * ```tsx
+   * {
+   *   select: {
+   *     markets: 'markets'
+   *   },
+   *   languages: (client, {markets}) =>
+   *     client.fetch('*[_type == "language" && market in $markets]{id,title}', {markets})
+   * }
+   * ```
+   *
+   * If the studio is using the sanity-plugin-internationalized-array plugin, this
+   * should be set to the same configuration.
+   */
+  selectLanguageParams?: Record<string, string>
+
+  /**
+   * `translationOutputs` is used when the "Translate fields" instruction is started by a Studio user.
+   *
+   *  It determines the relationships between document paths: Given a document path and a language, into which
+   *  sibling paths should translations be output.
+
+   *
+   * `translationOutputs` is invoked once per path in the document (limited to a depth of 6), with the following:
+   *
+   *  * `documentMember` - the field or array item for a given path; contains the path and its schemaType,
+   *  * `enclosingType` - the schema type of parent holding the member
+   *  * `translateFromLanguageId` - the languageId for the language the user want to translate from
+   *  * `translateToLanguageIds` - all languageIds the user can translate to
+   *
+   * The function should return a `TranslationOutput[]` array that contains all the paths where translations from
+   * documentMember language (translateFromLanguageId) should be output.
+   *
+   * The function should return `undefined` for all documentMembers that should not be directly translated,
+   * or are nested fields under a translated path.
+   *
+   * ## Default function
+   *
+   * The default function for `translationOutputs` is configured to be automatically compatible with sanity-plugin-internationalized-array
+   * and object types prefixed with "locale".
+   *
+   * See <link to source for defaultTranslationOutputs> implementation details.
+   *
+   * ## Example
+   * A document has the following document members:
+   * * `{path: 'localeObject.en', schemaType: ObjectSchemaType}`
+   * * `{path: 'localeObject.en.title', schemaType: StringSchemaType}`
+   * * `{path: 'localeObject.de', schemaType: ObjectSchemaType}`,
+   * * `{path: 'localeObject.de.title', schemaType: StringSchemaType}`
+   *
+   * `translationOutputs` for invoked with `translateFromLanguageId` `en`,
+   * should only return [{id: 'de', outputPath: 'localeObject.de'}] for the `'localeObject.en'` path,
+   * and undefined for all the other members.
+   *
+   * ### Example implementation
+   * ```ts
+   * function translationOutputs(member, enclosingType, translateFromLanguageId, translateToLanguageIds)
+   *   if (enclosingType.jsonType === 'object' && enclosingType.name.startsWith('locale') && translateFromLanguageId === member.name) {
+   *      return translateToLanguageIds.map((translateToId) => ({
+   *         id: translateToId,
+   *         outputPath: [...member.path.slice(0, -1), translateToId],
+   *      }))
+   *   }
+   *   return undefined
+   * }
+   * ```
+   **/
+  translationOutputs?: TranslationOutputsFunction
+}
+
+export interface DocumentTranslationConfig {
+  /**
+   * Path to language field in documents. Can be a hidden field.
+   * For instance: 'config.language'
+   *
+   * For projects that use the `@sanity/document-internationalization` plugin,
+   * this should be the same as `languageField` config for that plugin.
+   *
+   * Default: 'language'
+   */
+  languageField: string
+
+  /**
+   * `documentTypes` should be an array of strings where each entry must match a name from your document schemas.
+   *
+   * If defined, this property will add a translate instruction to these document types.
+   * If undefined, the instruction will be added to all documents with aiAssistance enabled and a field matching `documentLanguageField` config.
+   *
+   * Documents with translation support will get a "Translate document>" instruction added.
+   **/
+  documentTypes?: string[]
+}
+
+export interface TranslationConfig {
+  /**
+   * Config for document types with fields in multiple languages in the same document.
+   */
+  field?: FieldTranslationConfig
+  /**
+   * Config for document types with a single language field that determines the language for the whole document.
+   */
+  document?: DocumentTranslationConfig
+}

package/src/types.ts

@@ -1,4 +1,4 @@
-import {SanityDocument, ValidationMarker} from 'sanity'
+import {SanityDocument} from 'sanity'
 import {PortableTextBlock, PortableTextMarkDefinition, PortableTextSpan} from '@portabletext/types'
 
 //id prefixes
@@ -26,6 +26,9 @@ export const fieldPresenceTypeName = 'sanity.assist.instructionTask.presence' as
 export const assistSerializedTypeName = 'sanity.assist.serialized.type' as const
 export const assistSerializedFieldTypeName = 'sanity.assist.serialized.field' as const
 
+export const outputFieldTypeName = 'sanity.assist.output.field' as const
+export const outputTypeTypeName = 'sanity.assist.output.type' as const
+
 //url params
 export const inspectParam = 'inspect' as const
 export const fieldPathParam = 'pathKey' as const
@@ -149,10 +152,10 @@ export interface StudioInstruction {
   userId?: string
   title?: string
   placeholder?: string
+  output?: (OutputFieldItem | OutputTypeItem)[]
 
   //added after query / synthetic fields
   tasks?: InstructionTask[]
-  validation?: ValidationMarker[]
 }
 
 export interface AssistTasksStatus {
@@ -166,3 +169,19 @@ export interface AssistInspectorRouteParams {
   [fieldPathParam]?: string
   [instructionParam]?: string
 }
+
+export interface OutputFieldItem {
+  _type: typeof outputFieldTypeName
+  _key: string
+  //path relative to the field the instruction is for (same as _key)
+  relativePath?: string
+}
+
+export interface OutputTypeItem {
+  _type: typeof outputTypeTypeName
+  _key: string
+  /* array item type name */
+  type?: string
+  //path relative to the array-field the instruction is for, can be empty string (the array itself, same as _key)
+  relativePath?: string
+}

package/src/useApiClient.ts

@@ -3,6 +3,7 @@ import {useCallback, useMemo, useState} from 'react'
 import {serializeSchema} from './schemas/serialize/serializeSchema'
 import {useToast} from '@sanity/ui'
 import {SanityClient} from '@sanity/client'
+import {TranslationMap} from './translate/paths'
 
 export interface UserTextInstance {
   blockKey: string
@@ -35,6 +36,68 @@ export function useApiClient(customApiClient?: (defaultClient: SanityClient) =>
   )
 }
 
+export function useTranslate(apiClient: SanityClient) {
+  const [loading, setLoading] = useState(false)
+  const user = useCurrentUser()
+  const schema = useSchema()
+  const types = useMemo(() => serializeSchema(schema, {leanFormat: true}), [schema])
+  const toast = useToast()
+
+  const translate = useCallback(
+    ({
+      documentId,
+      languagePath,
+      fieldLanguageMap,
+    }: {
+      documentId: string
+      languagePath?: string
+      fieldLanguageMap?: TranslationMap[]
+    }) => {
+      setLoading(true)
+
+      return apiClient
+        .request({
+          method: 'POST',
+          url: `/assist/tasks/translate/${apiClient.config().dataset}?projectId=${
+            apiClient.config().projectId
+          }`,
+          body: {
+            documentId,
+            types,
+            languagePath,
+            fieldLanguageMap,
+            userId: user?.id,
+          },
+        })
+        .catch((e) => {
+          toast.push({
+            status: 'error',
+            title: 'Translate failed',
+            description: e.message,
+          })
+          setLoading(false)
+          throw e
+        })
+        .finally(() => {
+          // adding some artificial delay here
+          // server responds with 201 then proceeds; we dont need to allow spamming the button
+          setTimeout(() => {
+            setLoading(false)
+          }, 2000)
+        })
+    },
+    [setLoading, apiClient, toast, user, types]
+  )
+
+  return useMemo(
+    () => ({
+      translate,
+      loading,
+    }),
+    [translate, loading]
+  )
+}
+
 export function useGenerateCaption(apiClient: SanityClient) {
   const [loading, setLoading] = useState(false)
   const user = useCurrentUser()