CLI reference

Run ai-i18n-tools <command> --help for every flag on a command. Group pages below add context, key options, and links to topic guides.

Command overview

Getting started

Command	Summary
version	Print CLI version and build timestamp.
init	Write a starter config; -t selects a scaffold template.
help	Display help for a subcommand.

Models & languages

Command	Summary
check-models	Validate configured model ids against the active provider.
list-models	List models advertised by the active provider.
bench-models	Benchmark configured models on one sample translation.
list-languages	List the bundled UI languages catalog.

UI strings

Command	Summary
extract	Update strings.json from source literals and HTML markers.
mark-html	Insert data-i18n* markers into HTML files.
migrate-intlayer	Import Intlayer .content.ts dictionaries and rewrite simple useIntlayer / getIntlayer sites to t().
generate-ui-languages	Write ui-languages.json from config locales.
translate-ui	Translate UI strings (strings.json → locale JSON).
sync-ui	Extract, then translate UI strings.
proofread-ui	Extract, then LLM-review source-locale UI strings.
export-ui-xliff	Export strings.json to XLIFF 2.0.

Documents

Command	Summary
translate-docs	Translate markdown, MDX, .astro, and framework catalogs.
write-heading-ids	Insert HTML anchor lines before ATX headings.
check-markdown	Scan markdown/MDX for delimiter and emphasis issues.

JSON & SVG

Command	Summary
translate-json	Translate nested JSON per json[] config blocks.
translate-svg	Translate SVG files configured in config.svg.

Workflows & reporting

Command	Summary
sync	Run extract + UI + SVG + docs + JSON in one pipeline.
status	Print UI, documentation, and JSON translation coverage.
statistics	Print cache and strings.json statistics.
usage	Print recorded model API-call tokens and costs.

Cache maintenance

Command	Summary
cleanup	Prune stale/orphan/unconfigured-locale cache rows and repopulate markdown issues.
clean-temp	Find and delete *.log, *.tmp, and cache backups.
purge-locale	Remove cache rows and generated artifacts for locale(s).

Dashboard & glossary

Command	Summary
dashboard (dash)	Launch the Translation Dashboard web UI.
glossary-generate	Write an empty glossary-user.csv template.

Synopsis

ai-i18n-tools version
ai-i18n-tools init [-t ui-markdown|ui-docusaurus|ui-starlight|ui-vitepress|ui-nextra|ui-fumadocs|ui-astro-website|ui-json-bundles] [-o path] [-P <provider>] [--with-translate-ignore]
ai-i18n-tools help [command]
ai-i18n-tools check-models
ai-i18n-tools list-models
ai-i18n-tools bench-models [--model <ids>] [--text <text>|--file <path>] [--source <locale>] [--target <locale>]
ai-i18n-tools list-languages [search]
ai-i18n-tools extract
ai-i18n-tools mark-html [paths...] [--write]
ai-i18n-tools migrate-intlayer [paths...] [--write] [--report <path>] [--content-glob <glob>] [--t-import <specifier>]
ai-i18n-tools generate-ui-languages [--master path] [--dry-run]
ai-i18n-tools translate-ui …
ai-i18n-tools sync-ui …
ai-i18n-tools proofread-ui …
ai-i18n-tools export-ui-xliff …
ai-i18n-tools translate-docs …
ai-i18n-tools write-heading-ids …
ai-i18n-tools check-markdown [-p|--path <path>] [-f|--file <path>] [--json] [--no-cache]
ai-i18n-tools translate-json …
ai-i18n-tools translate-svg …
ai-i18n-tools sync …
ai-i18n-tools status …
ai-i18n-tools statistics …
ai-i18n-tools usage …
ai-i18n-tools cleanup …
ai-i18n-tools clean-temp …
ai-i18n-tools purge-locale -l <code> [-l <code> …] [--dry-run] [-y|--yes] [-f|--force] [--keep-files] [--backup <path>]
ai-i18n-tools dashboard …
ai-i18n-tools glossary-generate

Root and global options

Option	Scope	Description
-V / --version	Root program	Output version number and build timestamp (same information as the version subcommand).
-h / --help	Root program	Display help for the root program or for a subcommand when used with a command name.
-c / --config <path>	Every command	Config file path (default: ai-i18n-tools.config.json).
-v / --verbose	Every command	Verbose logging.
-P / --provider <name>	Every command	Active LLM provider for this run; overrides the config provider key. Must be configured under providers.
-L / --ui-lang <code>	Every command	Language for the tool's own UI (CLI help, logs/summaries, dashboard); highest-priority source. See Tool UI language.
-w / --write-logs [path]	Selected commands	Tee console output to a .log file (default path: under root cacheDir). Wired for translate-docs, translate-json, translate-svg, translate-ui, sync-ui, sync, and cleanup only.
--debug-failed	Translation commands	Write FAILED-TRANSLATION logs under root cacheDir for each discarded translation-check (wrong script, parse, or quality), including fallbacks — not only when every model fails. Provider API / empty-body errors print on the console (once per model and error message) and do not write those files. Applies to translate-ui, translate-docs, translate-json, translate-svg, sync-ui, sync, and cleanup.

Per-command help

Usage	Description
ai-i18n-tools <command> --help	All options for that command.
ai-i18n-tools help <command>	Same output as <command> --help.

Target locales (-l / --locale)

Commands	Behaviour
translate-docs, translate-json, translate-svg, translate-ui, sync, sync-ui, export-ui-xliff	-l / --locale <codes> — comma-separated target BCP-47 codes (e.g. de,fr,pt-BR). When omitted, defaults come from config (json[] blocks may also set per-block targetLocales; UI steps use targetLocales minus sourceLocale).
proofread-ui	-l / --locale <code> — single source locale to review (default: config sourceLocale).