ai-i18n-tools 1.3.1 → 1.4.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 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.
+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. For documentation, it translates markdown and MDX under `contentPaths` (the localized pages readers open). Optional Docusaurus label JSON from `jsonSource` covers site shell strings (`write-translations` catalogs such as theme/nav/footer), distinct from page body copy. SVG file translation uses `features.translateSVG` and the top-level `svg` block.
 
 
 <small>**Read in other languages:** </small>
@@ -43,11 +43,11 @@ CLI and toolkit for internationalizing JavaScript/TypeScript applications and do
 
 Builds a master catalog (`strings.json` with optional per-locale `models` metadata) from `t("…")` / `i18n.t("…")` **literals**, optionally `package.json` `description`, and optionally each `englishName` from `ui-languages.json` when enabled in config. Translates missing entries per locale via OpenRouter and writes flat JSON files (`de.json`, `pt-BR.json`, …) ready for i18next.
 
-**Workflow 2 - Document translation** (Markdown, Docusaurus JSON)
+**Workflow 2 - Document translation** (Markdown / MDX, optional Docusaurus shell JSON)
 
-Translates `.md` and `.mdx` from each `documentations` block’s `contentPaths` and JSON label files from that block’s `jsonSource` when enabled. Supports Docusaurus-style and flat locale-suffixed layouts per block (`documentations[].markdownOutput`). Shared root `cacheDir` holds the SQLite cache so only new or changed segments are sent to the LLM. **SVG:** enable `features.translateSVG`, add the top-level `svg` block, then use `translate-svg` (also run from `sync` when both are set).
+Translates `.md` and `.mdx` from each `documentations` block’s `contentPaths` — that is the localized documentation. When `features.translateJSON` and `jsonSource` are set, it also translates Docusaurus **label JSON** (navbar, footer, theme/plugin UI from `write-translations`), not MDX body text. Supports Docusaurus-style and flat locale-suffixed layouts per block (`documentations[].markdownOutput`). Shared root `cacheDir` holds the SQLite cache so only new or changed segments are sent to the LLM. **SVG:** enable `features.translateSVG`, add the top-level `svg` block, then use `translate-svg` (also run from `sync` when both are set).
 
-Both workflows share a single `ai-i18n-tools.config.json` file and can be used independently or together. Standalone SVG translation uses `features.translateSVG` plus the top-level `svg` block and runs through `translate-svg` (or the SVG stage inside `sync`).
+Both workflows share a single `ai-i18n-tools.config.json` file and can be used independently or together. SVG file translation uses `features.translateSVG` plus the top-level `svg` block and runs through `translate-svg` (or the SVG stage inside `sync`).
 
 ---
 
