failproofai 0.0.13 → 0.0.14-beta.0

package/scripts/postinstall.mjs

@@ -144,10 +144,9 @@ try {
 
 if (!hooksResult.configured && !hooksResult.registered) {
   console.log(
-    `\n[failproofai] Installed. Next steps:\n` +
-    `  1. Run \`failproofai policies --install\` to enable safety policies.\n` +
-    `  2. Run \`failproofai\` to open the dashboard (or just \`failproofai\` to start now — it'll offer to set up policies for you).\n` +
-    `  Disable first-run prompt: FAILPROOFAI_NO_FIRST_RUN=1\n`
+    `\n[failproofai] Installed ✓\n` +
+    `  👋 Hi! Run \`failproofai config\` to set it up.\n` +
+    `  (Disable this prompt: FAILPROOFAI_NO_FIRST_RUN=1)\n`
   );
 }
 

package/scripts/sync-agent-cli-harnesses-prompt.md

@@ -32,7 +32,6 @@ tracked in `src/hooks/types.ts` and written to disk by `src/hooks/integrations.t
 | Cursor Agent   | `CURSOR_HOOK_EVENT_TYPES`          | `CURSOR_EVENT_MAP`     | `.cursor/hooks.json` |
 | OpenCode       | `OPENCODE_HOOK_EVENT_TYPES`        | `OPENCODE_EVENT_MAP`   | `.opencode/opencode.json` + `.opencode/plugins/failproofai.mjs` |
 | Pi             | `PI_HOOK_EVENT_TYPES`              | `PI_EVENT_MAP`         | `.pi/settings.json` |
-| Gemini CLI     | `GEMINI_HOOK_EVENT_TYPES`          | `GEMINI_EVENT_MAP`     | `.gemini/settings.json` |
 
 ## What "drift" means — three scopes
 
@@ -62,7 +61,7 @@ For each verified CLI, compare the upstream docs to this repo across three scope
   when you only need to **inspect** a committed fixture, prefer
   `git show HEAD:<path>` (e.g. `git show HEAD:.codex/hooks.json`) — it is never
   blocked and is the reliable way to read `.claude/settings.json`, `.codex/hooks.json`,
-  `.cursor/hooks.json`, `.github/hooks/failproofai.json`, `.gemini/settings.json`,
+  `.cursor/hooks.json`, `.github/hooks/failproofai.json`,
   `.pi/settings.json`, and `.opencode/*`.
 - Do **NOT** run `failproofai policies --install` (or any `failproofai` subcommand)
   to regenerate a fixture — it is blocked. Edit fixtures by hand.
@@ -76,7 +75,7 @@ Spawn one subagent per CLI (seven, in parallel). Each subagent, for its CLI:
    **settings-file schema** (top-level keys, per-entry shape, command field name,
    timeout field name **and unit**, and whether `matcher` / `version` / `$schema`
    are present). **Use upstream casing exactly** — Codex snake_case, Cursor
-   camelCase, OpenCode dot.namespaced, Pi snake_case, Claude/Copilot/Gemini
+   camelCase, OpenCode dot.namespaced, Pi snake_case, Claude/Copilot
    PascalCase. Do **not** normalize.
 2. Compare against this repo: the CLI's `*HOOK_EVENT_TYPES` array + paired
    `*EVENT_MAP` (scope 1); its `*_TOOL_MAP` / `*_TOOL_INPUT_MAP` and its branch in
@@ -98,7 +97,6 @@ surface is documented in the package source, not a clean enumeration).
 | Cursor    | https://cursor.com/docs/hooks |
 | OpenCode  | https://opencode.ai/docs/plugins/ |
 | Pi        | https://www.npmjs.com/package/@mariozechner/pi-coding-agent |
-| Gemini    | https://geminicli.com/docs/hooks/ · https://geminicli.com/docs/reference/tools/ (tool names) |
 
 ## Phase 2 — Decide what to do (do this BEFORE editing any files)
 
@@ -122,7 +120,6 @@ changes that block a clean stop on the comment / no-op paths below.
 
      > This open sync PR is missing newly-detected drift:
      > - **Cursor**: upstream added event `afterEdit` — append to `CURSOR_HOOK_EVENT_TYPES` (+ a `CURSOR_EVENT_MAP` entry).
-     > - **Gemini**: the `run_shell_command` tool was renamed to `shell` — the `GEMINI_TOOL_MAP` key is stale.
      >
      > (hook-sync bot — please fold these into this PR rather than opening a second sync PR.)
 
@@ -140,7 +137,7 @@ requires.
 - **Append** new events just before `] as const`, preserving upstream casing.
 - **Delete** removed events; if the CLI has an `*EVENT_MAP`, also delete the same
   key from that map (the `Record` is exhaustive — a stale key fails `tsc`).
-- For **map-bearing CLIs** (Codex, Cursor, OpenCode, Pi, Gemini), do **NOT** invent
+- For **map-bearing CLIs** (Codex, Cursor, OpenCode, Pi), do **NOT** invent
   the canonical mapping for a newly-added event — leave it out of the `*EVENT_MAP`
   so `tsc` fails intentionally, and add a reviewer-checklist item to the PR body
   (see below). For **Claude and Copilot** (no map), the build stays green.
@@ -148,9 +145,9 @@ requires.
   - If `HOOK_EVENT_TYPES` (Claude) changed: in `__tests__/hooks/manager.test.ts`,
     update the `installs hooks for all <N> event types` description AND both
     `expect(Object.keys(written.hooks)).toHaveLength(<N>)` assertions.
-  - If `GEMINI_HOOK_EVENT_TYPES` changed: in `__tests__/hooks/integrations.test.ts`,
-    update the `expect(gemini.eventTypes).toHaveLength(<N>)` assertion AND the
-    matching description string.
+  - If a CLI's `*_HOOK_EVENT_TYPES` changed: in `__tests__/hooks/integrations.test.ts`,
+    update the matching `expect(<cli>.eventTypes).toHaveLength(<N>)` assertion AND the
+    description string.
   - Locate these by searching for the current count number.
 
 ### Scope 2 / Scope 3 (tool schema / settings-file shape)
@@ -211,7 +208,7 @@ The PR **body** must contain, in order:
   `__tests__/e2e/hooks/<cli>-integration.e2e.test.ts`, the seven dogfood fixtures
   (`.claude/settings.json`, `.codex/hooks.json`, `.cursor/hooks.json`,
   `.github/hooks/failproofai.json`, `.opencode/opencode.json`,
-  `.opencode/plugins/failproofai.mjs`, `.pi/settings.json`, `.gemini/settings.json`),
+  `.opencode/plugins/failproofai.mjs`, `.pi/settings.json`),
   and `CHANGELOG.md`.
 - Do **NOT** edit `.failproofai/policies-config.json` (the entrypoint manages it),
   `src/hooks/handler.ts`, `src/hooks/manager.ts`, or any other source file.

package/scripts/translate-docs/cli.ts

@@ -3,10 +3,19 @@ import { parseArgs } from "node:util";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
-import { LANGUAGES, getLanguagesByTier, getLanguageByCode, getModelForTier } from "./config";
+import {
+  LANGUAGES,
+  getLanguagesByTier,
+  getLanguageByCode,
+  getModelForTier,
+} from "./config";
 import { getEnglishMdxPages, translateMdxPage } from "./mdx-translator";
 import { translateReadme } from "./readme-translator";
-import { updateDocsJson, readDocsConfig } from "./mintlify-nav";
+import {
+  getNavigationPageReferences,
+  updateDocsJson,
+  readDocsConfig,
+} from "./mintlify-nav";
 import { readCache, writeCache, isCached, setCacheEntry } from "./cache";
 import type { TranslationResult } from "./types";
 
@@ -87,44 +96,14 @@ async function validateNavReferences(): Promise<boolean> {
   let total = 0;
   let missing = 0;
 
-  const languages = (nav.languages || []) as Array<{
-    language: string;
-    tabs: Array<{ groups: Array<{ pages: string[] }> }>;
-  }>;
-
-  if (languages.length === 0) {
-    // Flat tabs structure (not yet migrated to languages)
-    const tabs = (nav.tabs || []) as Array<{
-      groups: Array<{ pages: string[] }>;
-    }>;
-    for (const tab of tabs) {
-      for (const group of tab.groups) {
-        for (const page of group.pages) {
-          total++;
-          const filePath = join(DOCS_DIR, `${page}.mdx`);
-          if (!existsSync(filePath)) {
-            console.error(`  MISSING: ${page} -> ${filePath}`);
-            missing++;
-            valid = false;
-          }
-        }
-      }
-    }
-  } else {
-    for (const langEntry of languages) {
-      for (const tab of langEntry.tabs) {
-        for (const group of tab.groups) {
-          for (const page of group.pages) {
-            total++;
-            const filePath = join(DOCS_DIR, `${page}.mdx`);
-            if (!existsSync(filePath)) {
-              console.error(`  MISSING [${langEntry.language}]: ${page} -> ${filePath}`);
-              missing++;
-              valid = false;
-            }
-          }
-        }
-      }
+  for (const reference of getNavigationPageReferences(nav)) {
+    total++;
+    const filePath = join(DOCS_DIR, `${reference.page}.mdx`);
+    if (!existsSync(filePath)) {
+      const context = reference.language ? ` [${reference.language}]` : "";
+      console.error(`  MISSING${context}: ${reference.page} -> ${filePath}`);
+      missing++;
+      valid = false;
     }
   }
 
@@ -169,7 +148,9 @@ async function main() {
     `${isDryRun ? "[DRY RUN] " : ""}Translating into: ${langCodes.join(", ")}`,
   );
   if (!modelOverride) {
-    console.log(`Models: Tier 1 -> ${getModelForTier(1)}, Tier 2/3 -> ${getModelForTier(2)}`);
+    console.log(
+      `Models: Tier 1 -> ${getModelForTier(1)}, Tier 2/3 -> ${getModelForTier(2)}`,
+    );
   } else {
     console.log(`Model override: ${modelOverride}`);
   }
@@ -186,10 +167,17 @@ async function main() {
   // configured in translator.ts) to absorb per-request transient
   // `Connection error.` from LB-induced replica flapping.
   // Override via TRANSLATE_MAX_CONCURRENT (integer >= 1; otherwise default).
-  const parsedConcurrent = Number.parseInt(process.env.TRANSLATE_MAX_CONCURRENT ?? "", 10);
+  const parsedConcurrent = Number.parseInt(
+    process.env.TRANSLATE_MAX_CONCURRENT ?? "",
+    10,
+  );
   const MAX_CONCURRENT =
-    Number.isInteger(parsedConcurrent) && parsedConcurrent > 0 ? parsedConcurrent : 4;
-  async function runWithConcurrency<T>(tasks: (() => Promise<T>)[]): Promise<T[]> {
+    Number.isInteger(parsedConcurrent) && parsedConcurrent > 0
+      ? parsedConcurrent
+      : 4;
+  async function runWithConcurrency<T>(
+    tasks: (() => Promise<T>)[],
+  ): Promise<T[]> {
     const results: T[] = [];
     let i = 0;
     async function next(): Promise<void> {
@@ -198,7 +186,11 @@ async function main() {
         results[idx] = await tasks[idx]();
       }
     }
-    await Promise.all(Array.from({ length: Math.min(MAX_CONCURRENT, tasks.length) }, () => next()));
+    await Promise.all(
+      Array.from({ length: Math.min(MAX_CONCURRENT, tasks.length) }, () =>
+        next(),
+      ),
+    );
     return results;
   }
 
@@ -227,7 +219,11 @@ async function main() {
       for (const page of filteredPages) {
         const relPath = relative(DOCS_DIR, page);
         const task = { page, relPath, lang };
-        if (!isForce && !isDryRun && isCached(cache, relPath, lang, pageContents.get(page)!)) {
+        if (
+          !isForce &&
+          !isDryRun &&
+          isCached(cache, relPath, lang, pageContents.get(page)!)
+        ) {
           cachedTasks.push(task);
         } else {
           uncachedTasks.push(task);
@@ -235,7 +231,9 @@ async function main() {
       }
     }
 
-    console.log(`\n${filteredPages.length} MDX pages x ${langCodes.length} languages = ${filteredPages.length * langCodes.length} total`);
+    console.log(
+      `\n${filteredPages.length} MDX pages x ${langCodes.length} languages = ${filteredPages.length * langCodes.length} total`,
+    );
     console.log(`  Cached (unchanged): ${cachedTasks.length}`);
     console.log(`  Need translation: ${uncachedTasks.length}`);
 
@@ -268,7 +266,14 @@ async function main() {
             console.log(`  ${relPath} [${lang}] -> ${status}`);
             results.push(result);
             if (!result.cached && !isDryRun) {
-              setCacheEntry(cache, relPath, lang, pageContents.get(page)!, result.inputTokens, result.outputTokens);
+              setCacheEntry(
+                cache,
+                relPath,
+                lang,
+                pageContents.get(page)!,
+                result.inputTokens,
+                result.outputTokens,
+              );
             }
           } catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -285,10 +290,17 @@ async function main() {
     console.log(`\nTranslating README...`);
 
     // Read README once
-    const readmeSource = readFileSync(join(DOCS_DIR, "..", "README.md"), "utf-8");
+    const readmeSource = readFileSync(
+      join(DOCS_DIR, "..", "README.md"),
+      "utf-8",
+    );
     const uncachedLangs: string[] = [];
     for (const lang of langCodes) {
-      if (!isForce && !isDryRun && isCached(cache, "README.md", lang, readmeSource)) {
+      if (
+        !isForce &&
+        !isDryRun &&
+        isCached(cache, "README.md", lang, readmeSource)
+      ) {
         console.log(`  README.${lang}.md -> cached`);
         results.push({
           lang,
@@ -317,10 +329,19 @@ async function main() {
             const status = isDryRun
               ? "would translate"
               : `translated (${result.inputTokens}+${result.outputTokens} tokens)`;
-            console.log(`  README.${lang}.md -> ${langConfig.nativeName}: ${status}`);
+            console.log(
+              `  README.${lang}.md -> ${langConfig.nativeName}: ${status}`,
+            );
             results.push(result);
             if (!result.cached && !isDryRun) {
-              setCacheEntry(cache, "README.md", lang, readmeSource, result.inputTokens, result.outputTokens);
+              setCacheEntry(
+                cache,
+                "README.md",
+                lang,
+                readmeSource,
+                result.inputTokens,
+                result.outputTokens,
+              );
             }
           } catch (err) {
             const msg = err instanceof Error ? err.message : String(err);

package/scripts/translate-docs/config.ts

@@ -2,22 +2,60 @@ import type { LanguageConfig } from "./types";
 
 export const LANGUAGES: LanguageConfig[] = [
   // Tier 1 — largest developer populations
-  { code: "zh", name: "Chinese (Simplified)", nativeName: "\u7b80\u4f53\u4e2d\u6587", tier: 1 },
+  {
+    code: "zh",
+    name: "Chinese (Simplified)",
+    nativeName: "\u7b80\u4f53\u4e2d\u6587",
+    tier: 1,
+  },
   { code: "ja", name: "Japanese", nativeName: "\u65e5\u672c\u8a9e", tier: 1 },
   { code: "ko", name: "Korean", nativeName: "\ud55c\uad6d\uc5b4", tier: 1 },
   { code: "es", name: "Spanish", nativeName: "Espa\u00f1ol", tier: 1 },
-  { code: "pt-br", name: "Portuguese (Brazil)", nativeName: "Portugu\u00eas", tier: 1 },
+  {
+    code: "pt-br",
+    mintlifyCode: "pt-BR",
+    name: "Portuguese (Brazil)",
+    nativeName: "Portugu\u00eas",
+    tier: 1,
+  },
   { code: "de", name: "German", nativeName: "Deutsch", tier: 1 },
   { code: "fr", name: "French", nativeName: "Fran\u00e7ais", tier: 1 },
   // Tier 2 — strong tech communities
-  { code: "ru", name: "Russian", nativeName: "\u0420\u0443\u0441\u0441\u043a\u0438\u0439", tier: 2 },
-  { code: "hi", name: "Hindi", nativeName: "\u0939\u093f\u0928\u094d\u0926\u0940", tier: 2 },
+  {
+    code: "ru",
+    name: "Russian",
+    nativeName: "\u0420\u0443\u0441\u0441\u043a\u0438\u0439",
+    tier: 2,
+  },
+  {
+    code: "hi",
+    name: "Hindi",
+    nativeName: "\u0939\u093f\u0928\u094d\u0926\u0940",
+    tier: 2,
+  },
   { code: "tr", name: "Turkish", nativeName: "T\u00fcrk\u00e7e", tier: 2 },
-  { code: "vi", name: "Vietnamese", nativeName: "Ti\u1ebfng Vi\u1ec7t", tier: 2 },
+  {
+    code: "vi",
+    name: "Vietnamese",
+    nativeName: "Ti\u1ebfng Vi\u1ec7t",
+    tier: 2,
+  },
   { code: "it", name: "Italian", nativeName: "Italiano", tier: 2 },
   // Tier 3 — RTL languages
-  { code: "ar", name: "Arabic", nativeName: "\u0627\u0644\u0639\u0631\u0628\u064a\u0629", tier: 3, rtl: true },
-  { code: "he", name: "Hebrew", nativeName: "\u05e2\u05d1\u05e8\u05d9\u05ea", tier: 3, rtl: true },
+  {
+    code: "ar",
+    name: "Arabic",
+    nativeName: "\u0627\u0644\u0639\u0631\u0628\u064a\u0629",
+    tier: 3,
+    rtl: true,
+  },
+  {
+    code: "he",
+    name: "Hebrew",
+    nativeName: "\u05e2\u05d1\u05e8\u05d9\u05ea",
+    tier: 3,
+    rtl: true,
+  },
 ];
 
 export function getLanguagesByTier(maxTier: number): LanguageConfig[] {
@@ -184,17 +222,21 @@ export const NAV_TRANSLATIONS: Record<
   ru: {
     docs: "\u0414\u043e\u043a\u0443\u043c\u0435\u043d\u0442\u0430\u0446\u0438\u044f",
     examples: "\u041f\u0440\u0438\u043c\u0435\u0440\u044b",
-    gettingStarted: "\u041d\u0430\u0447\u0430\u043b\u043e \u0440\u0430\u0431\u043e\u0442\u044b",
-    coreConcepts: "\u041e\u0441\u043d\u043e\u0432\u043d\u044b\u0435 \u043a\u043e\u043d\u0446\u0435\u043f\u0446\u0438\u0438",
+    gettingStarted:
+      "\u041d\u0430\u0447\u0430\u043b\u043e \u0440\u0430\u0431\u043e\u0442\u044b",
+    coreConcepts:
+      "\u041e\u0441\u043d\u043e\u0432\u043d\u044b\u0435 \u043a\u043e\u043d\u0446\u0435\u043f\u0446\u0438\u0438",
     cli: "CLI",
     tools: "\u0418\u043d\u0441\u0442\u0440\u0443\u043c\u0435\u043d\u0442\u044b",
-    advanced: "\u041f\u0440\u043e\u0434\u0432\u0438\u043d\u0443\u0442\u044b\u0439",
+    advanced:
+      "\u041f\u0440\u043e\u0434\u0432\u0438\u043d\u0443\u0442\u044b\u0439",
   },
   hi: {
     docs: "\u0926\u0938\u094d\u0924\u093e\u0935\u0947\u091c\u093c",
     examples: "\u0909\u0926\u093e\u0939\u0930\u0923",
     gettingStarted: "\u0936\u0941\u0930\u0942 \u0915\u0930\u0947\u0902",
-    coreConcepts: "\u092e\u0942\u0932 \u0905\u0935\u0927\u093e\u0930\u0923\u093e\u090f\u0901",
+    coreConcepts:
+      "\u092e\u0942\u0932 \u0905\u0935\u0927\u093e\u0930\u0923\u093e\u090f\u0901",
     cli: "CLI",
     tools: "\u0909\u092a\u0915\u0930\u0923",
     advanced: "\u0909\u0928\u094d\u0928\u0924",
@@ -230,7 +272,8 @@ export const NAV_TRANSLATIONS: Record<
     docs: "\u0627\u0644\u0645\u0633\u062a\u0646\u062f\u0627\u062a",
     examples: "\u0623\u0645\u062b\u0644\u0629",
     gettingStarted: "\u0627\u0644\u0628\u062f\u0627\u064a\u0629",
-    coreConcepts: "\u0627\u0644\u0645\u0641\u0627\u0647\u064a\u0645 \u0627\u0644\u0623\u0633\u0627\u0633\u064a\u0629",
+    coreConcepts:
+      "\u0627\u0644\u0645\u0641\u0627\u0647\u064a\u0645 \u0627\u0644\u0623\u0633\u0627\u0633\u064a\u0629",
     cli: "CLI",
     tools: "\u0627\u0644\u0623\u062f\u0648\u0627\u062a",
     advanced: "\u0645\u062a\u0642\u062f\u0645",
@@ -238,7 +281,8 @@ export const NAV_TRANSLATIONS: Record<
   he: {
     docs: "\u05ea\u05d9\u05e2\u05d5\u05d3",
     examples: "\u05d3\u05d5\u05d2\u05de\u05d0\u05d5\u05ea",
-    gettingStarted: "\u05ea\u05d7\u05d9\u05dc\u05ea \u05e2\u05d1\u05d5\u05d3\u05d4",
+    gettingStarted:
+      "\u05ea\u05d7\u05d9\u05dc\u05ea \u05e2\u05d1\u05d5\u05d3\u05d4",
     coreConcepts: "\u05de\u05d5\u05e9\u05d2\u05d9 \u05d9\u05e1\u05d5\u05d3",
     cli: "CLI",
     tools: "\u05db\u05dc\u05d9\u05dd",

package/scripts/translate-docs/mdx-translator.ts

@@ -1,14 +1,15 @@
-import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import {
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  readdirSync,
+  statSync,
+} from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getLanguageByCode } from "./config";
 import { translateContent } from "./translator";
-import {
-  readCache,
-  writeCache,
-  isCached,
-  setCacheEntry,
-} from "./cache";
+import { readCache, writeCache, isCached, setCacheEntry } from "./cache";
 import type { TranslationResult, TranslationCache } from "./types";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -98,28 +99,23 @@ export function stripStrayTrailingFence(content: string): string {
  * e.g. href="/built-in-policies" -> href="/es/built-in-policies"
  *      [Getting started](/getting-started) -> [Getting started](/es/getting-started)
  */
-export function rewriteInternalLinks(
-  content: string,
-  lang: string,
-): string {
+export function rewriteInternalLinks(content: string, lang: string): string {
+  const shouldPreservePath = (path: string): boolean =>
+    path.startsWith("/http") ||
+    path === "/" ||
+    /\.(?:png|jpe?g|gif|svg|webp|ico)(?:#.*)?$/i.test(path);
+
   // Rewrite MDX component href attributes pointing to internal paths
-  let result = content.replace(
-    /href="(\/[^"]*?)"/g,
-    (_match, path: string) => {
-      // Skip external URLs and anchors
-      if (path.startsWith("/http") || path === "/") return `href="${path}"`;
-      return `href="/${lang}${path}"`;
-    },
-  );
+  let result = content.replace(/href="(\/[^"]*?)"/g, (_match, path: string) => {
+    if (shouldPreservePath(path)) return `href="${path}"`;
+    return `href="/${lang}${path}"`;
+  });
 
   // Rewrite Markdown links with internal paths
