ai-i18n-tools 1.2.8 → 1.3.1

package/README.md

@@ -7,7 +7,7 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![CI](https://github.com/wsj-br/ai-i18n-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/wsj-br/ai-i18n-tools/actions/workflows/ci.yml)
 
-CLI and programmatic toolkit for internationalising JavaScript/TypeScript applications and documentation sites. Extracts UI strings, translates them with LLMs via OpenRouter, and generates locale-ready JSON files for i18next, plus pipelines for markdown, Docusaurus JSON, and standalone SVG assets.
+CLI and toolkit for internationalizing JavaScript/TypeScript applications and documentation sites. Extracts UI strings, translates them using large language models via OpenRouter, and generates locale-ready JSON files for i18next. Also includes pipelines for markdown, Docusaurus JSON, and standalone SVG assets.
 
 
 <small>**Read in other languages:** </small>
@@ -54,7 +54,7 @@ Both workflows share a single `ai-i18n-tools.config.json` file and can be used i
 <a id="installation"></a>
 ## Installation
 
-The published package is **ESM-only** (`"type": "module"`). Use `import` from Node.js, bundlers, or `import()` — `require('ai-i18n-tools')` **is not supported.** The package declares **`engines.node` `>=22.16.0`**; older Node.js versions are unsupported.
+The published package is **ESM-only** (`"type": "module"`). Use `import` from Node.js, bundlers, or `import()` — `require('ai-i18n-tools')` **is not supported.** The package declares `engines.node`  `>=22.16.0`; older Node.js versions are unsupported.
 
 ```bash
 npm install ai-i18n-tools
@@ -80,7 +80,7 @@ npx ai-i18n-tools sync        # or: pnpm exec ai-i18n-tools sync
 
 The package manager writes `node_modules/.bin/ai-i18n-tools` with the correct permissions on Linux and macOS and `.cmd` / `.ps1` shims on Windows; script runners pick it up automatically.
 
-**Bare** `ai-i18n-tools` **in the terminal** — `package.json` scripts already run with `node_modules/.bin` on `PATH`, so commands like `pnpm run i18n:sync` invoke the CLI without typing `npx`. To run `ai-i18n-tools` directly in an interactive shell (from the project root, after a local install), prepend the local bin directory to `PATH`:
+**Bare** `ai-i18n-tools` **in the terminal:** `package.json` scripts already run with `node_modules/.bin` on `PATH`, so commands like `pnpm run i18n:sync` invoke the CLI without typing `npx`. To run `ai-i18n-tools` directly in an interactive shell (from the project root, after a local install), prepend the local bin directory to `PATH`:
 
 ```bash
 # bash/zsh — project root
@@ -94,7 +94,7 @@ $env:Path = "$PWD\node_modules\.bin;$env:Path"
 ai-i18n-tools sync
 ```
 
-With [direnv](https://direnv.net/), add `PATH_add node_modules/.bin` to a `.envrc` in the project root so the bare command is available after `cd` into the repo. Without adjusting `PATH`, keep using `npx ai-i18n-tools …` or `pnpm exec ai-i18n-tools …`.
+With [**direnv**](https://direnv.net/), add `PATH_add node_modules/.bin` to a `.envrc` in the project root so the bare command is available after `cd` into the repo. Without adjusting `PATH`, keep using `npx ai-i18n-tools …` or `pnpm exec ai-i18n-tools …`.
 
 **Zero-install one-off** — `npx ai-i18n-tools <cmd>` or `pnpm dlx ai-i18n-tools <cmd>` (downloads the package for that invocation; no entry in `package.json`).
 
@@ -111,7 +111,7 @@ export OPENROUTER_API_KEY=sk-or-v1-your-key-here
 <a id="openrouter"></a>
 ## OpenRouter
 
-Commands that call OpenRouter (`translate-ui`, `translate-docs`, `sync`, `check-models`, and related scripts) need `OPENROUTER_API_KEY` in the environment.
+Commands that call OpenRouter (`translate-ui`, `translate-docs`, `sync`, `check-models`, and related scripts) need `OPENROUTER_API_KEY` in the environment. `check-markdown` does not use OpenRouter.
 
 In `ai-i18n-tools.config.json`, the `openrouter` object includes model lists, `baseUrl`, `maxTokens`, `temperature`, and `requestTimeoutMs`: the maximum time in milliseconds to wait for each HTTP request to OpenRouter (chat completions and internal `GET /models` calls). The default is `30000` (30 seconds).
 
@@ -226,6 +226,7 @@ ai-i18n-tools translate-docs [--locale <code>]      Translate documentation (mar
                                                     --prompt-format (xml | json-array | json-object)
 ai-i18n-tools write-heading-ids …                   Insert HTML anchor lines before ATX headings in .md/.mdx (documentations[])
 ai-i18n-tools strip-md-bold-inline …              Remove bold (**) around inline code in markdown/MDX (documentations[])
+ai-i18n-tools check-markdown [-p|--path <path>] [--json] [--no-cache]   Scan documentation markdown for delimiter / inline-code issues and strong-outside-code or strong-outside-link patterns; refresh SQLite markdown_source_issues; exit 1 if any issue
 ai-i18n-tools translate-svg [--locale <code>]       Standalone SVG assets (features.translateSVG + config.svg); see --no-cache
 ai-i18n-tools translate-ui [--locale <code>]        Translate UI strings only; see --force, --dry-run
 ai-i18n-tools lint-source …                         Run extract, then LLM review of source-locale UI strings (OpenRouter)
@@ -235,6 +236,7 @@ ai-i18n-tools status [--max-columns <n>]   UI strings per locale; markdown per f
 ai-i18n-tools statistics [--max-columns <n>]        Documentation cache + strings.json aggregates (same as editor Statistics)
 ai-i18n-tools editor                                Open cache/glossary web editor
 ai-i18n-tools cleanup [--dry-run] [--no-backup] [--backup <path>]   Runs sync --force-update, then cleans stale + orphaned cache rows; backs up SQLite by default
+ai-i18n-tools clean-temp [-r|--root <path>] [-f|--force] [--dry-run]   List *.log and cache.db.backup*.sqlite; delete after `y`, with `-f`, or skip if none match
 ai-i18n-tools glossary-generate                     Create empty glossary CSV template
 ```
 

package/dist/build-info.generated.d.ts

@@ -1,3 +1,3 @@
 /** Auto-generated by scripts/write-build-info.mjs — do not edit */
-export declare const BUILD_TIMESTAMP_ISO = "2026-05-03T13:40:52.006Z";
+export declare const BUILD_TIMESTAMP_ISO = "2026-05-03T18:52:54.458Z";
 //# sourceMappingURL=build-info.generated.d.ts.map

package/dist/build-info.generated.js

@@ -1,3 +1,3 @@
 /** Auto-generated by scripts/write-build-info.mjs — do not edit */
-export const BUILD_TIMESTAMP_ISO = "2026-05-03T13:40:52.006Z";
+export const BUILD_TIMESTAMP_ISO = "2026-05-03T18:52:54.458Z";
 //# sourceMappingURL=build-info.generated.js.map

package/dist/cli/check-markdown.d.ts

@@ -0,0 +1,25 @@
+import type { I18nConfig } from "../core/types.js";
+export interface CheckMarkdownOptions {
+    cwd: string;
+    config: I18nConfig;
+    pathFilter?: string;
+    json: boolean;
+    noCache: boolean;
+    verbose: boolean;
+}
+export interface CheckMarkdownJsonRow {
+    filepath: string;
+    displayPath: string;
+    line: number | null;
+    issueCode: string;
+    detail: string;
+    sourceHash: string;
+}
+/**
+ * Scan configured documentation markdown for delimiter / inline-code issues; optional SQLite refresh.
+ * @returns exit code 0 = no issues, 1 = at least one issue
+ */
+export declare function runCheckMarkdown(opts: CheckMarkdownOptions): Promise<{
+    exitCode: number;
+}>;
+//# sourceMappingURL=check-markdown.d.ts.map

package/dist/cli/check-markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-markdown.d.ts","sourceRoot":"","sources":["../../src/cli/check-markdown.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAenD,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAuEhG"}

package/dist/cli/check-markdown.js

@@ -0,0 +1,78 @@
+import fs from "fs";
+import path from "path";
+import chalk from "chalk";
+import { toDocTranslateConfig } from "../core/config.js";
+import { TranslationCache } from "../core/cache.js";
+import { documentationFileTrackingKey } from "../core/doc-file-tracking.js";
+import { MarkdownExtractor } from "../extractors/markdown-extractor.js";
+import { collectMarkdownIssuesForSegment } from "../processors/markdown-source-diagnostics.js";
+import { collectFilesByExtension } from "./file-utils.js";
+import { loadTranslateIgnore, isIgnored } from "../utils/ignore-parser.js";
+import { matchesPathFilter, buildMarkdownExtractOpts } from "./doc-translate.js";
+function filterIgnoredFiles(files, cwd) {
+    const ig = loadTranslateIgnore(".translate-ignore", cwd);
+    return files.filter((f) => !isIgnored(ig, path.join(cwd, f), cwd));
+}
+/**
+ * Scan configured documentation markdown for delimiter / inline-code issues; optional SQLite refresh.
+ * @returns exit code 0 = no issues, 1 = at least one issue
+ */
+export async function runCheckMarkdown(opts) {
+    const projectRoot = opts.cwd;
+    const jsonRows = [];
+    let issueCount = 0;
+    const cache = !opts.noCache && opts.config.cacheDir
+        ? new TranslationCache(path.join(projectRoot, opts.config.cacheDir))
+        : null;
+    try {
+        for (let bi = 0; bi < opts.config.documentations.length; bi++) {
+            const block = opts.config.documentations[bi];
+            const view = toDocTranslateConfig(opts.config, block);
+            const md = filterIgnoredFiles(collectFilesByExtension(block.contentPaths, [".md", ".mdx"], projectRoot), projectRoot).filter((r) => matchesPathFilter(r, opts.pathFilter));
+            const mdExtractOpts = buildMarkdownExtractOpts(view.documentation);
+            const extractor = new MarkdownExtractor();
+            for (const relPath of md) {
+                const abs = path.join(projectRoot, relPath);
+                const content = fs.readFileSync(abs, "utf8");
+                const segments = extractor.extract(content, relPath, mdExtractOpts);
+                const trackKey = documentationFileTrackingKey(bi, relPath);
+                const rows = segments.flatMap((s) => collectMarkdownIssuesForSegment(s, trackKey));
+                if (cache) {
+                    cache.replaceMarkdownIssuesForFilepath(trackKey, rows);
+                }
+                for (const row of rows) {
+                    issueCount++;
+                    if (opts.json) {
+                        jsonRows.push({
+                            filepath: row.filepath,
+                            displayPath: relPath,
+                            line: row.startLine,
+                            issueCode: row.issueCode,
+                            detail: row.detail,
+                            sourceHash: row.sourceHash,
+                        });
+                    }
+                    else {
+                        const line = row.startLine ?? "?";
+                        console.error(chalk.cyan(`${relPath}:${line}`) +
+                            chalk.yellow(`: [${row.issueCode}] ${row.detail}${opts.verbose ? ` (hash ${row.sourceHash})` : ""}`));
+                    }
+                }
+            }
+        }
+    }
+    finally {
+        cache?.close();
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({ issues: jsonRows, count: issueCount }, null, 2));
+    }
+    else if (issueCount > 0) {
+        console.error(chalk.red(`\n❌ check-markdown: ${issueCount} issue(s) in documentation sources`));
+    }
+    else {
+        console.log(chalk.green("✅ check-markdown: no markdown source issues found"));
+    }
+    return { exitCode: issueCount > 0 ? 1 : 0 };
+}
+//# sourceMappingURL=check-markdown.js.map