@@ -62,6 +62,7 @@ npm install ai-i18n-tools
 pnpm add ai-i18n-tools
 ```
 
+<a id="using-the-cli"></a>
 ### Using the CLI
 
 **Per-project (recommended)** — install as a dependency or devDependency, then call via `npx`, `pnpm exec`, or a `package.json` script:
@@ -221,17 +222,20 @@ ai-i18n-tools init [-t ui-markdown|ui-docusaurus] [-o path] [--with-translate-ig
 ai-i18n-tools check-models                          Validate configured OpenRouter model ids against GET /models (pricing, expiration); requires OPENROUTER_API_KEY
 ai-i18n-tools generate-ui-languages [--master path] [--dry-run]   Build ui-languages.json from locales + master catalog (needs uiLanguagesPath)
 ai-i18n-tools extract                               Merge scanner output, optional package.json description, optional manifest englishName into strings.json
-ai-i18n-tools translate-docs [--locale <code>]      Translate documentation (markdown, JSON); see docs for
-                                                    --force-update, --force, --stats, --clear-cache,
-                                                    --prompt-format (xml | json-array | json-object)
+ai-i18n-tools translate-docs …                      Translate documentation: markdown/MDX from contentPaths; optional Docusaurus label JSON from jsonSource. Flags include -l/--locale <codes>, -p/-f path, --dry-run,
+                                                    --force, --force-update, --stats, --clear-cache, --type, --json-only, --no-json, -j, -b,
+                                                    --prompt-format, --emphasis-placeholders, --no-emphasis-placeholders, --debug-failed
 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 translate-svg …                        SVG files (features.translateSVG + config.svg); flags include -l/--locale <codes>,
+                                                    -p/-f path, --dry-run, --force, --force-update, --no-cache, -j, -b
+ai-i18n-tools translate-ui …                        Translate UI strings only; flags include -l/--locale <codes>, --dry-run, --force, -j
 ai-i18n-tools lint-source …                         Run extract, then LLM review of source-locale UI strings (OpenRouter)
-ai-i18n-tools export-ui-xliff [--locale <code>]     Export UI strings to XLIFF 2.0 (one file per locale); see --untranslated-only, -o
-ai-i18n-tools sync                                  Extract UI strings, then translate UI strings, SVG, and docs
+ai-i18n-tools export-ui-xliff …                   Export UI strings to XLIFF 2.0 (one file per locale); -l, -o, --untranslated-only, --dry-run
+ai-i18n-tools sync …                                Extract, then UI / SVG / docs; flags include -l/--locale <codes>, -p/-f path, --dry-run, --force,
+                                                    --force-update, --no-ui, --no-svg, --no-docs, -j, -b, --emphasis-placeholders,
+                                                    --no-emphasis-placeholders, --debug-failed
 ai-i18n-tools status [--max-columns <n>]   UI strings per locale; markdown per file × locale in tables of up to n locales (default 9)
 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
@@ -240,7 +244,9 @@ ai-i18n-tools clean-temp [-r|--root <path>] [-f|--force] [--dry-run]   List *.lo
 ai-i18n-tools glossary-generate                     Create empty glossary CSV template
 ```
 
