CLI — Documents
translate-docs
Synopsis: ai-i18n-tools translate-docs [options]
Translate markdown, MDX, .astro, optional Docusaurus catalog JSON (docusaurusCatalogDir), optional Nextra _meta.ts/dictionary .ts, and optional VitePress theme catalog for each docs block.
Key options: -l, -j, -b, --prompt-format, --force, --force-update, --check-cache, -p / -f, --dry-run
-j: max parallel locales; -b: max parallel batch API calls per file. --prompt-format: batch wire format (xml | json-array | json-object).
See also: Cache behaviour and translate-docs flags, Batch prompt format
write-heading-ids
Synopsis: ai-i18n-tools write-heading-ids [options]
Requires at least one docs[] block. Collects .md / .mdx under each block's contentPaths (honours .translate-ignore). By default inserts an HTML anchor line <a id="slug"></a> immediately before each flat ATX # heading (skips headings inside fenced code blocks). Existing heading ids of any form (HTML anchor line, classic {#id} suffix, MDX {/* #id */} comment) are replaced with the selected style; the slug is always derived from the current heading text. With --slug-style mdx-comment, writes a Docusaurus MDX comment suffix on the heading line instead (same github-style slug algorithm) and drops a preceding HTML anchor when present. --remove strips all of those heading-id forms and writes nothing in their place.
After updating source files, the command also walks each locale's existing translated markdown (same docsOutput path mapping as translate-docs). It copies the English heading ids onto the matching ATX headings in document order — it never slugs the translated title — and moves a mid-heading {#id} / {/* #id */} (or stray HTML <a id>) back to the form Docusaurus / the chosen style expects. Missing translated files are skipped. --remove strips heading ids from those translated files as well, including misplaced mid-line tokens.
When a translated file's heading ids are repositioned or repaired, the matching cached translated segment (keyed by the English source hash) is updated too, if the English source and the old and new translated content have the same number of segments. A count mismatch skips that file and locale. A later sync --force-update then reassembles the file from the updated cache row.
Key options: -p / --path, -f / --file, --slug-style, --remove, --dry-run
--slug-style: github (default; doctoc / anchor-markdown-header), bitbucket, gitlab, pymdown, azure-devops, mdx-comment (Docusaurus {/* #… */} suffix). With pymdown, optional --pymdown-case, --pymdown-normalize, --pymdown-percent-encode / --no-pymdown-percent-encode. --remove cannot be combined with --pymdown-*.
See also: Anchor links
check-markdown
Synopsis: ai-i18n-tools check-markdown [options]
Scans markdown/MDX under each docs[] block's contentPaths (same discovery as translate-docs, honours .translate-ignore): delimiter pairing, unclosed inline code, and STRONG_OUTSIDE_LINK when **/__ wrap a [text](url) link.
Prints relativePath:line: [ISSUE_CODE] message lines to stderr; exit code 1 if any issue. --json: JSON report on stdout. Writes markdown_source_issues in cacheDir unless --no-cache. -v adds source hashes to stderr lines.
Key options: -p / --path, -f / --file, --json, --no-cache
See also: Markdown issues