@sanity/assist 3.1.1 → 3.2.1

package/README.md

@@ -31,6 +31,7 @@
   - [What it solves](#what-ai-assist-field-level-translations-solves)
   - [Configure](#configure-field-translations)
 - [Adding translation actions to fields](#adding-translation-actions-to-fields)
+- [Translation style guide](#translation-style-guide)
 - [License](#license)
 - [Develop \& test](#develop--test)
   - [Release new version](#release-new-version)
@@ -113,6 +114,7 @@ Note that instructions run using the permissions of the user invoking it, so onl
 themselves can edit can be changed by the instruction instance.
 
 ### Conditional user access
+
 To limit which users can see the AI Assist actions in the Studio, use a custom-plugin after `assist()`
 that filters out the inspector and actions, based on user properties:
 
@@ -141,7 +143,6 @@ export default defineConfig({
       },
     },
   ],
-
 })
 
 const ALLOWED_ROLES = ['administrator']
@@ -591,6 +592,28 @@ defineType({
 
 **If your schema is not using either of these structures**, refer to the section on [Custom language fields](#custom-language-fields).
 
+#### Note on document schema depth
+By default, field level translations will translate 6 "path-segments" deep.
+
+Depth is based on field path segments like so:
+- `title` has depth 1
+- `array[_key="no"].title` has depth 3
+
+If this is not sufficient for your document types, use `maxPathDepth`:
+
+```ts
+assist({
+  translate: {
+    field: {
+      maxPathDepth: 12
+    },
+  },
+})
+```
+
+Be careful not to set this too high in studios with recursive document schemas, as it could have negative impact on performance.
+maxPathDepth is hard-capped to 50.
+
 ### Loading field languages
 
 Languages must be an array of objects with an id and title.
@@ -749,7 +772,7 @@ function translationOutputs(
 }
 ```
 
-### Full field translation configuration example
+[### Full field translation configuration example]()
 
 ```ts
 assist({
@@ -817,6 +840,28 @@ defineField({
 })
 ```
 
+## Translation style guide
+
+In some cases you might want/need the translator to follow a certain style guide - for
+instance you might tell it not to translate certain words, or be more formal or casual.
+To configure this you can pass a `styleguide` property under the translation
+configuration:
+
+```ts
+assist({
+  translate: {
+    styleguide: `Be extremely formal and precise. Translate as if you are Spock from Star Trek.`,
+  },
+})
+```
+
+The style guide is currently limited to 2000 characters, and the translation might get
+slower the longer your style guide is. If the provided string is longer than the limit,
+the plugin will throw upon studio startup.
+
+Note that this is currently only available on a global level - it can not be defined
+per-field for now.
+
 ## Caveats
 
 Large Language Models (LLMs) are a new technology. Constraints and limitations are still being explored,

package/dist/index.d.mts

@@ -5,7 +5,7 @@ import {PortableTextBlock} from '@portabletext/types'
 import {PortableTextMarkDefinition} from '@portabletext/types'
 import {PortableTextSpan} from '@portabletext/types'
 import {SanityClient} from 'sanity'
-import {SanityClient as SanityClient_2} from '@sanity/client'
+import type {SanityClient as SanityClient_2} from '@sanity/client'
 import {SchemaType} from 'sanity'
 
 export declare const assist: Plugin_2<void | AssistPluginConfig>
@@ -129,57 +129,71 @@ export declare interface FieldTranslationConfig {
    */
   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` 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
+   * }
+   * ```
+   *
+   * @see #maxPathDepth
+   **/
   translationOutputs?: TranslationOutputsFunction
+  /**
+   * The max depth for document paths AI Assist will translate.
+   *
+   * Depth is based on field path segments:
+   * - `title` has depth 1
+   * - `array[_key="no"].title` has depth 3
+   *
+   * Be careful not to set this too high in studios with recursive document schemas, as it could have
+   * negative impact on performance.
+   *
+   * Default: 6
+   */
+  maxPathDepth?: number
 }
 
 declare type InlinePromptBlock = PortableTextSpan | FieldRef | UserInputBlock | ContextBlock
@@ -250,6 +264,12 @@ export declare interface TranslationConfig {
    * Config for document types with a single language field that determines the language for the whole document.
    */
   document?: DocumentTranslationConfig
+  /**
+   * A "style guide" that can be used to provide guidance on how to translate content.
+   * Will be passed to the LLM - ergo this is only a guide and the model _may_ not
+   * always follow it to the letter.
+   */
+  styleguide?: string
 }
 
 export declare interface TranslationOutput {

package/dist/index.d.ts

@@ -5,7 +5,7 @@ import {PortableTextBlock} from '@portabletext/types'
 import {PortableTextMarkDefinition} from '@portabletext/types'
 import {PortableTextSpan} from '@portabletext/types'
 import {SanityClient} from 'sanity'
-import {SanityClient as SanityClient_2} from '@sanity/client'
+import type {SanityClient as SanityClient_2} from '@sanity/client'
 import {SchemaType} from 'sanity'
 
 export declare const assist: Plugin_2<void | AssistPluginConfig>
@@ -129,57 +129,71 @@ export declare interface FieldTranslationConfig {
    */
   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` 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
+   * }
+   * ```
+   *
+   * @see #maxPathDepth
+   **/
   translationOutputs?: TranslationOutputsFunction
+  /**
+   * The max depth for document paths AI Assist will translate.
+   *
+   * Depth is based on field path segments:
+   * - `title` has depth 1
+   * - `array[_key="no"].title` has depth 3
+   *
+   * Be careful not to set this too high in studios with recursive document schemas, as it could have
+   * negative impact on performance.
+   *
+   * Default: 6
+   */
+  maxPathDepth?: number
 }
 
 declare type InlinePromptBlock = PortableTextSpan | FieldRef | UserInputBlock | ContextBlock
@@ -250,6 +264,12 @@ export declare interface TranslationConfig {
    * Config for document types with a single language field that determines the language for the whole document.
    */
   document?: DocumentTranslationConfig
+  /**
+   * A "style guide" that can be used to provide guidance on how to translate content.
+   * Will be passed to the LLM - ergo this is only a guide and the model _may_ not
+   * always follow it to the letter.
+   */
+  styleguide?: string
 }
 
 export declare interface TranslationOutput {