-Global options on every command: `-c <config>` (default: `ai-i18n-tools.config.json`), `-v` (verbose), optional `-w` / `--write-logs [path]` to tee console output to a log file (default: under the translation cache directory), `-V` / `--version`, and `-h` / `--help`. See [Getting Started](docs/GETTING_STARTED.md#cli-reference) for per-command flags.
+Complete per-command flag lists are maintained next to `src/cli/index.ts` in [CLI flags by command](docs/GETTING_STARTED.md#cli-flags-by-command). Run `ai-i18n-tools <command> --help` for built-in usage text.
+
+Global options on every command: `-c <config>` (default: `ai-i18n-tools.config.json`), `-v` (verbose), optional `-w` / `--write-logs [path]` to tee console output to a log file (default: under the translation cache directory), `-V` / `--version`, and `-h` / `--help`. See [Getting Started](docs/GETTING_STARTED.md#cli-reference) for the command overview table.
 
 ---
 

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-03T18:52:54.458Z";
+export declare const BUILD_TIMESTAMP_ISO = "2026-05-06T22:24:28.496Z";
 //# 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-03T18:52:54.458Z";
+export const BUILD_TIMESTAMP_ISO = "2026-05-06T22:24:28.496Z";
 //# sourceMappingURL=build-info.generated.js.map

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

@@ -1 +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"}
+{"version":3,"file":"clean-temp.d.ts","sourceRoot":"","sources":["../../src/cli/clean-temp.ts"],"names":[],"mappings":"AAKA,4FAA4F;AAC5F,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAKlE;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,CA+C3E"}

package/dist/cli/clean-temp.js

@@ -1,10 +1,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import readline from "node:readline/promises";
+import chalk from "chalk";
 /** Basenames matched by `find … \( -name '*.log' -o -name 'cache.db.backup*.sqlite' \)`. */
 export function matchesCleanTempBasename(basename) {
     if (basename.endsWith(".log"))
         return true;
+    if (basename.endsWith(".tmp"))
+        return true;
     if (basename.startsWith("cache.db.backup") && basename.endsWith(".sqlite"))
         return true;
     return false;
@@ -15,7 +18,7 @@ export function formatFindPrintLine(rootAbs, fileAbs) {
     const norm = rel.split(path.sep).join("/");
     if (norm === "" || norm === ".")
         return "./";
-    return `./${norm}`;
+    return `[clean-temp]` + chalk.cyan(` ./${norm}`);
 }
 async function collectCleanTempFiles(rootAbs) {
     const out = [];
@@ -57,7 +60,7 @@ async function collectCleanTempFiles(rootAbs) {
 async function promptDeleteConfirmed() {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     try {
-        const ans = await rl.question("\nDelete these files? (y/n) ");
+        const ans = await rl.question(chalk.red("\nDelete these files? (y/n) "));
         return ans === "y";
     }
     finally {
@@ -86,9 +89,16 @@ export async function runCleanTemp(opts) {
         console.log(formatFindPrintLine(rootAbs, abs));
     }
     if (opts.dryRun) {
+        if (files.length > 0) {
+            console.log(chalk.gray("Dry run mode: no files will be deleted."));
+        }
+        else {
+            console.log(chalk.green("Dry run mode: no files to delete."));
+        }
         return;
     }
     if (files.length === 0) {
+        console.log(chalk.green("No files to delete."));
         return;
     }
     const ok = opts.force ? true : await promptDeleteConfirmed();

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

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

@@ -99,6 +99,33 @@ 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;
+/**
+ * True if `relPosix` (project-relative, forward slashes) is under one of the block's
+ * `contentPaths` (file or directory roots).
+ */
+export declare function isProjectRelUnderBlockContentPath(projectRoot: string, relPosix: string, block: {
+    contentPaths: string[];
+}): boolean;
+export declare function isProjectRelUnderAnyDocumentationContentPath(projectRoot: string, relPosix: string, documentations: Array<{
+    contentPaths: string[];
+}>): boolean;
+/**
+ * Expand a normalized project-root `--path` / `--file` to concrete `.md` / `.mdx` paths
+ * (single file or all markdown files under a directory).
+ */
+export declare function expandPathFilterToMarkdownPaths(projectRoot: string, pathFilter: string | undefined): string[];
+export interface AugmentMarkdownFromPathFilterResult {
+    markdown: string[];
+    warnings: string[];
+}
+/**
+ * When the user passes `--path` / `--file`, include matching markdown that normal discovery
+ * skipped (outside `contentPaths`, or under this block but filtered e.g. by `.translate-ignore`).
+ * Paths outside every `contentPaths` are only attached to `documentations[0]`.
+ */
+export declare function augmentMarkdownFilesFromPathFilter(projectRoot: string, pathFilter: string | undefined, documentationBlockIndex: number, documentations: Array<{
+    contentPaths: string[];
+}>, markdownDiscovered: string[]): AugmentMarkdownFromPathFilterResult;
 /**
  * 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

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

@@ -25,6 +25,7 @@ import { applyMarkdownLanguageListPostProcessing, applyMarkdownPostProcessing, }
 import { resolveSvgAssetOutputPath, svgAssetCacheFilepath, svgTranslationFilepathMetadata, } from "../core/svg-asset-paths.js";
 import { ensureDirForFile, hashFileContent, resolveTranslatedOutputPath, writeAtomicUtf8, } from "./helpers.js";
 import { normalizeLocale } from "../core/config.js";
+import { collectFilesByExtension } from "./file-utils.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";
@@ -59,6 +60,9 @@ function emptyMarkdownProtectShell() {
         endMap: [],
         htmlAnchors: [],
         docusaurusHeadingIds: [],
+        mdxMap: [],
+        jsxAttributeMap: [],
+        jsxAttributeText: undefined,
         urlMap: [],
         boldCodeMap: [],
         ilcMap: [],
@@ -72,8 +76,12 @@ export function protectSegmentForTranslation(raw, glossary, locale, useMarkdownP
     if (useMarkdownPlaceholders) {
         const ph = new PlaceholderHandler();
         const st = ph.protectForTranslation(g.text, { emphasis: emphasisPlaceholders });
+        let segmentText = st.text;
+        if (st.jsxAttributeText) {
+            segmentText = `${segmentText}\n${st.jsxAttributeText}`;
+        }
         return {
-            text: st.text,
+            text: segmentText,
             state: {
                 ...st,
                 glossaryForceReplacements: glossaryForceReplacements.length > 0 ? glossaryForceReplacements : undefined,
@@ -243,6 +251,110 @@ export function normalizePathFilterForProjectRoot(projectRoot, raw) {
     }
     return norm;
 }
+const DOC_MARKDOWN_EXTENSIONS = [".md", ".mdx"];
+/**
+ * True if `relPosix` (project-relative, forward slashes) is under one of the block's
+ * `contentPaths` (file or directory roots).
+ */
+export function isProjectRelUnderBlockContentPath(projectRoot, relPosix, block) {
+    const r = relPosix.replace(/\\/g, "/");
+    for (const cp of block.contentPaths) {
+        const rootRel = path
+            .relative(projectRoot, path.resolve(projectRoot, cp))
+            .split(path.sep)
+            .join("/");
+        if (rootRel === "" || rootRel === ".") {
+            return true;
+        }
+        if (r === rootRel || r.startsWith(`${rootRel}/`)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function isProjectRelUnderAnyDocumentationContentPath(projectRoot, relPosix, documentations) {
+    for (const block of documentations) {
+        if (isProjectRelUnderBlockContentPath(projectRoot, relPosix, block)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Expand a normalized project-root `--path` / `--file` to concrete `.md` / `.mdx` paths
+ * (single file or all markdown files under a directory).
+ */
+export function expandPathFilterToMarkdownPaths(projectRoot, pathFilter) {
+    if (!pathFilter?.trim()) {
+        return [];
+    }
+    const abs = path.resolve(projectRoot, pathFilter);
+    if (!fs.existsSync(abs)) {
+        return [];
+    }
+    const st = fs.statSync(abs);
+    if (st.isFile()) {
+        const ext = path.extname(abs).toLowerCase();
+        if (ext === ".md" || ext === ".mdx") {
+            return [path.relative(projectRoot, abs).split(path.sep).join("/")];
+        }
+        return [];
+    }
+    if (st.isDirectory()) {
+        return collectFilesByExtension([abs], [...DOC_MARKDOWN_EXTENSIONS], projectRoot);
+    }
+    return [];
+}
+/**
+ * When the user passes `--path` / `--file`, include matching markdown that normal discovery
+ * skipped (outside `contentPaths`, or under this block but filtered e.g. by `.translate-ignore`).
+ * Paths outside every `contentPaths` are only attached to `documentations[0]`.
+ */
+export function augmentMarkdownFilesFromPathFilter(projectRoot, pathFilter, documentationBlockIndex, documentations, markdownDiscovered) {
+    const warnings = [];
+    if (!pathFilter?.trim() || documentations.length === 0) {
+        return { markdown: markdownDiscovered, warnings };
+    }
+    const block = documentations[documentationBlockIndex];
+    if (!block) {
+        return { markdown: markdownDiscovered, warnings };
+    }
+    const candidates = expandPathFilterToMarkdownPaths(projectRoot, pathFilter);
+    if (candidates.length === 0) {
+        return { markdown: markdownDiscovered, warnings };
+    }
+    const seen = new Set(markdownDiscovered);
+    let md = markdownDiscovered;
+    for (const rel of candidates) {
+        if (seen.has(rel)) {
+            continue;
+        }
+        const abs = path.join(projectRoot, rel);
+        if (!fs.existsSync(abs)) {
+            continue;
+        }
+        const underThis = isProjectRelUnderBlockContentPath(projectRoot, rel, block);
+        const underAny = isProjectRelUnderAnyDocumentationContentPath(projectRoot, rel, documentations);
+        if (underThis) {
+            if (!md.includes(rel)) {
+                md = [...md, rel];
+                seen.add(rel);
+                warnings.push(`${rel}: explicit --path/--file was not in the discovered file set (e.g. outside contentPaths or excluded by .translate-ignore); translating with documentations[${documentationBlockIndex}].`);
+            }
+            continue;
+        }
+        if (underAny) {
+            /* Owned by another documentations[] block; that iteration handles it (or augments there). */
+            continue;
+        }
+        if (documentationBlockIndex === 0) {
+            md = [...md, rel];
+            seen.add(rel);
+            warnings.push(`${rel} is outside every documentations[].contentPaths — translating with documentations[0] output settings.`);
+        }
+    }
+    return { markdown: [...new Set(md)].sort(), warnings };
+}
 async function withCacheMutex(mutex, fn) {
     if (!mutex) {
         return fn();