failproofai 0.0.14-beta.0 → 0.0.14-beta.2

package/scripts/install-telemetry.mjs

@@ -80,12 +80,20 @@ function getInstanceId() {
 
 /**
  * Track a named event to PostHog. No-op when telemetry is disabled.
- * Uses process.env.npm_package_version (set automatically by npm in lifecycle scripts).
+ *
+ * `opts.version` must be supplied by callers outside an npm lifecycle script:
+ * npm only sets npm_package_version while running one, and these events now
+ * fire from the CLI (see lib/install-check.ts) because package managers block
+ * install scripts by default.
+ *
+ * @param {string} event
+ * @param {Record<string, unknown>} [properties]
+ * @param {{ version?: string, timeoutMs?: number }} [opts]
  */
-export async function trackInstallEvent(event, properties = {}) {
+export async function trackInstallEvent(event, properties = {}, opts = {}) {
   if (process.env.FAILPROOFAI_TELEMETRY_DISABLED === "1") return;
 
-  const version = process.env.npm_package_version ?? "unknown";
+  const version = opts.version ?? process.env.npm_package_version ?? "unknown";
   const body = JSON.stringify({
     api_key: process.env.FAILPROOFAI_POSTHOG_KEY ?? API_KEY,
     event,
@@ -106,7 +114,7 @@ export async function trackInstallEvent(event, properties = {}) {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body,
-      signal: AbortSignal.timeout(5000),
+      signal: AbortSignal.timeout(opts.timeoutMs ?? 5000),
     }
   );
 }

package/scripts/translate-docs/cli.ts

@@ -9,7 +9,11 @@ import {
   getLanguageByCode,
   getModelForTier,
 } from "./config";
-import { getEnglishMdxPages, translateMdxPage } from "./mdx-translator";
+import {
+  getEnglishMdxPages,
+  translateMdxPage,
+  pruneOrphanedTranslations,
+} from "./mdx-translator";
 import { translateReadme } from "./readme-translator";
 import {
   getNavigationPageReferences,
@@ -33,6 +37,8 @@ const { values: args } = parseArgs({
     force: { type: "boolean", short: "f", default: false },
     "update-nav": { type: "boolean", default: false },
     validate: { type: "boolean", default: false },
+    prune: { type: "boolean", default: false },
+    "no-prune": { type: "boolean", default: false },
     model: { type: "string", short: "m" },
     help: { type: "boolean", short: "h", default: false },
   },
@@ -53,6 +59,8 @@ Options:
   -f, --force              Ignore cache, re-translate everything
       --update-nav         Regenerate docs.json navigation after translation
       --validate           Check all nav references resolve to files
+      --prune              Only delete translations whose English source is gone
+      --no-prune           Skip the prune step during a normal translation run
   -m, --model <model>      Claude model override (default: Sonnet for Tier 1, Haiku for Tier 2/3)
   -h, --help               Show this help
 
@@ -65,6 +73,7 @@ Examples:
   bun scripts/translate-docs/cli.ts --dry-run --tier 3    # Preview all translations
   bun scripts/translate-docs/cli.ts --validate            # Check nav references
   bun scripts/translate-docs/cli.ts --update-nav          # Regenerate docs.json
+  bun scripts/translate-docs/cli.ts --prune --tier 3      # Drop orphaned translations
 `);
   process.exit(0);
 }
@@ -132,6 +141,26 @@ async function main() {
     return;
   }
 
+  // Prune-only mode
+  if (args.prune) {
+    const langCodes = resolveLanguages();
+    const cache = readCache();
+    const pruned = pruneOrphanedTranslations(langCodes, {
+      dryRun: args["dry-run"],
+      cache,
+    });
+    for (const file of pruned) {
+      console.log(
+        `  ${args["dry-run"] ? "would remove" : "removed"}: ${file}`,
+      );
+    }
+    if (pruned.length > 0 && !args["dry-run"]) writeCache(cache);
+    console.log(
+      `\n${pruned.length} orphaned translation(s)${args["dry-run"] ? " would be" : ""} removed.`,
+    );
+    return;
+  }
+
   const langCodes = resolveLanguages();
   const isDryRun = args["dry-run"];
   const isForce = args.force;
@@ -196,6 +225,23 @@ async function main() {
 
   // Translate docs
   if (!args["readme-only"]) {
+    // Drop translations orphaned by an upstream English deletion before
+    // translating, so a stale locale page can never outlive its source.
+    if (!args["no-prune"]) {
+      const pruned = pruneOrphanedTranslations(langCodes, {
+        dryRun: isDryRun,
+        cache,
+      });
+      for (const file of pruned) {
+        console.log(`  ${isDryRun ? "would prune" : "pruned"}: ${file}`);
+      }
+      if (pruned.length > 0) {
+        console.log(
+          `${pruned.length} orphaned translation(s)${isDryRun ? " would be" : ""} removed.`,
+        );
+      }
+    }
+
     const pages = getEnglishMdxPages();
     const filteredPages = args.pages
       ? pages.filter((p) => {
@@ -373,6 +419,12 @@ async function main() {
   if (totalInput > 0) {
     console.log(`Total tokens: ${totalInput} input + ${totalOutput} output`);
   }
+  // Surface pages that needed a re-translation to pass validation, so a run
+  // that quietly retried does not read as a clean one in the job log.
+  const retried = translated.filter((r) => (r.attempts ?? 1) > 1);
+  if (retried.length > 0) {
+    console.log(`Retried: ${retried.length}`);
+  }
 
   if (errors.length > 0) {
     process.exit(1);

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

@@ -4,12 +4,21 @@ import {
   mkdirSync,
   readdirSync,
   statSync,
+  existsSync,
+  rmSync,
 } 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 { translateValidated } from "./translator";
+import { findTranslationError } from "./validate-translation";
+import {
+  readCache,
+  writeCache,
+  isCached,
+  setCacheEntry,
+  getCacheKey,
+} from "./cache";
 import type { TranslationResult, TranslationCache } from "./types";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -94,6 +103,60 @@ export function stripStrayTrailingFence(content: string): string {
   return lines.join("\n");
 }
 
+/**
+ * Convert HTML comments (`<!-- ... -->`) into MDX brace-slash-star comments.
+ *
+ * Mintlify parses every page as MDX, where a top-level HTML comment is a hard
+ * syntax error ("Unexpected character `!` (U+0021) before name …") that fails
+ * the whole deployment — the remedy Mintlify itself suggests is switching to
+ * MDX's own comment form. The root README keeps HTML-comment syntax (GitHub
+ * renders it invisibly), so its translated copies under docs/i18n/ have to be
+ * rewritten to the MDX form or the docs deploy breaks.
+ *
+ * Comments inside fenced code blocks are left untouched — there `<!-- -->` is
+ * literal sample text (e.g. the plist snippet in the AgentEye collector docs),
+ * not a comment to convert. Any `*`+`/` sequence inside a body is broken up so
+ * the generated JS block comment can't be terminated early.
+ */
+export function convertHtmlComments(content: string): string {
+  // Map out fenced-code ranges so comments inside them stay literal. Per
+  // CommonMark, a fence opens with ≥3 backticks or tildes and closes only on a
+  // later line using the SAME character and at least the same length. A naive
+  // "any ``` toggles" counter misfires on a ```` block that embeds ``` or on
+  // mixed ```/~~~ fences — the toggle desyncs and a real top-level comment
+  // after the block would be left unconverted (breaking the deploy we fix here).
+  const fenceRanges: Array<[number, number]> = [];
+  const fenceRe = /^[ \t]*(`{3,}|~{3,})/gm;
+  let fenceMatch: RegExpExecArray | null;
+  let open: { char: string; length: number; start: number } | null = null;
+  while ((fenceMatch = fenceRe.exec(content)) !== null) {
+    const marker = fenceMatch[1];
+    if (!open) {
+      open = { char: marker[0], length: marker.length, start: fenceMatch.index };
+    } else if (marker[0] === open.char && marker.length >= open.length) {
+      const lineEnd = content.indexOf("\n", fenceRe.lastIndex);
+      fenceRanges.push([open.start, lineEnd === -1 ? content.length : lineEnd]);
+      open = null;
+    }
+    // A different char or shorter marker while a fence is open is inner content.
+  }
+  // An unterminated fence runs to the end of the document.
+  if (open) fenceRanges.push([open.start, content.length]);
+
+  const isInsideFence = (offset: number): boolean =>
+    fenceRanges.some(([start, end]) => offset >= start && offset < end);
+
+  return content.replace(
+    /<!--([\s\S]*?)-->/g,
+    (match: string, body: string, offset: number) => {
+      if (isInsideFence(offset)) return match;
+      // Neutralize any `*/` so it can't close the JS block comment early.
+      const safeBody = body.replace(/\*\//g, "* /");
+      return `{/*${safeBody}*/}`;
+    },
+  );
+}
+
 /**
  * Rewrite internal doc links to include the language prefix.
  * e.g. href="/built-in-policies" -> href="/es/built-in-policies"
@@ -131,10 +194,13 @@ export async function translateMdxPage(
     dryRun?: boolean;
     model?: string;
     cache?: TranslationCache;
+    /** Override the docs root. Tests point this at a fixture tree. */
+    docsDir?: string;
   } = {},
 ): Promise<TranslationResult> {
-  const relPath = relative(DOCS_DIR, sourcePath);
-  const outputPath = join(DOCS_DIR, lang, relPath);
+  const docsDir = options.docsDir ?? DOCS_DIR;
+  const relPath = relative(docsDir, sourcePath);
+  const outputPath = join(docsDir, lang, relPath);
   const sourceContent = readFileSync(sourcePath, "utf-8");
 
   const langConfig = getLanguageByCode(lang);
@@ -166,23 +232,31 @@ export async function translateMdxPage(
     };
   }
 
-  // Translate
-  const { translated, inputTokens, outputTokens } = await translateContent(
-    sourceContent,
-    lang,
-    langConfig.name,
-    options.model,
-  );
-
-  // Strip stray quote artifacts from JSX attribute values, drop any
-  // unmatched trailing code fence the model sometimes hallucinates, then
-  // rewrite links.
-  const sanitized = stripStrayTrailingFence(sanitizeJsxAttributes(translated));
-  const withLinks = rewriteInternalLinks(sanitized, lang);
+  // Translate and validate the exact bytes we will write. The render callback
+  // reproduces the historical sanitize + link-rewrite chain byte-for-byte
+  // (strip stray JSX-attribute quotes, drop an unmatched trailing fence,
+  // convert HTML comments to MDX, then add the language prefix to links), so
+  // the validated bytes ARE the written bytes and a pass here equals a pass in
+  // the deploy. On exhaustion translateValidated throws before we reach the
+  // write, so an invalid page is never written or cached.
+  const { rendered, inputTokens, outputTokens, attempts } =
+    await translateValidated({
+      source: sourceContent,
+      lang,
+      langName: langConfig.name,
+      model: options.model,
+      label: `${relPath} [${lang}]`,
+      render: (raw) =>
+        rewriteInternalLinks(
+          convertHtmlComments(stripStrayTrailingFence(sanitizeJsxAttributes(raw))),
+          lang,
+        ),
+      validate: (bytes) => findTranslationError(bytes, sourceContent),
+    });
 
   // Write output
   mkdirSync(dirname(outputPath), { recursive: true });
-  writeFileSync(outputPath, withLinks);
+  writeFileSync(outputPath, rendered);
 
   // Update cache — skip if caller manages the cache (batch write)
   if (!options.cache) {
@@ -205,6 +279,7 @@ export async function translateMdxPage(
     inputTokens,
     outputTokens,
     cached: false,
+    attempts,
   };
 }
 
@@ -234,6 +309,71 @@ export function getEnglishMdxPages(): string[] {
   return results.sort();
 }
 
+/** Every `.mdx` file under `dir`, recursively. */
+function collectMdxFiles(dir: string): string[] {
+  const results: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      results.push(...collectMdxFiles(full));
+    } else if (entry.endsWith(".mdx")) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/**
+ * Delete translated pages whose English source no longer exists, and drop
+ * their cache entries.
+ *
+ * Translation only ever moves forward: `getEnglishMdxPages()` drives what gets
+ * written, so when an English page is deleted upstream (the agenteye sync does
+ * this routinely) its 14 translations are simply never revisited. They linger
+ * on disk and `--update-nav` drops them from `docs.json`, which hides them from
+ * the sidebar but does *not* unpublish them — Mintlify still serves and indexes
+ * any `.mdx` present, so non-English readers can land on a page documenting a
+ * removed feature with no navigation out. Left unpruned these also accumulate
+ * as permanent `validate:mdx` surface area for content no English source can
+ * ever correct.
+ *
+ * Returns the docs-dir-relative paths that were (or, when `dryRun`, would be)
+ * removed.
+ */
+export function pruneOrphanedTranslations(
+  langCodes: string[],
+  options: {
+    dryRun?: boolean;
+    cache?: TranslationCache;
+    /** Override the docs root. Tests point this at a fixture tree. */
+    docsDir?: string;
+  } = {},
+): string[] {
+  const docsDir = options.docsDir ?? DOCS_DIR;
+  const removed: string[] = [];
+
+  for (const lang of langCodes) {
+    const langDir = join(docsDir, lang);
+    if (!existsSync(langDir)) continue;
+
+    for (const file of collectMdxFiles(langDir)) {
+      // docs/zh/agenteye/foo.mdx -> agenteye/foo.mdx -> docs/agenteye/foo.mdx
+      const relPath = relative(langDir, file);
+      if (existsSync(join(docsDir, relPath))) continue;
+
+      removed.push(relative(docsDir, file));
+      if (!options.dryRun) {
+        rmSync(file);
+        if (options.cache) {
+          delete options.cache.translations[getCacheKey(relPath, lang)];
+        }
+      }
+    }
+  }
+
+  return removed.sort();
+}
+
 function isLanguageDir(name: string): boolean {
   const langCodes = [
     "zh",

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

@@ -2,8 +2,13 @@ import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { LANGUAGES, getLanguageByCode } from "./config";
-import { translateContent } from "./translator";
-import { stripStrayTrailingFence } from "./mdx-translator";
+import { translateValidated } from "./translator";
+import {
+  stripStrayTrailingFence,
+  convertHtmlComments,
+  sanitizeJsxAttributes,
+} from "./mdx-translator";
+import { findTranslationError } from "./validate-translation";
 import { readCache, writeCache, isCached, setCacheEntry } from "./cache";
 import type { TranslationResult, TranslationCache } from "./types";
 
@@ -86,15 +91,12 @@ export async function translateReadme(
     };
   }
 
-  // Translate
-  const { translated, inputTokens, outputTokens } = await translateContent(
-    sourceContent,
-    lang,
-    langConfig.name,
-    options.model,
-  );
-
-  // Build the final output with header
+  // Compute the wrapper (disclaimer, language selector, RTL <div>) up front so
+  // the render callback can assemble the FINAL bytes on every attempt. The
+  // assembled bytes — not the raw model output — are what gets validated: the
+  // swallowed-`</div>` class is introduced by the wrapper AFTER the model
+  // returns, and `mintlify validate` never sees the README at all, so this gate
+  // is the only thing standing between a broken README and the deploy.
   const disclaimer = langConfig.rtl
     ? `> **\u26a0\ufe0f** \u0647\u0630\u0647 \u062a\u0631\u062c\u0645\u0629 \u0622\u0644\u064a\u0629. \u0644\u0644\u0627\u0637\u0644\u0627\u0639 \u0639\u0644\u0649 \u0623\u062d\u062f\u062b \u0625\u0635\u062f\u0627\u0631\u060c \u0631\u0627\u062c\u0639 [English README](../../README.md).`
     : `> **\u26a0\ufe0f** This is an auto-generated translation. For the latest version, see the [English README](../../README.md). Community corrections welcome!`;
@@ -103,16 +105,31 @@ export async function translateReadme(
   const rtlOpen = langConfig.rtl ? `<div dir="rtl">\n\n` : "";
   const rtlClose = langConfig.rtl ? `\n\n</div>` : "";
 
-  // Drop any stray trailing fence the model hallucinated — would otherwise
-  // open an unclosed code block that swallows the wrapping `</div>` for RTL
-  // pages and break Mintlify's MDX parser.
-  const cleaned = stripStrayTrailingFence(translated);
-
-  const output = `${disclaimer}\n\n${langSelector}\n\n---\n${rtlOpen}\n${cleaned}\n${rtlClose}`;
+  // Translate and validate the assembled bytes, re-translating on failure.
+  const { rendered, inputTokens, outputTokens, attempts } =
+    await translateValidated({
+      source: sourceContent,
+      lang,
+      langName: langConfig.name,
+      model: options.model,
+      label: `README.${lang}.md`,
+      render: (raw) => {
+        // Same MDX sanitizers as translateMdxPage — the README emits JSX (the
+        // logo table), so strip stray attribute quotes, drop any unmatched
+        // trailing code fence (which would swallow the RTL `</div>`), and
+        // convert HTML comments to MDX — then wrap in disclaimer + selector +
+        // RTL div.
+        const cleaned = convertHtmlComments(
+          stripStrayTrailingFence(sanitizeJsxAttributes(raw)),
+        );
+        return `${disclaimer}\n\n${langSelector}\n\n---\n${rtlOpen}\n${cleaned}\n${rtlClose}`;
+      },
+      validate: (bytes) => findTranslationError(bytes, sourceContent),
+    });
 
   // Write output
   mkdirSync(I18N_DIR, { recursive: true });
-  writeFileSync(outputPath, output);
+  writeFileSync(outputPath, rendered);
 
   // Update cache — skip if caller manages the cache (batch write)
   if (!options.cache) {
@@ -128,6 +145,7 @@ export async function translateReadme(
     inputTokens,
     outputTokens,
     cached: false,
+    attempts,
   };
 }
 

package/scripts/translate-docs/translator.ts

@@ -3,6 +3,47 @@ import { DO_NOT_TRANSLATE } from "./config";
 
 let client: Anthropic | null = null;
 
+// Output-token ceiling for a single translation. The largest English docs
+// (e.g. agenteye/kubernetes-deployment.mdx at ~1400 lines) translate to well
+// beyond the old 16384 cap for verbose target languages. When a response hit
+// that cap it was silently truncated mid-MDX — leaving an unbalanced `{` or an
+// unterminated JSX expression — and the partial output was written to disk and
+// the cache, only to fail `mintlify validate` later in the consolidate job
+// (or, for the very largest pages, to trip the proxy with a "stream ended"
+// error). 64000 is Claude Haiku 4.5's max output (Tier 2/3 languages) and well
+// inside Claude Sonnet 4.6's 128000 (Tier 1), with headroom over the largest
+// observed translation; max_tokens is only a ceiling, so smaller pages still
+// stop at `end_turn` and cost the same. Streaming (below) is what keeps an
+// output this large safe from the SDK's HTTP timeout.
+// Override via TRANSLATE_MAX_TOKENS (integer >= 1; otherwise default).
+const parsedMaxTokens = Number.parseInt(
+  process.env.TRANSLATE_MAX_TOKENS ?? "",
+  10,
+);
+const MAX_TOKENS =
+  Number.isInteger(parsedMaxTokens) && parsedMaxTokens > 0
+    ? parsedMaxTokens
+    : 64000;
+
+// Maximum TOTAL validation attempts per page: 1 initial translation plus up to
+// MAX_ATTEMPTS-1 re-translations when the rendered output fails validation
+// (see translateValidated below). Distinct from the SDK transport budget
+// TRANSLATE_MAX_RETRIES (default 5, in getClient): that retries a single HTTP
+// request on a connection error; this re-translates a page whose *content*
+// failed the docs-build checks. They multiply — at most
+// MAX_ATTEMPTS x (1 + maxRetries) HTTP requests for one page in the worst case.
+// 3 collapses the observed per-page failure rate to negligible while costing
+// wall-clock (a serial retry inside one worker slot), not peak concurrency.
+// Override via TRANSLATE_MAX_ATTEMPTS (integer >= 1; 1 disables retries).
+const parsedMaxAttempts = Number.parseInt(
+  process.env.TRANSLATE_MAX_ATTEMPTS ?? "",
+  10,
+);
+const MAX_ATTEMPTS =
+  Number.isInteger(parsedMaxAttempts) && parsedMaxAttempts > 0
+    ? parsedMaxAttempts
+    : 3;
+
 function getClient(): Anthropic {
   if (!client) {
     // Default 5 retries (up from SDK default of 2) so transient
@@ -22,7 +63,7 @@ const SYSTEM_PROMPT = `You are a professional technical documentation translator
 
 1. **Preserve all code blocks exactly as-is** — never translate content inside backtick-fenced code blocks (\`\`\`...\`\`\`) or inline code (\`...\`).
 2. **Preserve MDX component syntax** — tags like <Card>, <CardGroup>, <CodeGroup>, <Steps>, <Step>, <Note>, <Tip>, <Tabs>, <Tab>, <Warning> must remain unchanged. Their attribute names (title, icon, href, cols) must remain in English. Only translate the text content of the \`title\` attribute and the text body between tags. **Never put an ASCII straight \`"\` inside a \`title="…"\` (or any JSX attribute value)** — it terminates the attribute and breaks MDX parsing. If the target language would normally wrap a word in quotation marks (e.g. German „…", Japanese 「…」), drop the inner quotes inside attribute values and rely on the surrounding tag for emphasis.
-3. **Preserve YAML frontmatter keys** — only translate the string values of \`title\` and \`description\`. Keep the \`icon\` value unchanged.
+3. **Preserve YAML frontmatter keys** — only translate the string values of \`title\` and \`description\`. Keep the \`icon\` value unchanged. Never rename, add, or drop a frontmatter key. The \`title\` and \`description\` values are wrapped in double quotes: **never put an unescaped ASCII \`"\` inside them** — it terminates the YAML string and breaks the frontmatter parse (exactly as an ASCII \`"\` breaks a JSX attribute in rule 2). If the source value contains an escaped quote (\`\\"\`), keep it escaped in the same form; if the target language would quote a phrase, use typographic quotes (e.g. „…", «…», 「…」) or rephrase to avoid the inner quote.
 4. **Preserve all URLs and paths** — never modify href values, image paths, or links.
 5. **Preserve Markdown structure** — headers (#, ##), lists (-, *), tables (|), bold (**), italic (*), links ([text](url)) must keep their Markdown formatting.
 6. **Preserve badge/shield URLs** — any [![...](https://img.shields.io/...)](url) pattern must remain completely unchanged.
@@ -43,11 +84,40 @@ ${DO_NOT_TRANSLATE.map((t) => `- ${t}`).join("\n")}
 
 Return ONLY the translated content. Do not add explanations, notes, or commentary.`;
 
+export interface RetryFeedback {
+  attempt: number;
+  maxAttempts: number;
+  /** The previous attempt's validation error — model-actionable text. */
+  error: string;
+}
+
+/**
+ * The repair note appended to the user turn on a retry. The failed attempt is
+ * NOT fed back as an assistant turn: a fresh re-translate keeps the input flat
+ * across attempts. Conversational repair would grow the input every attempt and
+ * push a large README toward the max_tokens ceiling on exactly the retry where
+ * a truncation would be worst — and the error is self-locating (it carries the
+ * caret excerpt / body snippet), so the model needs the note, not its own prior
+ * output, to fix the defect.
+ */
+function buildRetryFeedback(f: RetryFeedback): string {
+  return (
+    `[Retry ${f.attempt} of ${f.maxAttempts}. The source document above is unchanged.]\n\n` +
+    "Your previous translation of this document was REJECTED by the docs build " +
+    "and discarded. It failed validation with:\n\n" +
+    `${f.error}\n\n` +
+    "Translate the source again from the beginning and return ONLY the " +
+    "corrected translation — do not comment on this note. Do not reproduce that " +
+    "defect. Every rule above still applies."
+  );
+}
+
 export async function translateContent(
   content: string,
   targetLang: string,
   targetLangName: string,
   model: string = "claude-sonnet-4-6",
+  feedback?: RetryFeedback,
 ): Promise<{ translated: string; inputTokens: number; outputTokens: number }> {
   const anthropic = getClient();
 
@@ -59,20 +129,36 @@ export async function translateContent(
   // surfaces to the SDK as `APIConnectionError ("Connection error.")`.
   // `messages.stream(...).finalMessage()` returns the same Message shape
   // as `messages.create(...)`, so the rest of the pipeline is unchanged.
+  const base = `Translate the following documentation content into ${targetLangName} (${targetLang}).\n\n---\n\n${content}`;
+  // On a retry, append the repair note after the source in the SAME single user
+  // turn — no assistant turn is fed back, so the request stays flat-input.
+  const userContent = feedback
+    ? `${base}\n\n---\n\n${buildRetryFeedback(feedback)}`
+    : base;
+
   const response = await anthropic.messages.stream({
     model,
-    max_tokens: 16384,
+    max_tokens: MAX_TOKENS,
     system: [{ type: "text", text: SYSTEM_PROMPT, cache_control: { type: "ephemeral" } }],
-    messages: [
-      {
-        role: "user",
-        content: `Translate the following documentation content into ${targetLangName} (${targetLang}).\n\n---\n\n${content}`,
-      },
-    ],
+    messages: [{ role: "user", content: userContent }],
   }).finalMessage();
 
+  // A truncated translation is worse than a failed one: the model stops
+  // mid-MDX, and that partial would otherwise be written to disk and cached as
+  // if complete, surfacing only as an unbalanced-brace parse error in
+  // `mintlify validate`. Fail loudly instead so the caller (cli.ts) records an
+  // error, never caches the partial, and excludes this language from the
+  // consolidate publish step. If a page ever legitimately needs more than
+  // MAX_TOKENS, raise TRANSLATE_MAX_TOKENS or split the source.
+  if (response.stop_reason === "max_tokens") {
+    throw new Error(
+      `translation truncated at max_tokens=${MAX_TOKENS} ` +
+        `(output ${response.usage.output_tokens} tokens) — source too large to translate in one request`,
+    );
+  }
+
   const translated =
-    response.content[0].type === "text" ? response.content[0].text : "";
+    response.content[0]?.type === "text" ? response.content[0].text : "";
 
   return {
     translated,
@@ -80,3 +166,88 @@ export async function translateContent(
     outputTokens: response.usage.output_tokens,
   };
 }
+
+/**
+ * Translate `source`, render it to the exact bytes that will be written, and
+ * validate those bytes — re-translating with the validation error fed back
+ * until it passes or MAX_ATTEMPTS is reached.
+ *
+ * The loop lives here, not in translateContent, because each caller renders
+ * different final bytes (the MDX pages add rewriteInternalLinks; the README
+ * wraps the body in a disclaimer + RTL `<div>`). Validating the RENDERED bytes —
+ * not the raw model output — is what makes a pass here equal to a pass in
+ * `mintlify validate` and the deploy.
+ *
+ * On exhaustion it THROWS (never returns a partial), so the caller's write is
+ * unreachable and no invalid page is ever written or cached — the same
+ * fail-loud contract translateContent already enforces for max_tokens
+ * truncation. Transport/auth/max_tokens errors from translateContent propagate
+ * unchanged and consume no attempt: only *validity* failures retry.
+ */
+export async function translateValidated(opts: {
+  source: string;
+  lang: string;
+  langName: string;
+  model?: string;
+  /** Label for the per-attempt warning line, e.g. `agenteye/cli.mdx [de]`. */
+  label: string;
+  /** Turn raw model output into the exact bytes that will be written. */
+  render: (raw: string) => string;
+  /** Validate the rendered bytes; return an error message, or null if valid. */
+  validate: (rendered: string) => Promise<string | null>;
+}): Promise<{
+  rendered: string;
+  inputTokens: number;
+  outputTokens: number;
+  attempts: number;
+}> {
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let lastError = "";
+
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    const feedback: RetryFeedback | undefined =
+      attempt > 1
+        ? { attempt, maxAttempts: MAX_ATTEMPTS, error: lastError }
+        : undefined;
+
+    // No try/catch: a transport/auth/max_tokens throw is not a validity
+    // failure — let it propagate so it is never silently retried as one.
+    const result = await translateContent(
+      opts.source,
+      opts.lang,
+      opts.langName,
+      opts.model,
+      feedback,
+    );
+    inputTokens += result.inputTokens;
+    outputTokens += result.outputTokens;
+
+    if (result.translated.trim() === "") {
+      // An empty response is a validity failure, not a usable page — resample
+      // rather than write a blank file.
+      lastError =
+        "The translation was empty. Return the full translated document.";
+      console.warn(
+        `  ${opts.label} -> attempt ${attempt}/${MAX_ATTEMPTS} produced empty output; retrying`,
+      );
+      continue;
+    }
+
+    const rendered = opts.render(result.translated);
+    const error = await opts.validate(rendered);
+    if (error === null) {
+      return { rendered, inputTokens, outputTokens, attempts: attempt };
+    }
+
+    lastError = error;
+    console.warn(
+      `  ${opts.label} -> attempt ${attempt}/${MAX_ATTEMPTS} failed validation: ${error.split("\n")[0]}`,
+    );
+  }
+
+  throw new Error(
+    `translation into ${opts.langName} (${opts.lang}) still fails validation ` +
+      `after ${MAX_ATTEMPTS} attempt(s): ${lastError.split("\n")[0]}`,
+  );
+}