package/dist/cli/check-markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-markdown.js","sourceRoot":"","sources":["../../src/cli/check-markdown.ts"],"names":[],"mappings":"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"}

package/dist/cli/clean-temp.d.ts

@@ -0,0 +1,17 @@
+/** Basenames matched by `find … \( -name '*.log' -o -name 'cache.db.backup*.sqlite' \)`. */
+export declare function matchesCleanTempBasename(basename: string): boolean;
+/** Print path like `find . -print` (posix-style `./…` under `rootAbs`). */
+export declare function formatFindPrintLine(rootAbs: string, fileAbs: string): string;
+export type RunCleanTempOptions = {
+    rootDir: string;
+    /** When true, skip the prompt and do not delete (list only). Overrides `force`. */
+    dryRun?: boolean;
+    /** When true, delete without prompting (after listing). Ignored when `dryRun` is true. */
+    force?: boolean;
+};
+/**
+ * Lists `*.log` and `cache.db.backup*.sqlite` under `rootDir`, prints paths like `find -print`,
+ * then prompts unless `force` or there are no matches; deletes on exact `y`, or immediately when `force`.
+ */
+export declare function runCleanTemp(opts: RunCleanTempOptions): Promise<void>;
+//# sourceMappingURL=clean-temp.d.ts.map

