fix(content-translator): translate rich text as marker units and align by input index (#166)

Author: jhb-dev

content-translator/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+- fix: translate rich text block-level elements as one unit using segment markers so inline formatting spans stay aligned and word order can change across languages
+- fix: reconstruct OpenAI translations by input index so a merged, dropped, or reordered entry no longer shifts later translations into the wrong fields; missing entries keep their original text
+- fix: abort a translation when the resolver returns a different number of texts than were sent, and guard against non-string values reaching `he.decode`
 - fix: translate each entry of `hasMany` text fields individually so keyword/tag lists are translated instead of crashing
 - fix: translate fields inside unnamed (presentational) groups instead of throwing an "Unnamed groups are currently not supported" error
 - fix: skip fields and tabs named `__proto__`, `constructor`, or `prototype` during traversal to avoid prototype-polluting writes when a user-supplied Payload config contains such a name

content-translator/src/resolvers/openAI.ts

@@ -32,16 +32,23 @@ type OpenAIResponse = {
 }
 
 const defaultPrompt: OpenAIPrompt = ({ localeFrom, localeTo, texts }) => {
-  return `Translate the following array of strings from the language with ISO 639 code "${localeFrom}" to the language with ISO 639 code "${localeTo}".
+  const indexed: Record<string, string> = {}
+  texts.forEach((text, i) => {
+    indexed[String(i)] = text
+  })
 
-IMPORTANT: You must return ONLY a valid JSON object with a "translations" key containing the array of translated strings. The array must maintain the exact same length and order as the input. Properly escape all special characters including quotes, newlines, and backslashes according to JSON standards.
+  return `Translate the values of the following JSON object from the language with ISO 639 code "${localeFrom}" to the language with ISO 639 code "${localeTo}".
 
-Input array to translate:
-${JSON.stringify(texts, null, 2)}
+IMPORTANT: Return ONLY a valid JSON object with a "translations" key whose value is an object using the EXACT SAME KEYS as the input. Translate each value independently and keep it under its own key. Never merge, split, drop, reorder, or add entries — even if two adjacent values look like fragments of the same sentence, they MUST stay as separate keys. Preserve leading and trailing whitespace of each value. Properly escape all special characters including quotes, newlines, and backslashes according to JSON standards.
+
+Some values contain segment markers of the form ⟦0⟧, ⟦1⟧, ⟦2⟧ (a number enclosed in the brackets ⟦ ⟧). These markers separate inline formatting spans within one text. In your translation, keep every marker exactly as it appears — same characters, same numbers, each marker exactly once — and place each marker immediately before the translated words that belong to its segment. You may move words across markers when grammar requires it, but never add, remove, renumber, duplicate, or translate the markers themselves.
+
+Input object to translate:
+${JSON.stringify(indexed, null, 2)}
 
 Expected response format:
 {
-  "translations": ["translated string 1", "translated string 2", ...]
+  "translations": { "0": "translated value 0", "1": "translated value 1" }
 }`
 }
 
@@ -63,6 +70,7 @@ export const openAIResolver = ({
       try {
         const response: {
           data: OpenAIResponse
+          inputTexts: string[]
           success: boolean
         }[] = await Promise.all(
           chunkArray(texts, chunkLength).map(async (texts) => {
@@ -94,6 +102,7 @@ export const openAIResolver = ({
 
               return {
                 data,
+                inputTexts: texts,
                 success: res.ok,
               }
             })
@@ -102,7 +111,7 @@ export const openAIResolver = ({
 
         const translated: string[] = []
 
-        for (const { data, success } of response) {
+        for (const { data, inputTexts, success } of response) {
           if (!success) {
             return {
               success: false as const,
@@ -121,12 +130,12 @@ export const openAIResolver = ({
             }
           }
 
-          let translatedChunk: string[] = []
+          let translationsObj: unknown
 
           try {
             const parsedResponse = JSON.parse(content)
 
-            // Extract translations array from the response object
+            // Extract the translations from the response object
             if (!parsedResponse || typeof parsedResponse !== 'object') {
               req.payload.logger.error({
                 fullContent: content,
@@ -152,7 +161,7 @@ export const openAIResolver = ({
               }
             }
 
-            translatedChunk = parsedResponse.translations
+            translationsObj = parsedResponse.translations
           } catch (e) {
             req.payload.logger.error({
               error: e instanceof Error ? e.message : String(e),
@@ -165,35 +174,47 @@ export const openAIResolver = ({
             }
           }
 
-          if (!Array.isArray(translatedChunk)) {
+          // "translations" must be an object (keyed by index) or an array.
+          // A bare string would otherwise be indexed character by character
+          // (e.g. "abc"["0"] === "a"), producing garbage that still looks
+          // like a success - so reject anything that is not an object/array.
+          if (translationsObj === null || typeof translationsObj !== 'object') {
             req.payload.logger.error({
-              data: translatedChunk,
               fullContent: content,
               message:
-                'An error occurred when trying to translate the data using OpenAI API - parsed content is not an array',
+                'An error occurred when trying to parse the content - "translations" is not an object or array',
+              translations: translationsObj,
             })
 
             return {
               success: false as const,
             }
           }
 
-          for (const text of translatedChunk) {
-            if (text && typeof text !== 'string') {
-              req.payload.logger.error({
-                chunkData: translatedChunk,
-                data: text,
-                fullContent: content,
+          // The model is asked to return an object keyed by the input index.
+          // Reconstruct the output strictly from the input indices so the
+          // result always has the same length and order as the input. A
+          // missing / merged / non-string key keeps the original text (left
+          // untranslated in its own slot) instead of shifting every later
+          // value into the wrong field. An array response is tolerated too,
+          // for backwards compatibility with custom prompts.
+          for (let i = 0; i < inputTexts.length; i++) {
+            const value = Array.isArray(translationsObj)
+              ? translationsObj[i]
+              : (translationsObj as Record<string, unknown>)[String(i)]
+
+            if (typeof value === 'string') {
+              translated.push(value)
+            } else {
+              req.payload.logger.warn({
+                index: i,
                 message:
-                  'An error occurred when trying to translate the data using OpenAI API - parsed content is not a string',
+                  'Translation missing or not a string for input index - keeping original text',
+                original: inputTexts[i],
               })
 
-              return {
-                success: false as const,
-              }
+              translated.push(inputTexts[i])
             }
-
-            translated.push(text)
           }
         }
 

content-translator/src/translate/operation.ts

@@ -79,12 +79,29 @@ export const translateOperation = async (args: TranslateOperationArgs) => {
   let result: TranslateResult
 
   if (!resolveResult.success) {
+    result = {
+      success: false,
+    }
+  } else if (resolveResult.translatedTexts.length !== valuesToTranslate.length) {
+    // Defense in depth: the resolver must return exactly one translation per
+    // input value, in order. A count mismatch means index-based write-back
+    // would shift translations into the wrong fields, so fail instead.
+    req.payload.logger.error({
+      inputCount: valuesToTranslate.length,
+      message: 'Translation aborted: resolver returned a different number of texts than were sent',
+      outputCount: resolveResult.translatedTexts.length,
+    })
+
     result = {
       success: false,
     }
   } else {
     resolveResult.translatedTexts.forEach((translated, index) => {
-      const formattedValue = he.decode(translated)
+      // he.decode() calls String.prototype.replace internally, so a
+      // non-string value (e.g. an array slipping through from a hasMany
+      // field) would throw "e.replace is not a function". Guard against it
+      // and pass non-strings through untouched.
+      const formattedValue = typeof translated === 'string' ? he.decode(translated) : translated
 
       valuesToTranslate[index].onTranslate(formattedValue)
     })

content-translator/src/translate/traverseFields.ts

@@ -263,14 +263,6 @@ export const traverseFields = ({
         if (root) {
           traverseRichText({
             emptyOnly,
-            onText: (siblingData, key) => {
-              valuesToTranslate.push({
-                onTranslate: (translated: string) => {
-                  siblingData[key] = translated
-                },
-                value: siblingData[key],
-              })
-            },
             payloadConfig,
             root,
             translatedData,

content-translator/src/translate/traverseRichText.ts

@@ -4,17 +4,95 @@ import type { ValueToTranslate } from './types.js'
 
 import { traverseFields } from './traverseFields.js'
 
+// Markers delimit the individual text nodes inside a single block-level element
+// (paragraph, heading, list item, quote, ...) so the element can be translated
+// as ONE unit. This lets the translator reorder words across nodes — required
+// for languages like German -> English where the verb moves — while each
+// formatting span (bold, italic, ...) still receives its own translated text.
+// Translating each text node in isolation made the model merge adjacent
+// sentence fragments and shift content (and formatting) into the wrong nodes.
+const MARKER_OPEN = '⟦'
+const MARKER_CLOSE = '⟧'
+const buildMarker = (i: number) => `${MARKER_OPEN}${i}${MARKER_CLOSE}`
+const markerRegex = /⟦(\d+)⟧/g
+
+// Translate a maximal run of consecutive text-node siblings. A single node is
+// sent as plain text (no markers). Two or more nodes are joined into one
+// marker-delimited value and split back apart once translated.
+const pushTextRun = (run: Record<string, any>[], valuesToTranslate: ValueToTranslate[]) => {
+  if (run.length === 1) {
+    const node = run[0]
+
+    if (!node.text) {
+      return
+    }
+
+    valuesToTranslate.push({
+      onTranslate: (translated) => {
+        node.text = translated
+      },
+      value: node.text,
+    })
+
+    return
+  }
+
+  let combined = ''
+  run.forEach((node, index) => {
+    combined += buildMarker(index) + node.text
+  })
+
+  valuesToTranslate.push({
+    onTranslate: (translated: string) => {
+      const matches: { end: number; index: number; start: number }[] = []
+      let match: null | RegExpExecArray
+      markerRegex.lastIndex = 0
+
+      while ((match = markerRegex.exec(translated)) !== null) {
+        matches.push({
+          end: markerRegex.lastIndex,
+          index: parseInt(match[1], 10),
+          start: match.index,
+        })
+      }
+
+      if (matches.length === 0) {
+        // No markers survived translation - keep the originals rather than
+        // writing the whole translated blob into the first node.
+        return
+      }
+
+      // Each segment is the text following its marker up to the next marker
+      // in textual order, so reordering across markers is handled correctly.
+      const segments: Record<number, string> = {}
+      for (let m = 0; m < matches.length; m++) {
+        const current = matches[m]
+        const next = matches[m + 1]
+        segments[current.index] = translated.slice(
+          current.end,
+          next ? next.start : translated.length,
+        )
+      }
+
+      run.forEach((node, index) => {
+        if (typeof segments[index] === 'string') {
+          node.text = segments[index]
+        }
+      })
+    },
+    value: combined,
+  })
+}
+
 export const traverseRichText = ({
   emptyOnly,
-  onText,
   payloadConfig,
   root,
   siblingData,
   translatedData,
   valuesToTranslate,
 }: {
   emptyOnly: boolean
-  onText: (siblingData: Record<string, unknown>, key: string) => void
   payloadConfig: SanitizedConfig
   root: Record<string, unknown>
   siblingData?: Record<string, unknown>
@@ -23,10 +101,6 @@ export const traverseRichText = ({
 }) => {
   siblingData = siblingData ?? root
 
-  if (siblingData.text) {
-    onText(siblingData, 'text')
-  }
-
   if (siblingData.type === 'block') {
     if (
       'fields' in siblingData &&
@@ -58,17 +132,42 @@ export const traverseRichText = ({
     } else {
       console.warn('Could not find fields and blockType in block', siblingData)
     }
-  } else if (Array.isArray(siblingData?.children)) {
-    for (const child of siblingData.children) {
+
+    return
+  }
+
+  if (!Array.isArray(siblingData?.children)) {
+    return
+  }
+
+  const children = siblingData.children as Record<string, any>[]
+  let i = 0
+
+  while (i < children.length) {
+    const child = children[i]
+
+    if (child && typeof child.text === 'string') {
+      // Gather a maximal run of consecutive text nodes and translate them
+      // together so a sentence split across formatting spans stays aligned.
+      const run: Record<string, any>[] = []
+
+      while (i < children.length && children[i] && typeof children[i].text === 'string') {
+        run.push(children[i])
+        i++
+      }
+
+      pushTextRun(run, valuesToTranslate)
+    } else {
       traverseRichText({
         emptyOnly,
-        onText,
         payloadConfig,
         root,
         siblingData: child,
         translatedData,
         valuesToTranslate,
       })
+
+      i++
     }
   }
 }