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 [](url) pattern must remain completely unchanged.
@@ -65,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();
@@ -81,16 +129,18 @@ 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: 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
@@ -116,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 ``). 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;
+}): 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]}`,
+ );
+}
diff --git a/scripts/translate-docs/types.ts b/scripts/translate-docs/types.ts
index 22ea32f6..1eae9e7c 100644
--- a/scripts/translate-docs/types.ts
+++ b/scripts/translate-docs/types.ts
@@ -43,4 +43,10 @@ export interface TranslationResult {
inputTokens: number;
outputTokens: number;
cached: boolean;
+ /**
+ * Total translation attempts spent (1 = valid on first try). Optional so the
+ * cached / dry-run result literals need no change; absent means "not
+ * translated this run" (cached) or "1".
+ */
+ attempts?: number;
}
diff --git a/scripts/translate-docs/validate-translation.ts b/scripts/translate-docs/validate-translation.ts
new file mode 100644
index 00000000..63234302
--- /dev/null
+++ b/scripts/translate-docs/validate-translation.ts
@@ -0,0 +1,132 @@
+/**
+ * Generation-time validation for a freshly translated page.
+ *
+ * `findTranslationError` runs the exact checks the Mintlify deploy performs —
+ * frontmatter YAML then MDX body — plus one the deploy cannot: frontmatter
+ * KEY-PARITY against the English source. It is called on the exact bytes about
+ * to be written to disk (post-sanitize, post-link-rewrite), so a page that
+ * passes here is a page `mintlify validate` and the deploy accept.
+ *
+ * Why a translation-specific wrapper instead of `findPageError` alone:
+ * - Frontmatter YAML (class A): the model re-emits an inner `"` unescaped into
+ * a double-quoted `title:`/`description:` value, breaking the YAML. This is
+ * the class that failed run 29575781632; `findFrontmatterError` catches it.
+ * - Key parity (class B): the model drops the frontmatter block entirely, or
+ * renames a key. A dropped block is still *valid YAML* (mintlify tolerates
+ * it, deriving the title from the slug), so only comparing against the
+ * source's keys catches it. This is deliberately stricter than mintlify —
+ * the keys are prompt-forbidden to change, so it fails ~never but converts
+ * a silent content regression into a retry.
+ * - MDX body (classes C+): stray ``, `{#anchor}`, unmatched fence,
+ * swallowed `
` — `findMdxParseError` catches these.
+ *
+ * The message returned is written for a MODEL to act on: it names the failing
+ * construct and, for a body error, quotes the offending line, so the retry has
+ * a concrete defect to fix rather than a bare line number the RTL/README
+ * wrappers would have offset anyway.
+ */
+import { findFrontmatterError, findMdxParseError } from "../validate-mdx";
+import YAML from "yaml";
+
+// Same matcher as validate-mdx.ts; duplicated locally so this module owns its
+// frontmatter extraction and does not depend on an internal export.
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?/;
+
+/**
+ * The sorted top-level keys of a page's frontmatter, or `null` when the page
+ * has no frontmatter block or its block is not a key/value mapping (an
+ * unparseable or scalar block). Callers distinguish "no block" from a YAML
+ * error separately via `findFrontmatterError`.
+ */
+function frontmatterKeys(page: string): string[] | null {
+ const match = FRONTMATTER_RE.exec(page);
+ if (!match) return null;
+ try {
+ const doc = YAML.parse(match[1]);
+ if (doc && typeof doc === "object" && !Array.isArray(doc)) {
+ return Object.keys(doc).sort();
+ }
+ return null;
+ } catch {
+ return null;
+ }
+}
+
+/**
+ * A ±2-line window around `line` (1-based), the failing line prefixed `> ` and
+ * its neighbours ` `. Empty string when `line` is undefined.
+ */
+function excerpt(page: string, line?: number): string {
+ if (!line) return "";
+ const lines = page.split("\n");
+ const start = Math.max(1, line - 2);
+ const end = Math.min(lines.length, line + 2);
+ const out: string[] = [];
+ for (let n = start; n <= end; n++) {
+ out.push(`${n === line ? "> " : " "}${lines[n - 1]}`);
+ }
+ return out.join("\n");
+}
+
+const backticked = (keys: string[]): string =>
+ keys.map((k) => `\`${k}\``).join(", ");
+
+/**
+ * Validate a rendered translation against its English `source`. Returns a
+ * model-actionable error message, or `null` when the page is publishable.
+ */
+export async function findTranslationError(
+ rendered: string,
+ source: string,
+): Promise {
+ // Validate the rendered frontmatter block FIRST, for every source shape —
+ // even when the source had none. findMdxParseError (below) blanks a leading
+ // `---` block before compiling, so a malformed block the model *added* to a
+ // frontmatter-less page would otherwise be invisible here yet still break the
+ // Mintlify deploy. Closing exactly that blind spot is this module's job, so
+ // it must hold regardless of whether the source has frontmatter.
+ const fm = findFrontmatterError(rendered);
+ if (fm) {
+ return (
+ "The YAML frontmatter (the `---` block at the top of the file) does " +
+ `not parse:\n\n${fm.message}`
+ );
+ }
+
+ const sourceKeys = frontmatterKeys(source);
+ if (sourceKeys) {
+ // The source has frontmatter, so the translation must carry the same keys.
+ // (Its block, if present, already parsed cleanly above.)
+ const keys = frontmatterKeys(rendered);
+ if (keys === null) {
+ return (
+ "The YAML frontmatter is missing. The English source starts with a " +
+ `\`---\` block containing ${backticked(sourceKeys)}; the translation ` +
+ "must start with the same block — translate the values, keep the keys."
+ );
+ }
+ // Subset check BY DESIGN: a missing or renamed key is a content regression
+ // (the page loses its title/description), so reject it. An *extra* key is
+ // harmless — Mintlify ignores unknown frontmatter keys — so tolerate it
+ // rather than burn a retry (and risk exhausting the whole batch) on a page
+ // that would deploy fine. Reject content loss; allow harmless additions.
+ const missing = sourceKeys.filter((k) => !keys.includes(k));
+ if (missing.length > 0) {
+ return (
+ `The YAML frontmatter keys changed. Expected ${backticked(sourceKeys)} ` +
+ `but got ${backticked(keys)}. Translate the values, never rename or ` +
+ "drop a key."
+ );
+ }
+ }
+
+ const body = await findMdxParseError(rendered);
+ if (body) {
+ const snippet = excerpt(rendered, body.line);
+ return `The MDX body does not parse: ${body.message}${
+ snippet ? `\n\n${snippet}` : ""
+ }`;
+ }
+
+ return null;
+}
diff --git a/scripts/validate-mdx.ts b/scripts/validate-mdx.ts
index ff4074ee..592b2d8a 100644
--- a/scripts/validate-mdx.ts
+++ b/scripts/validate-mdx.ts
@@ -2,12 +2,12 @@
* Validate that every docs page (`.mdx` and `.md` — Mintlify parses both as
* MDX) parses with the same MDX engine Mintlify runs at deploy time.
*
- * Why this exists: `mintlify validate` (the existing `docs` CI job) only checks
- * `docs.json` structure and nav-link resolution — it does NOT parse page
- * content. A page that is structurally referenced but contains an MDX syntax
- * error (e.g. a `` that escaped its surrounding backticks because a
- * translation dropped a closing `` ` ``) passes `mintlify validate` but fails
- * the Mintlify deploy with:
+ * Why this exists: `mintlify validate` (the existing `docs` CI job) checks
+ * `docs.json` structure, nav-link resolution, and frontmatter YAML — but it
+ * does NOT report MDX *body* syntax errors. A page whose frontmatter is valid
+ * but whose body contains an MDX syntax error (e.g. a `` that escaped its
+ * surrounding backticks because a translation dropped a closing `` ` ``) passes
+ * `mintlify validate` but fails the Mintlify deploy with:
*
* Failed to parse page content at path tr/cli/audit.mdx:
* Expected a closing tag for `` (61:127-61:133) before the end of `paragraph`
@@ -21,12 +21,16 @@
*
* The error string above is emitted by `@mdx-js/mdx`'s micromark MDX layer,
* which is the same engine Mintlify uses, so compiling here reproduces the
- * deploy-time parse faithfully.
+ * deploy-time parse faithfully. `main()` validates the frontmatter too (via
+ * `findPageError`), so this net is a strict superset of `mintlify validate`:
+ * it catches both the frontmatter YAML class that fails `mintlify validate`
+ * and the body-MDX class that `mintlify validate` lets through to deploy.
*/
import { readdirSync, statSync, readFileSync } from "node:fs";
import { dirname, join, relative } from "node:path";
import { fileURLToPath } from "node:url";
import { compile } from "@mdx-js/mdx";
+import YAML from "yaml";
const __dirname = dirname(fileURLToPath(import.meta.url));
const DOCS_DIR = join(__dirname, "..", "docs");
@@ -37,21 +41,86 @@ export interface MdxParseError {
column?: number;
}
+/**
+ * Shared frontmatter matcher. The capture group is the YAML block *body* (the
+ * text between the fences); `match[0]` is still the whole block including the
+ * fences and trailing newline, which is what `stripFrontmatter` blanks.
+ */
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?/;
+
/**
* Replace a leading YAML frontmatter block (`--- … ---`) with blank lines.
*
* Mintlify parses frontmatter as YAML, not MDX, so it never causes an MDX parse
- * error. We blank it rather than delete it so the remaining content keeps its
- * original line numbers — error positions then match the real file.
+ * error — but it CAN contain a YAML syntax error, which blanking here hides
+ * from `findMdxParseError`. That gap is covered separately by
+ * `findFrontmatterError`; `findPageError` runs both. We blank rather than delete
+ * so the remaining body keeps its original line numbers — body error positions
+ * then match the real file.
*/
export function stripFrontmatter(source: string): string {
- const match = /^---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n?/.exec(source);
+ const match = FRONTMATTER_RE.exec(source);
if (!match) return source;
// Keep newlines, drop every other character, so line numbers stay aligned.
const blanked = match[0].replace(/[^\n]/g, "");
return blanked + source.slice(match[0].length);
}
+/**
+ * Parse the leading YAML frontmatter block and return its parse error, or
+ * `null` when the block is absent (legal — some pages and every i18n README
+ * have none) or valid.
+ *
+ * This is the half of page validation that `findMdxParseError` structurally
+ * cannot do: it compiles only the *body* (frontmatter blanked), so a YAML
+ * syntax error in `title:`/`description:` — the exact class that failed the
+ * `consolidate` job's `mintlify validate` step, and that this repo's own
+ * `validate:mdx` net could not see — sailed straight through. `mintlify`
+ * parses the frontmatter as YAML, so parsing it here reproduces that check.
+ *
+ * The reported `line` is FILE-relative (the opening `---` is file line 1), so
+ * it matches the convention `findMdxParseError` already uses for body errors.
+ * That is deliberately one greater than the block-relative number `mintlify`
+ * prints — do NOT "fix" it to match mintlify; file-relative is what points a
+ * reader (or a model asked to repair the page) at the right line.
+ */
+export function findFrontmatterError(source: string): MdxParseError | null {
+ const match = FRONTMATTER_RE.exec(source);
+ if (!match) return null;
+ try {
+ YAML.parse(match[1]);
+ return null;
+ } catch (err) {
+ const e = err as {
+ message?: string;
+ linePos?: Array<{ line: number; col: number }>;
+ };
+ const raw = e.message ?? String(err);
+ return {
+ // Drop yaml's block-relative "at line N, column N:" phrase (it would
+ // contradict the file-relative line we report) but keep the caret-
+ // underlined excerpt after it — the single most useful signal for a
+ // model asked to repair the offending line.
+ message: raw.replace(/ at line \d+, column \d+:/, ":"),
+ line: e.linePos?.[0] ? e.linePos[0].line + 1 : undefined,
+ column: e.linePos?.[0]?.col,
+ };
+ }
+}
+
+/**
+ * Validate a full page the way the Mintlify deploy does: frontmatter YAML
+ * first, then the MDX body. Returns the first error found, or `null`. This is
+ * the single entry point shared by `validate:mdx` (`main()` below) and the
+ * translation pipeline's generation-time gate, so the two can never disagree
+ * about what is publishable.
+ */
+export async function findPageError(
+ source: string,
+): Promise {
+ return findFrontmatterError(source) ?? (await findMdxParseError(source));
+}
+
/**
* Compile one MDX source string with the deploy-time parser. Returns `null`
* when it parses cleanly, or the parse error (with position) otherwise.
@@ -114,7 +183,7 @@ async function main(): Promise {
const failures: Array<{ file: string; error: MdxParseError }> = [];
for (const file of files) {
- const error = await findMdxParseError(readFileSync(file, "utf-8"));
+ const error = await findPageError(readFileSync(file, "utf-8"));
if (error) failures.push({ file: relative(process.cwd(), file), error });
}