feat: allow specifying a translation style guide

plugin/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)
@@ -817,6 +818,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,

plugin/src/plugin.tsx

@@ -36,6 +36,14 @@ export interface AssistPluginConfig {
 
 export const assist = definePlugin<AssistPluginConfig | void>((config) => {
   const configWithDefaults = config ?? {}
+  const styleguide = configWithDefaults.translate?.styleguide || ''
+
+  if (styleguide.length > 2000) {
+    throw new Error(
+      `[${packageName}]: \`translate.styleguide\` value is too long. It must be 2000 characters or less, was ${styleguide.length} characters`,
+    )
+  }
+
   return {
     name: packageName,
 

plugin/src/translate/FieldTranslationProvider.tsx

@@ -68,6 +68,7 @@ function hasValuesToTranslate(
 export function FieldTranslationProvider(props: PropsWithChildren<{}>) {
   const {config: assistConfig} = useAiAssistanceConfig()
   const apiClient = useApiClient(assistConfig.__customApiClient)
+  const styleguide = assistConfig.translate?.styleguide
   const config = assistConfig.translate?.field
   const {translate: runTranslate} = useTranslate(apiClient)
 
@@ -193,7 +194,8 @@ export function FieldTranslationProvider(props: PropsWithChildren<{}>) {
     if (fieldLanguageMaps && documentId && translatePath) {
       runTranslate({
         documentId,
-        translatePath: translatePath,
+        translatePath,
+        styleguide,
         fieldLanguageMap: fieldLanguageMaps.map((map) => ({
           ...map,
           // eslint-disable-next-line max-nested-callbacks
@@ -207,6 +209,7 @@ export function FieldTranslationProvider(props: PropsWithChildren<{}>) {
     fieldLanguageMaps,
     documentId,
     runTranslate,
+    styleguide,
     close,
     toLanguages,
     fieldTranslationParams?.translatePath,

plugin/src/translate/translateActions.tsx

@@ -73,6 +73,7 @@ export const translateActions: DocumentFieldAction = {
         task: translationApi.translate,
       })
 
+      const styleguide = config.translate?.styleguide
       const languagePath = config.translate?.document?.languageField
 
       // if this is true, it is stable, and not breaking rules of hooks
@@ -98,6 +99,7 @@ export const translateActions: DocumentFieldAction = {
             translate({
               languagePath,
               translatePath: path,
+              styleguide,
               documentId: documentId ?? '',
               conditionalMembers: formStateRef.current
                 ? getConditionalMembers(formStateRef.current)
@@ -110,6 +112,7 @@ export const translateActions: DocumentFieldAction = {
       }, [
         languagePath,
         translate,
+        styleguide,
         documentId,
         translationApi.loading,
         documentTranslationEnabled,

plugin/src/translate/types.ts

@@ -157,4 +157,10 @@ export 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
 }

plugin/src/useApiClient.ts

@@ -34,6 +34,7 @@ export interface TranslateRequest {
   documentId: string
   translatePath: Path
   languagePath?: string
+  styleguide?: string
   fieldLanguageMap?: FieldLanguageMap[]
   conditionalMembers?: ConditionalMemberState[]
 }
@@ -63,6 +64,7 @@ export function useTranslate(apiClient: SanityClient) {
     ({
       documentId,
       languagePath,
+      styleguide,
       translatePath,
       fieldLanguageMap,
       conditionalMembers,
@@ -79,6 +81,7 @@ export function useTranslate(apiClient: SanityClient) {
             documentId,
             types,
             languagePath,
+            userStyleguide: styleguide,
             fieldLanguageMap,
             conditionalMembers,
             translatePath:

studio/sanity.config.ts

@@ -67,6 +67,7 @@ export default defineConfig({
           documentTypes: translatedDocTypes,
           languageField: 'language',
         },
+        styleguide: 'Retain the word "Headless" in all translations as is, regardless of language.',
       },
 
       __customApiClient: (defaultClient) =>