@braze/sanity-plugin-ai-translation 0.1.5 → 0.1.7

package/dist/index.d.ts

@@ -27,6 +27,7 @@ declare interface PluginConfig {
   languageFieldName: string;
   schemaId: string;
   maxConcurrentTranslationJobs?: number;
+  maxReferenceDepth?: number;
 }
 
 /**

package/dist/index.js

@@ -118,17 +118,24 @@ async function applySuggestions({
   suggestions,
   onProgress
 }) {
-  devLog.info("Applying suggestions", {
+  if (devLog.info("Applying suggestions", {
     sourceLanguage,
     targetLanguage,
+    targetLanguageType: typeof targetLanguage,
+    targetLanguageValue: targetLanguage,
     count: suggestions.filter((s) => s.approved).length
-  });
+  }), !targetLanguage)
+    throw devLog.error("targetLanguage is undefined in applySuggestions!", {
+      sourceLanguage,
+      targetLanguage,
+      suggestionsCount: suggestions.length
+    }), new Error("targetLanguage is required but was undefined");
   const approvedSuggestions = suggestions.filter((s) => s.approved);
   if (approvedSuggestions.length === 0) {
     devLog.info("No approved suggestions to apply");
     return;
   }
-  onProgress?.({ stage: "applying", message: "Applying updates to translation settings..." }), await applyImprovementsFromSuggestions(client, schemaId, sourceLanguage, approvedSuggestions, onProgress), devLog.info("Suggestions applied successfully");
+  onProgress?.({ stage: "applying", message: "Applying updates to translation settings..." }), await applyImprovementsFromSuggestions(client, schemaId, targetLanguage, approvedSuggestions, onProgress), devLog.info("Suggestions applied successfully");
 }
 function buildAnalysisPrompt({
   sourceLanguage,
@@ -203,7 +210,7 @@ function buildAnalysisPrompt({
     '  "globalPromptUpdates": "string | null - ONLY if this applies to ALL language pairs",',
     `  "localePromptUpdates": "string | null - ONLY if this is specific to ${sourceLanguage}\u2192${targetLanguage}",`,
     '  "protectedPhrasesToAdd": ["ONLY brand names, products, proper nouns that should NEVER translate"],',
-    '  "glossaryTermsToAdd": [{"sourceValue": "term", "targetValue": "translation"} - ONLY specific term mappings],',
+    '  "glossaryTermsToAdd": [{"sourceLocale": "sourceLocale","sourceValue": "term", "targetLocale": "targetLocale", "targetValue": "translation"} - ONLY specific term mappings],',
     '  "reasoning": "string - Explain your analysis and which mechanism you chose for each issue"',
     "}",
     "",
@@ -240,7 +247,9 @@ function convertAnalysisToSuggestions(analysis) {
         type: "glossaryTerm",
         description: `${term.sourceValue} \u2192 ${term.targetValue}`,
         approved: !0,
+        sourceLocale: term.sourceLocale,
         sourceValue: term.sourceValue,
+        targetLocale: term.targetLocale,
         targetValue: term.targetValue
       });
   return suggestions;
@@ -286,7 +295,7 @@ function parseAIResponse(responseText) {
     throw devLog.error("Error parsing AI response", { error, responseText }), new Error("Failed to parse AI response as JSON");
   }
 }
-async function applyImprovementsFromSuggestions(client, sourceLanguage, targetLanguage, suggestions, onProgress) {
+async function applyImprovementsFromSuggestions(client, schemaId, targetLanguage, suggestions, onProgress) {
   devLog.info("Applying improvements from suggestions", { count: suggestions.length });
   const settingsId = "translation-settings";
   await client.fetch("*[_id == $id][0]", { id: settingsId }) || await client.createIfNotExists({
@@ -294,28 +303,17 @@ async function applyImprovementsFromSuggestions(client, sourceLanguage, targetLa
     _type: "translationSettings"
   });
   const updates = [], globalPrompts = suggestions.filter((s) => s.type === "globalPrompt" && s.description.trim()), localePrompts = suggestions.filter((s) => s.type === "localePrompt" && s.description.trim()), protectedPhrases = suggestions.filter((s) => s.type === "protectedPhrase" && s.description.trim()), glossaryTerms = suggestions.filter(
-    (s) => s.type === "glossaryTerm" && s.sourceValue?.trim() && s.targetValue?.trim()
+    (s) => s.type === "glossaryTerm" && s.sourceLocale?.trim() && s.sourceValue?.trim() && s.targetLocale?.trim() && s.targetValue?.trim()
   );
   if (devLog.info("Filtered suggestions by type", {
     globalPrompts: globalPrompts.length,
     localePrompts: localePrompts.length,
     protectedPhrases: protectedPhrases.length,
     glossaryTerms: glossaryTerms.length
-  }), globalPrompts.length > 0) {
-    onProgress?.({ stage: "applying", message: "Updating global translation prompt..." });
-    const combinedUpdate = globalPrompts.map((s) => s.description).join(`
-
-`);
-    devLog.debug("Applying global prompt update", { combinedUpdate }), updates.push(updateGlobalPrompt(client, settingsId, combinedUpdate));
-  }
-  if (localePrompts.length > 0) {
-    onProgress?.({ stage: "applying", message: `Updating ${targetLanguage} translation prompt...` });
-    const combinedUpdate = localePrompts.map((s) => s.description).join(`
-
-`);
-    devLog.debug("Applying locale prompt update", { targetLanguage, combinedUpdate }), updates.push(updateLocalePrompt(client, settingsId, targetLanguage, combinedUpdate));
-  }
-  if (protectedPhrases.length > 0) {
+  }), (globalPrompts.length > 0 || localePrompts.length > 0) && (onProgress?.({
+    stage: "applying",
+    message: globalPrompts.length > 0 && localePrompts.length > 0 ? "Updating global and locale translation prompts..." : globalPrompts.length > 0 ? "Updating global translation prompt..." : `Updating ${targetLanguage} translation prompt...`
+  }), updates.push(updatePromptsWithTransform(client, schemaId, settingsId, targetLanguage, globalPrompts, localePrompts))), protectedPhrases.length > 0) {
     onProgress?.({ stage: "applying", message: "Adding protected phrases..." });
     const phrases = protectedPhrases.map((s) => s.description);
     devLog.debug("Applying protected phrases", { phrases }), updates.push(addProtectedPhrases(client, settingsId, phrases));
@@ -324,77 +322,118 @@ async function applyImprovementsFromSuggestions(client, sourceLanguage, targetLa
     onProgress?.({ stage: "applying", message: "Adding glossary terms..." });
     const terms = glossaryTerms.map((s) => ({
       // biome-ignore-start lint/style/noNonNullAssertion: safely handled
+      sourceLocale: s.sourceLocale,
       sourceValue: s.sourceValue,
+      targetLocale: s.targetLocale,
       targetValue: s.targetValue
       // biome-ignore-end lint/style/noNonNullAssertion: safely handled
     }));
-    devLog.debug("Applying glossary terms", { terms }), updates.push(addGlossaryTerms(client, terms, sourceLanguage, targetLanguage));
+    devLog.debug("Applying glossary terms", { terms }), updates.push(addGlossaryTerms(client, terms));
   }
   updates.length === 0 && devLog.warn("No valid updates to apply - all suggestions may have been empty"), await Promise.all(updates), devLog.info("All improvements applied successfully");
 }
-async function mergePromptWithAI(client, currentPrompt, newGuidance, context) {
-  const instruction = `
-You are updating a ${context === "global" ? "translation" : `locale-specific translation for ${context}`} prompt.
-Your task is to merge new guidance into an existing prompt.
+async function updatePromptsWithTransform(client, schemaId, settingsId, targetLanguage, globalPrompts, localePrompts) {
+  if (devLog.info("Updating prompts with transform action", {
+    settingsId,
+    targetLanguage,
+    targetLanguageType: typeof targetLanguage,
+    targetLanguageValue: targetLanguage,
+    hasGlobalUpdates: globalPrompts.length > 0,
+    hasLocaleUpdates: localePrompts.length > 0
+  }), !targetLanguage)
+    throw devLog.error("targetLanguage is undefined or empty!", {
+      targetLanguage,
+      globalPrompts: globalPrompts.length,
+      localePrompts: localePrompts.length
+    }), new Error("targetLanguage is required but was undefined");
+  const targets = [];
+  if (globalPrompts.length > 0) {
+    const combinedGlobalUpdate = globalPrompts.map((s) => s.description).join(`
 
-CURRENT PROMPT:
-${currentPrompt}
+`);
+    targets.push({
+      path: "globalPrompt",
+      instruction: `You are updating a translation prompt document that contains rules and guidance for future AI translations.
 
-NEW GUIDANCE TO ADD:
-${newGuidance}
+IMPORTANT: The text below is NEW GUIDANCE that should be INCORPORATED INTO the existing prompt as additional rules/instructions for future translations. DO NOT apply or execute these rules on the prompt text itself.
 
-INSTRUCTIONS:
-- Read the current prompt carefully
-- Integrate the new guidance into the prompt in a natural, coherent way
-- If the new guidance conflicts with existing content, update or replace the conflicting parts
-- If the new guidance is already covered, do not add redundant text
-- Maintain the structure and tone of the prompt
-- Output ONLY the updated prompt text, with no preamble or explanation
+Your task: Merge the new guidance below into the existing prompt text. Treat the new guidance as rules that will guide future translations, not as transformations to apply to the current text.
 
-OUTPUT THE UPDATED PROMPT:`.trim(), mergedPrompt = await client.agent.action.prompt({
-    instruction,
-    format: "string"
-  });
-  return devLog.debug("AI merged prompt", {
-    context,
-    originalLength: currentPrompt.length,
-    newLength: mergedPrompt.length
-  }), mergedPrompt;
-}
-async function updateGlobalPrompt(client, settingsId, updates) {
-  devLog.info("Updating global prompt", { settingsId, updatesLength: updates.length });
-  const currentPrompt = await client.fetch("*[_id == $settingsId][0].globalPrompt", { settingsId });
-  devLog.debug("Fetched current global prompt", {
-    hasCurrentPrompt: !!currentPrompt,
-    currentLength: currentPrompt?.length
-  });
-  const newPrompt = currentPrompt ? await mergePromptWithAI(client, currentPrompt, updates, "global") : updates, result = await client.patch(settingsId).set({ globalPrompt: newPrompt.trim() }).commit();
-  devLog.info("Global prompt updated", { resultId: result._id, newPromptLength: newPrompt.length });
-}
-async function updateLocalePrompt(client, settingsId, locale, updates) {
-  devLog.info("Updating locale prompt", { settingsId, locale, updatesLength: updates.length });
-  const currentLocalePrompts = await client.fetch(
-    "*[_id == $settingsId][0].localePrompts",
-    { settingsId }
-  );
-  devLog.debug("Fetched current locale prompts", { count: currentLocalePrompts?.length });
-  const existingPrompt = currentLocalePrompts?.find((lp) => lp.locale === locale);
-  if (devLog.debug("Found existing prompt for locale", { locale, hasExisting: !!existingPrompt }), existingPrompt?.prompt) {
-    const newPrompt = await mergePromptWithAI(client, existingPrompt.prompt, updates, locale), updatedPrompts = currentLocalePrompts.map(
-      (lp) => lp.locale === locale ? { ...lp, prompt: newPrompt.trim() } : lp
-    ), result = await client.patch(settingsId).set({ localePrompts: updatedPrompts }).commit();
-    devLog.info("Locale prompt updated (merged)", { locale, resultId: result._id });
-  } else {
-    const result = await client.patch(settingsId).setIfMissing({ localePrompts: [] }).append("localePrompts", [
+Integration guidelines:
+- Add the new guidance as additional instructions/rules in the prompt
+- If it conflicts with existing guidance, update or replace the conflicting parts
+- If it's already covered, don't add redundant text
+- Maintain clear structure and consistent tone
+- Preserve all existing guidance that is still relevant
+- Keep the prompt written as instructions for a translator (e.g., "When translating, you should..." not "The translation has been...")
+
+New guidance to incorporate:
+
+\`\`\`
+${combinedGlobalUpdate}
+\`\`\``
+    }), devLog.debug("Added global prompt target", { combinedUpdate: combinedGlobalUpdate });
+  }
+  if (localePrompts.length > 0) {
+    const combinedLocaleUpdate = localePrompts.map((s) => s.description).join(`
+
+`), existingLocalePrompts = await client.fetch(
+      "*[_id == $settingsId][0].localePrompts",
+      { settingsId }
+    ), hasExistingLocalePrompt = existingLocalePrompts?.some((lp) => lp._key === targetLanguage);
+    devLog.debug("Checking existing locale prompt", {
+      targetLanguage,
+      hasExistingLocalePrompt,
+      existingCount: existingLocalePrompts?.length || 0
+    }), hasExistingLocalePrompt || (devLog.info("Creating new locale prompt entry", { targetLanguage }), await client.patch(settingsId).setIfMissing({ localePrompts: [] }).append("localePrompts", [
       {
-        _type: "localePrompt",
-        _key: locale,
-        locale,
-        prompt: updates.trim()
+        _type: "internationalizedArrayTextValue",
+        _key: targetLanguage,
+        value: ""
+        // Start with empty value, transform will fill it
       }
-    ]).commit();
-    devLog.info("Locale prompt created", { locale, resultId: result._id });
+    ]).commit());
+    const localePromptPath = ["localePrompts", { _key: targetLanguage }, "value"];
+    targets.push({
+      // @ts-expect-error
+      path: localePromptPath,
+      instruction: `You are updating a translation prompt document that contains rules and guidance for future AI translations.
+
+IMPORTANT: The text below is NEW GUIDANCE that should be INCORPORATED INTO the existing prompt as additional rules/instructions for future translations. DO NOT apply or execute these rules on the prompt text itself.
+
+Your task: Merge the new guidance below into the existing prompt text. Treat the new guidance as rules that will guide future translations, not as transformations to apply to the current text.
+
+Integration guidelines:
+- Add the new guidance as additional instructions/rules in the prompt
+- If it conflicts with existing guidance, update or replace the conflicting parts
+- If it's already covered, don't add redundant text
+- Maintain clear structure and consistent tone
+- Preserve all existing guidance that is still relevant
+- Keep the prompt written as instructions for a translator (e.g., "When translating, you should..." not "The translation has been...")
+
+New guidance to incorporate:
+
+\`\`\`
+${combinedLocaleUpdate}
+\`\`\``
+    }), devLog.debug("Added locale prompt target", {
+      targetLanguage,
+      localePromptPath,
+      combinedUpdate: combinedLocaleUpdate
+    });
   }
+  const result = await client.agent.action.transform({
+    schemaId,
+    documentId: settingsId,
+    instruction: "Update translation prompts based on user feedback to improve future translations.",
+    target: targets,
+    forcePublishedWrite: !0
+  });
+  devLog.info("Prompts updated via transform action", {
+    resultId: result._id,
+    globalUpdated: globalPrompts.length > 0,
+    localeUpdated: localePrompts.length > 0
+  });
 }
 async function addProtectedPhrases(client, settingsId, phrases) {
   devLog.info("Adding protected phrases", { settingsId, phrasesCount: phrases.length, phrases });
@@ -408,7 +447,7 @@ async function addProtectedPhrases(client, settingsId, phrases) {
   const result = await client.patch(settingsId).setIfMissing({ protectedPhrases: [] }).append("protectedPhrases", newPhrases).commit();
   devLog.info("Protected phrases added", { count: newPhrases.length, phrases: newPhrases, resultId: result._id });
 }
-async function addGlossaryTerms(client, terms, sourceLocale, targetLocale) {
+async function addGlossaryTerms(client, terms) {
   const validTerms = terms.filter(({ sourceValue, targetValue }) => sourceValue === targetValue ? (devLog.warn("Skipping glossary term where source === target (should be a protected phrase)", {
     sourceValue,
     targetValue
@@ -417,38 +456,37 @@ async function addGlossaryTerms(client, terms, sourceLocale, targetLocale) {
     devLog.info("No valid glossary terms to add");
     return;
   }
-  for (const { sourceValue, targetValue } of validTerms) {
+  for (const { sourceLocale, sourceValue, targetLocale, targetValue } of validTerms) {
     const existingTerm = await client.fetch(
-      `*[_type == "translationGlossaryTerm"
-        && count(translations[locale == $sourceLocale && value == $sourceValue]) > 0
+      `*[_type == "translationGlossaryTerm" && count(translations[_key == $sourceLocale && value == $sourceValue]) > 0
       ][0] {
         _id,
         translations
       }`,
       { sourceLocale, sourceValue }
     );
-    existingTerm ? existingTerm.translations.some(
-      (t) => t.locale === targetLocale && t.value === targetValue
-    ) ? devLog.info("Glossary term already has this translation", { sourceValue, targetValue, targetLocale }) : (await client.patch(existingTerm._id).append("translations", [
+    existingTerm ? existingTerm.translations.some((t) => t._key === targetLocale) ? devLog.info("Glossary term already has this translation", {
+      sourceLocale,
+      sourceValue,
+      targetLocale,
+      targetValue
+    }) : (await client.patch(existingTerm._id).append("translations", [
       {
-        _type: "translation",
+        _type: "internationalizedArrayStringValue",
         _key: targetLocale,
-        locale: targetLocale,
         value: targetValue
       }
-    ]).commit(), devLog.info("Updated existing glossary term", { sourceValue, targetValue, targetLocale })) : (await client.create({
+    ]).commit(), devLog.info("Updated existing glossary term", { sourceLocale, sourceValue, targetLocale, targetValue })) : (await client.create({
       _type: "translationGlossaryTerm",
       translations: [
         {
-          _type: "translation",
+          _type: "internationalizedArrayStringValue",
           _key: sourceLocale,
-          locale: sourceLocale,
           value: sourceValue
         },
         {
-          _type: "translation",
+          _type: "internationalizedArrayStringValue",
           _key: targetLocale,
-          locale: targetLocale,
           value: targetValue
         }
       ]
@@ -729,7 +767,7 @@ const ICON_SIZE = 64, progressIconMap = {
         client,
         schemaId: config.schemaId,
         sourceLanguage: translationHistory2.sourceLanguage || "en-us",
-        targetLanguage: document[config.languageFieldName],
+        targetLanguage: translationHistory2.language,
         suggestions,
         onProgress: ({ stage, message }) => {
           setProcessingState(stage), setChangeSummary(message);
@@ -972,24 +1010,7 @@ const ICON_SIZE = 64, progressIconMap = {
     defineField({
       name: "translations",
       title: "Translations",
-      type: "array",
-      of: [
-        {
-          name: "translation",
-          title: "Translation",
-          type: "object",
-          fields: [
-            defineField({
-              name: "locale",
-              type: "string"
-            }),
-            defineField({
-              name: "value",
-              type: "string"
-            })
-          ]
-        }
-      ]
+      type: "internationalizedArrayString"
     })
   ],
   preview: {
@@ -1050,21 +1071,6 @@ const ICON_SIZE = 64, progressIconMap = {
       ]
     }
   ]
-}), localePrompt = defineField({
-  name: "localePrompt",
-  title: "Locale Prompt",
-  type: "object",
-  fields: [
-    defineField({
-      name: "locale",
-      type: "string"
-    }),
-    defineField({
-      name: "prompt",
-      type: "text",
-      rows: 5
-    })
-  ]
 }), translationSettings = defineType({
   name: "translationSettings",
   title: "Translation Settings",
@@ -1082,8 +1088,7 @@ const ICON_SIZE = 64, progressIconMap = {
       name: "localePrompts",
       title: "Locale Prompts",
       description: "Prompts that will be given to the Sanity AI Agent for each locale.",
-      type: "array",
-      of: [localePrompt]
+      type: "internationalizedArrayText"
     }),
     defineField({
       name: "protectedPhrases",
@@ -1120,9 +1125,9 @@ const ICON_SIZE = 64, progressIconMap = {
   ) || [], glossaryTermsByLocale = {};
   for (const targetLanguage of targetLanguages) {
     const relevantTranslations = translationGlossaryTerms.filter(
-      (termTranslations) => termTranslations.some((translation) => translation.locale === targetLanguage)
+      (termTranslations) => termTranslations.some((translation) => translation._key === targetLanguage)
     ).map((termTranslations) => {
-      const from = termTranslations.find((translation) => translation.locale === sourceLanguage)?.value, to = termTranslations.find((translation) => translation.locale === targetLanguage)?.value;
+      const from = termTranslations.find((translation) => translation._key === sourceLanguage)?.value, to = termTranslations.find((translation) => translation._key === targetLanguage)?.value;
       return !from || !to ? null : { from, to };
     }).filter((item) => item !== null);
     glossaryTermsByLocale[targetLanguage] = relevantTranslations;
@@ -1134,14 +1139,16 @@ const ICON_SIZE = 64, progressIconMap = {
       targetLanguages.map((locale) => [
         locale,
         {
-          prompt: translationSettings2?.localePrompts?.find((lp) => lp.locale === locale)?.prompt,
+          prompt: translationSettings2?.localePrompts?.find((lp) => lp._key === locale)?.value,
           glossaryTerms: formatGlossaryTermInstruction(glossaryTermsByLocale[locale])
         }
       ])
     )
   };
 }, formatGlossaryTermInstruction = (terms) => {
-  const instructions = ["Translate the following terms exactly as described below:"];
+  const instructions = [
+    "Translate the following terms exactly as described below. When a term includes a colon, the suffix following the colon describes how the term should be translated for the female gender."
+  ];
   return terms.forEach(({ from, to }) => {
     instructions.push(`"${from}" -> "${to}"`);
   }), instructions.join(`
@@ -1807,6 +1814,7 @@ const setupTranslationJobStatuses = (dispatch, sourceDocuments, targetLanguages)
               references,
               shouldOverwriteFreshTranslations,
               maxConcurrentTranslationJobs: config.maxConcurrentTranslationJobs,
+              maxReferenceDepth: config.maxReferenceDepth,
               shouldTranslateDiffs
             });
           },
@@ -1918,7 +1926,7 @@ const setupTranslationJobStatuses = (dispatch, sourceDocuments, targetLanguages)
   }
   return result;
 }, ReferenceConfigPanel = () => {
-  const { dispatch, document, shouldTranslateReferences, maxReferenceDepth, config, references } = useTranslationContext(), client = useClient({ apiVersion: "vX" }), [isLoadingReferences, setIsLoadingReferences] = useState(!1);
+  const { dispatch, document, shouldTranslateReferences, maxReferenceDepth, config, references } = useTranslationContext(), client = useClient({ apiVersion: "vX" }), [isLoadingReferences, setIsLoadingReferences] = useState(!1), maxDepth = config.maxReferenceDepth || 3;
   useEffect(() => {
     (async () => {
       if (setIsLoadingReferences(!0), !shouldTranslateReferences) {
@@ -1976,18 +1984,14 @@ const setupTranslationJobStatuses = (dispatch, sourceDocuments, targetLanguages)
       ),
       shouldTranslateReferences ? /* @__PURE__ */ jsxs(Inline, { space: 2, children: [
         /* @__PURE__ */ jsx(Text, { children: "Max Depth:" }),
-        /* @__PURE__ */ jsxs(
+        /* @__PURE__ */ jsx(
           Select,
           {
             disabled: !shouldTranslateReferences,
             placeholder: "Depth",
             onChange: handleMaxReferenceDepthChange,
             value: maxReferenceDepth.toString(),
-            children: [
-              /* @__PURE__ */ jsx("option", { value: 1, children: "1" }),
-              /* @__PURE__ */ jsx("option", { value: 2, children: "2" }),
-              /* @__PURE__ */ jsx("option", { value: 3, children: "3" })
-            ]
+            children: Array.from({ length: maxDepth }, (_, i) => i + 1).map((depth) => /* @__PURE__ */ jsx("option", { value: depth.toString(), children: depth }, depth))
           }
         )
       ] }) : null
@@ -2197,7 +2201,7 @@ const setupTranslationJobStatuses = (dispatch, sourceDocuments, targetLanguages)
     documentType: document?._type,
     translatableTypes: config.translatableSchemaTypes
   }), null) : config ? {
-    label: "Translate!",
+    label: "Translate",
     icon: TranslateIcon,
     onHandle: () => {
       devLog.info("Translation dialog opened", {