fix(translation): resolve workflow stale-scripts, schema, and undefined-content bugs

Three bugs found in the translate-docs workflow and translation scripts:

1. Workflow always ran scripts from the `content` branch, which had an
   older version of translateFrontMatter.ts with `type: "string"` in the
   OpenAI response schema instead of `type: "object"`, causing 400 errors.
   Fix: overlay scripts/ and package.json from main before bun i, then
   immediately unstage them (git restore --staged) so they are not
   accidentally committed to the content branch.

2. translateCodeJson.ts used CodeJsonSchema with additionalProperties as
   a schema object combined with strict: true, which OpenAI Structured
   Outputs forbids (additionalProperties must be false in strict mode).
   Fix: switch to response_format { type: "json_object" } — appropriate
   since code.json has dynamic/unknown keys.

3. removeFrontMatter and createNotionPageFromMarkdown had no guard
   against receiving undefined content (possible when an older caller
   caught a translation error but continued with undefined translatedContent).
   Fix: type guard in removeFrontMatter returns "" for non-strings;
   createNotionPageFromMarkdown throws with a clear diagnostic message.

Author: luandro

.github/workflows/translate-docs.yml

@@ -29,6 +29,12 @@ jobs:
         with:
           ref: ${{ env.TARGET_BRANCH }}
 
+      - name: Apply latest scripts from main
+        run: |
+          git fetch origin main --depth=1
+          git checkout origin/main -- scripts/ package.json
+          git restore --staged scripts/ package.json
+
       - name: Setup Bun
         uses: oven-sh/setup-bun@735343b667d3e6f658f44d0eca948eb6282f2b76 # v2.0.2
 

scripts/notion-translate/markdownToNotion.ts

@@ -488,6 +488,7 @@ type NotionCodeLanguage =
  * @returns The markdown content without front-matter
  */
 export function removeFrontMatter(content: string): string {
+  if (typeof content !== "string") return "";
   // Check if content starts with front-matter (---)
   const frontMatterRegex = /^---\n[\s\S]*?\n---\n/m;
   return content.replace(frontMatterRegex, "");
@@ -562,6 +563,12 @@ export async function createNotionPageFromMarkdown(
         ? markdownPath
         : await fs.readFile(markdownPath, "utf8");
 
+      if (typeof markdownContent !== "string") {
+        throw new Error(
+          `Invalid content for page "${title}": expected string, got ${typeof markdownContent}`
+        );
+      }
+
       // Remove front-matter if present
       markdownContent = removeFrontMatter(markdownContent);
 

scripts/notion-translate/translateCodeJson.ts

@@ -66,30 +66,6 @@ export async function translateJson(
     targetLanguage
   );
 
-  // JSON schema for code.json translation
-  // Requires both "message" and "description" fields (standard Docusaurus i18n format)
-  // Structure:
-  // {
-  //   "Some Key": {
-  //     "message": "Some message",
-  //     "description": "Some description"
-  //   },
-  //   ...
-  // }
-  const CodeJsonSchema = {
-    type: "object",
-    properties: {},
-    additionalProperties: {
-      type: "object",
-      properties: {
-        message: { type: "string" },
-        description: { type: "string" },
-      },
-      required: ["message", "description"],
-      additionalProperties: false,
-    },
-  };
-
   // Get model-specific parameters (handles GPT-5 temperature constraints)
   // For GPT-5.2, use reasoning_effort="none" to allow custom temperature
   const modelParams = getModelParams(model, { useReasoningNone: true });
@@ -101,14 +77,9 @@ export async function translateJson(
         { role: "system", content: prompt },
         { role: "user", content: jsonContent },
       ],
-      response_format: {
-        type: "json_schema",
-        json_schema: {
-          name: "translation",
-          schema: CodeJsonSchema,
-          strict: true,
-        },
-      },
+      // Use json_object format: code.json has dynamic keys so a strict schema
+      // cannot be defined (OpenAI strict mode forbids additionalProperties schemas).
+      response_format: { type: "json_object" },
       ...modelParams,
     });