package/dist/cli/clean-temp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clean-temp.d.ts","sourceRoot":"","sources":["../../src/cli/clean-temp.ts"],"names":[],"mappings":"AAIA,4FAA4F;AAC5F,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAIlE;AAED,2EAA2E;AAC3E,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAK5E;AA+CD,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,0FAA0F;IAC1F,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;GAGG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyC3E"}

package/dist/cli/clean-temp.js

@@ -0,0 +1,109 @@
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline/promises";
+/** Basenames matched by `find … \( -name '*.log' -o -name 'cache.db.backup*.sqlite' \)`. */
+export function matchesCleanTempBasename(basename) {
+    if (basename.endsWith(".log"))
+        return true;
+    if (basename.startsWith("cache.db.backup") && basename.endsWith(".sqlite"))
+        return true;
+    return false;
+}
+/** Print path like `find . -print` (posix-style `./…` under `rootAbs`). */
+export function formatFindPrintLine(rootAbs, fileAbs) {
+    const rel = path.relative(rootAbs, fileAbs);
+    const norm = rel.split(path.sep).join("/");
+    if (norm === "" || norm === ".")
+        return "./";
+    return `./${norm}`;
+}
+async function collectCleanTempFiles(rootAbs) {
+    const out = [];
+    async function visit(dir) {
+        let entries;
+        try {
+            entries = await fs.promises.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const ent of entries) {
+            const full = path.join(dir, ent.name);
+            if (ent.isSymbolicLink()) {
+                let st;
+                try {
+                    st = await fs.promises.lstat(full);
+                }
+                catch {
+                    continue;
+                }
+                if (st.isDirectory())
+                    continue;
+                if (matchesCleanTempBasename(ent.name))
+                    out.push(full);
+                continue;
+            }
+            if (ent.isDirectory()) {
+                await visit(full);
+            }
+            else if (ent.isFile() && matchesCleanTempBasename(ent.name)) {
+                out.push(full);
+            }
+        }
+    }
+    await visit(rootAbs);
+    return out;
+}
+async function promptDeleteConfirmed() {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const ans = await rl.question("\nDelete these files? (y/n) ");
+        return ans === "y";
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Lists `*.log` and `cache.db.backup*.sqlite` under `rootDir`, prints paths like `find -print`,
+ * then prompts unless `force` or there are no matches; deletes on exact `y`, or immediately when `force`.
+ */
+export async function runCleanTemp(opts) {
+    const rootAbs = path.resolve(opts.rootDir);
+    if (!fs.existsSync(rootAbs)) {
+        console.error(`Directory not found: ${rootAbs}`);
+        process.exitCode = 1;
+        return;
+    }
+    const st = await fs.promises.stat(rootAbs);
+    if (!st.isDirectory()) {
+        console.error(`Not a directory: ${rootAbs}`);
+        process.exitCode = 1;
+        return;
+    }
+    const files = await collectCleanTempFiles(rootAbs);
+    for (const abs of files) {
+        console.log(formatFindPrintLine(rootAbs, abs));
+    }
+    if (opts.dryRun) {
+        return;
+    }
+    if (files.length === 0) {
+        return;
+    }
+    const ok = opts.force ? true : await promptDeleteConfirmed();
+    if (!ok) {
+        return;
+    }
+    for (const abs of files) {
+        try {
+            await fs.promises.unlink(abs);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            console.error(`Failed to delete ${formatFindPrintLine(rootAbs, abs)}: ${msg}`);
+            process.exitCode = 1;
+        }
+    }
+}
+//# sourceMappingURL=clean-temp.js.map

package/dist/cli/clean-temp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clean-temp.js","sourceRoot":"","sources":["../../src/cli/clean-temp.ts"],"names":[],"mappings":"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"}

package/dist/cli/doc-translate.d.ts

@@ -1,11 +1,14 @@
-import type { DocSegmentTranslation, I18nConfig, I18nDocTranslateConfig } from "../core/types.js";
+import type { DocSegmentTranslation, DocumentationBlock, I18nConfig, I18nDocTranslateConfig } from "../core/types.js";
 export type { DocSegmentTranslation };
 import { TranslationCache } from "../core/cache.js";
+import type { MarkdownExtractOptions } from "../extractors/markdown-extractor.js";
 import { PlaceholderHandler } from "../processors/placeholder-handler.js";
 import { Glossary } from "../glossary/glossary.js";
 import { OpenRouterClient } from "../api/openrouter.js";
 import type { DocumentBatchResponseFormat } from "../core/prompt-builder.js";
 import { AsyncMutex } from "../utils/concurrency.js";
+/** Same segment-extraction options as `translate-docs` for one documentation block. */
+export declare function buildMarkdownExtractOpts(documentation: DocumentationBlock): MarkdownExtractOptions | undefined;
 /** Batch segment prompt/response shape for `translate-docs --prompt-format`. */
 export type TranslatePromptFormat = "xml" | "json-array" | "json-object";
 export declare function translatePromptFormatToResponseFormat(fmt: TranslatePromptFormat | undefined): DocumentBatchResponseFormat;
@@ -96,6 +99,12 @@ export declare function jsonFileProjectRelativePath(projectRoot: string, jsonAbs
  * Empty input or a path equal to the project root means no filter (translate everything).
  */
 export declare function normalizePathFilterForProjectRoot(projectRoot: string, raw: string | undefined): string | undefined;
+/**
+ * Locale-independent: read source, extract segments (same options as translation), then refresh
+ * `markdown_source_issues` and stderr warnings. Call once per markdown file before parallel
+ * per-locale work so diagnostics are not repeated for every locale.
+ */
+export declare function scanAndRecordMarkdownSourceIssuesForTranslate(absSource: string, relPath: string, config: I18nDocTranslateConfig, cache: TranslationCache, opts: TranslateRunOptions): Promise<void>;
 export declare function translateMarkdownFile(absSource: string, relPath: string, locale: string, config: I18nDocTranslateConfig, cache: TranslationCache | null, client: OpenRouterClient | null, glossary: Glossary, opts: TranslateRunOptions, hitKeys: Set<string>, translatedMarkdownRelPaths: ReadonlySet<string>): Promise<{
     skipped: boolean;
     totals: TranslateTotals;

package/dist/cli/doc-translate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doc-translate.d.ts","sourceRoot":"","sources":["../../src/cli/doc-translate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"doc-translate.d.ts","sourceRoot":"","sources":["../../src/cli/doc-translate.ts"],"names":[],"mappings":"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"}

package/dist/cli/doc-translate.js

@@ -27,6 +27,19 @@ import { ensureDirForFile, hashFileContent, resolveTranslatedOutputPath, writeAt
 import { normalizeLocale } from "../core/config.js";
 import { runMapWithConcurrency, AsyncSemaphore, AsyncMutex } from "../utils/concurrency.js";
 import { describeEmphasisPlaceholdersPolicy, resolveMarkdownEmphasisPlaceholders, usesAutomaticEmphasisPlaceholdersForLocale, } from "../core/markdown-emphasis-defaults.js";
+import { collectMarkdownIssuesForSegment } from "../processors/markdown-source-diagnostics.js";
+/** Same segment-extraction options as `translate-docs` for one documentation block. */
+export function buildMarkdownExtractOpts(documentation) {
+    const langListCfg = documentation.markdownOutput.postProcessing?.languageListBlock;
+    const splitCfg = segmentSplittingSchema.parse(documentation.segmentSplitting ?? {});
+    if (!langListCfg && !splitCfg.enabled) {
+        return undefined;
+    }
+    return {
+        ...(langListCfg ? { languageListBlock: langListCfg } : {}),
+        ...(splitCfg.enabled ? { segmentSplitting: splitCfg } : {}),
+    };
+}
 export function translatePromptFormatToResponseFormat(fmt) {
     if (fmt === "json-array") {
         return "json-array";
@@ -829,6 +842,33 @@ failureDocMeta) {
         individualSegmentTranslations,
     };
 }
+/**
+ * Locale-independent: read source, extract segments (same options as translation), then refresh
+ * `markdown_source_issues` and stderr warnings. Call once per markdown file before parallel
+ * per-locale work so diagnostics are not repeated for every locale.
+ */
+export async function scanAndRecordMarkdownSourceIssuesForTranslate(absSource, relPath, config, cache, opts) {
+    if (config.documentation.warnMarkdownSourceIssues === false || opts.noCache || opts.dryRun) {
+        return;
+    }
+    const content = fs.readFileSync(absSource, "utf8");
+    const blockIdx = opts.documentationBlockIndex ?? 0;
+    const fileTrackingKey = documentationFileTrackingKey(blockIdx, relPath);
+    const md = new MarkdownExtractor();
+    const mdExtractOpts = buildMarkdownExtractOpts(config.documentation);
+    const segments = md.extract(content, relPath, mdExtractOpts);
+    const markdownIssueRows = [];
+    for (const s of segments) {
+        markdownIssueRows.push(...collectMarkdownIssuesForSegment(s, fileTrackingKey));
+    }
+    await withCacheMutex(opts.cacheMutex, () => cache.replaceMarkdownIssuesForFilepath(fileTrackingKey, markdownIssueRows));
+    if (markdownIssueRows.length > 0) {
+        for (const row of markdownIssueRows) {
+            const ln = row.startLine ?? "?";
+            console.warn(chalk.yellow(`  ⚠️  Markdown source ${relPath}:${ln} [${row.issueCode}] ${row.detail}\n`));
+        }
+    }
+}
 export async function translateMarkdownFile(absSource, relPath, locale, config, cache, client, glossary, opts, hitKeys, translatedMarkdownRelPaths) {
     const totals = {
         filesWritten: 0,
@@ -869,14 +909,7 @@ export async function translateMarkdownFile(absSource, relPath, locale, config,
     }
     const fileStartTime = Date.now();
     const md = new MarkdownExtractor();
-    const langListCfg = config.documentation.markdownOutput.postProcessing?.languageListBlock;
-    const splitCfg = segmentSplittingSchema.parse(config.documentation.segmentSplitting ?? {});
-    const mdExtractOpts = langListCfg || splitCfg.enabled
-        ? {
-            ...(langListCfg ? { languageListBlock: langListCfg } : {}),
-            ...(splitCfg.enabled ? { segmentSplitting: splitCfg } : {}),
-        }
-        : undefined;
+    const mdExtractOpts = buildMarkdownExtractOpts(config.documentation);
     const segments = md.extract(content, relPath, mdExtractOpts);
     const translatableCount = segments.filter((s) => s.translatable).length;
     console.log(chalk.yellow(`📄 ${locale} ${relPath}: ${segments.length} segment(s) (${translatableCount} translatable)`));
@@ -1457,6 +1490,15 @@ export async function runTranslate(config, opts, files, jsonAbsRoot) {
         batchConcurrency: batchConcurrencyEffective,
         cacheMutex,
     };
+    if (shouldRunMarkdown(opts, config) && cache && !opts.noCache && !opts.dryRun) {
+        for (const rel of files.markdown) {
+            if (!matchesPathFilter(rel, opts.pathFilter)) {
+                continue;
+            }
+            const abs = path.join(opts.cwd, rel);
+            await scanAndRecordMarkdownSourceIssuesForTranslate(abs, rel, config, cache, runOpts);
+        }
+    }
     const processLocale = async (locale) => {
         const markdownHitKeysLocal = new Set();
         const partial = {