-  result = result.replace(
-    /\]\((\/[^)]*?)\)/g,
-    (_match, path: string) => {
-      if (path.startsWith("/http") || path === "/") return `](${path})`;
-      return `](/${lang}${path})`;
-    },
-  );
+  result = result.replace(/\]\((\/[^)]*?)\)/g, (_match, path: string) => {
+    if (shouldPreservePath(path)) return `](${path})`;
+    return `](/${lang}${path})`;
+  });
 
   return result;
 }
@@ -130,7 +126,12 @@ export function rewriteInternalLinks(
 export async function translateMdxPage(
   sourcePath: string,
   lang: string,
-  options: { force?: boolean; dryRun?: boolean; model?: string; cache?: TranslationCache } = {},
+  options: {
+    force?: boolean;
+    dryRun?: boolean;
+    model?: string;
+    cache?: TranslationCache;
+  } = {},
 ): Promise<TranslationResult> {
   const relPath = relative(DOCS_DIR, sourcePath);
   const outputPath = join(DOCS_DIR, lang, relPath);
@@ -186,7 +187,14 @@ export async function translateMdxPage(
   // Update cache — skip if caller manages the cache (batch write)
   if (!options.cache) {
     const cache = readCache();
-    setCacheEntry(cache, relPath, lang, sourceContent, inputTokens, outputTokens);
+    setCacheEntry(
+      cache,
+      relPath,
+      lang,
+      sourceContent,
+      inputTokens,
+      outputTokens,
+    );
     writeCache(cache);
   }
 
@@ -213,7 +221,7 @@ export function getEnglishMdxPages(): string[] {
       if (statSync(full).isDirectory()) {
         // Skip language directories at the top level
         if (!prefix && isLanguageDir(entry)) continue;
-        // Skip non-doc directories like logo, i18n
+        // Skip non-page asset and localization directories.
         if (!prefix && (entry === "logo" || entry === "i18n")) continue;
         walk(full, rel);
       } else if (entry.endsWith(".mdx")) {
@@ -228,8 +236,20 @@ export function getEnglishMdxPages(): string[] {
 
 function isLanguageDir(name: string): boolean {
   const langCodes = [
-    "zh", "ja", "ko", "es", "pt-br", "de", "fr",
-    "ru", "hi", "tr", "vi", "it", "ar", "he",
+    "zh",
+    "ja",
+    "ko",
+    "es",
+    "pt-br",
+    "de",
+    "fr",
+    "ru",
+    "hi",
+    "tr",
+    "vi",
+    "it",
+    "ar",
+    "he",
   ];
   return langCodes.includes(name);
 }

package/scripts/translate-docs/mintlify-nav.ts

@@ -1,7 +1,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { NAV_TRANSLATIONS, LANGUAGES } from "./config";
+import { getLanguageByCode, NAV_TRANSLATIONS, LANGUAGES } from "./config";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DOCS_JSON_PATH = join(__dirname, "..", "..", "docs", "docs.json");
@@ -21,6 +21,57 @@ interface LanguageNav {
   tabs: NavTab[];
 }
 
+export interface NavigationPageReference {
+  page: string;
+  language?: string;
+}
+
+/** Collect page references from flat, localized, or multi-product navigation. */
+export function getNavigationPageReferences(
+  navigation: unknown,
+): NavigationPageReference[] {
+  const references: NavigationPageReference[] = [];
+  const childKeys = [
+    "products",
+    "languages",
+    "tabs",
+    "groups",
+    "anchors",
+    "dropdowns",
+    "versions",
+    "menu",
+  ];
+
+  function walk(value: unknown, inheritedLanguage?: string): void {
+    if (Array.isArray(value)) {
+      for (const item of value) walk(item, inheritedLanguage);
+      return;
+    }
+    if (!value || typeof value !== "object") return;
+
+    const entry = value as Record<string, unknown>;
+    const language =
+      typeof entry.language === "string" ? entry.language : inheritedLanguage;
+
+    if (Array.isArray(entry.pages)) {
+      for (const page of entry.pages) {
+        if (typeof page === "string") {
+          references.push({ page, language });
+        } else {
+          walk(page, language);
+        }
+      }
+    }
+
+    for (const key of childKeys) {
+      if (key !== "pages" && entry[key]) walk(entry[key], language);
+    }
+  }
+
+  walk(navigation);
+  return references;
+}
+
 /**
  * Build a navigation entry for a specific language by transforming the
  * English navigation structure.
@@ -54,7 +105,10 @@ export function buildLanguageNav(
     })),
   }));
 
-  return { language: lang, tabs };
+  return {
+    language: getLanguageByCode(lang)?.mintlifyCode ?? lang,
+    tabs,
+  };
 }
 
 /**
@@ -78,6 +132,28 @@ export function generateLanguagesArray(
   return [english, ...others];
 }
 
+/** Localize every product that has English tabs or an English language entry. */
+export function localizeProductsNavigation(
+  products: unknown[],
+  langCodes: string[],
+): Record<string, unknown>[] {
+  return products.map((value) => {
+    const product = value as Record<string, unknown>;
+    const existingLanguages = product.languages as LanguageNav[] | undefined;
+    const englishTabs = existingLanguages
+      ? existingLanguages.find((entry) => entry.language === "en")?.tabs
+      : (product.tabs as NavTab[] | undefined);
+
+    if (!englishTabs) return product;
+
+    const { tabs: _tabs, ...rest } = product;
+    return {
+      ...rest,
+      languages: generateLanguagesArray(englishTabs, langCodes),
+    };
+  });
+}
+
 /**
  * Update docs.json to use the languages array structure.
  */
@@ -85,18 +161,23 @@ export function updateDocsJson(langCodes: string[]): void {
   const config = readDocsConfig();
   const nav = config.navigation as Record<string, unknown>;
 
-  // Extract existing English tabs
-  const englishTabs = nav.tabs as NavTab[];
-  if (!englishTabs) {
-    throw new Error("docs.json navigation.tabs not found — is this already using the languages format?");
+  if (Array.isArray(nav.products)) {
+    nav.products = localizeProductsNavigation(nav.products, langCodes);
+    config.navigation = nav;
+    writeFileSync(DOCS_JSON_PATH, JSON.stringify(config, null, 2) + "\n");
+    return;
   }
 
-  // Build languages array
-  const languages = generateLanguagesArray(englishTabs, langCodes);
+  const existingLanguages = nav.languages as LanguageNav[] | undefined;
+  const englishTabs = existingLanguages
+    ? existingLanguages.find((entry) => entry.language === "en")?.tabs
+    : (nav.tabs as NavTab[] | undefined);
+  if (!englishTabs) {
+    throw new Error("No English navigation tabs found in docs.json");
+  }
 
-  // Replace tabs with languages, preserve global
   const newNav: Record<string, unknown> = {
-    languages,
+    languages: generateLanguagesArray(englishTabs, langCodes),
   };
   if (nav.global) {
     newNav.global = nav.global;

package/scripts/translate-docs/types.ts

@@ -1,5 +1,8 @@
 export interface LanguageConfig {
+  /** Internal code used for folders, cache keys, and translation routing. */
   code: string;
+  /** Mintlify locale when its canonical casing differs from `code`. */
+  mintlifyCode?: string;
   name: string;
   nativeName: string;
   tier: 1 | 2 | 3;