Skip to content

CLI — UI strings ​

extract ​

Synopsis: ai-i18n-tools extract

Update strings.json from t("…") / i18n.t("…") literals, optional package.json description, and optional bundled-master englishName entries when includeUiLanguageEnglishNames is enabled (see ui.uiExtractor; does not read languagesManifestPath). Also regenerates each block's ui-languages.json. When .html / .htm are listed in ui.uiExtractor.extensions, also captures data-i18n / data-i18n-title / data-i18n-placeholder marker strings from HTML. Walks every ui block that has sourceRoots. --ui-block limits the run to one block (index, description, or stringsJson path). Does not call an LLM.

See also: UI strings overview, Plain HTML apps


migrate-intlayer ​

Synopsis: ai-i18n-tools migrate-intlayer [paths...] [--write] [--report <path>] [--content-glob <glob>] [--t-import <specifier>]

Import Intlayer *.content.ts dictionaries into strings.json and flat locale files, and rewrite simple useIntlayer / getIntlayer call sites to t('source string'). The string is written in sourceLocale, which can be any language. Dry run by default (the report is still written). --write seeds the catalog and applies safe rewrites. Does not call an LLM.

The report is the handoff for everything --write leaves behind, and it ends with a Step-by-step TODO that orders the rest of the work: a concrete t() or JSX call for each manual site, the import { t } line, dictionary files and IntlayerProvider leftovers to delete afterwards, source strings that need extract then translate-ui, and an i18next runtime bootstrap to paste over the app's i18n module. The locale control must call i18n.changeLanguage as well as loadLocale. extract writes ui-languages.json, which that bootstrap imports. Do not edit strings.json, the flat locale files, or ui-languages.json by hand.

Key options: --write, --report, --content-glob (default **/*.content.ts), --t-import

See also: Migrating from Intlayer


translate-intlayer ​

Synopsis: ai-i18n-tools translate-intlayer [paths...] [-l <codes>] [--ui-block <selector>] [--dry-run] [-j <n>]

Translate missing and stale locale leaves inside Intlayer *.content.ts dictionaries in place, keeping the dictionaries as the source of truth. Unlike migrate-intlayer, this does not move the app off Intlayer; it only fills the t({ … }) leaves. Use it when you want to keep Intlayer at runtime and use ai-i18n-tools as the translation engine.

It extracts every t({ … }) leaf, seeds the chosen UI block's strings.json with the source text, runs the same engine as translate-ui (provider selection, glossary, translation context, and model fallback), then writes the new per-locale strings back into each t({ … }) object. Edits are precise: only the missing or stale locale lines change, so your formatting and comments are preserved. Intlayer {token} placeholders round-trip to {{token}} for translation and back.

A leaf+locale is translated when the locale is absent from the leaf (missing), or when the source-locale text changed since the last run for that locale (stale). Staleness is tracked in cacheDir, so editing that source string re-translates that one leaf on the next run. The source language is sourceLocale and can be any language. --dry-run reports the missing/stale counts without calling an LLM or writing anything. Requires features.translateUIStrings and the UI block's stringsJson (same as translate-ui).

Key options: -l / --locale, --ui-block, --dry-run, -j / --concurrency

[paths...]: files/dirs/globs to scan (default: the block's sourceRoots). -l / --locale: comma-separated target locales to fill (default: the block's configured targetLocales). --ui-block: zero-based index, description, or stringsJson path (default: block 0). -j parallelises locales.

See also: migrate-intlayer, Migrating from Intlayer


mark-html ​

Synopsis: ai-i18n-tools mark-html [paths...] [--write]

Insert bare data-i18n / data-i18n-title / data-i18n-placeholder markers into HTML so the source text is written once (on the element itself). Scans the given files/dirs/globs (default: .html / .htm under every block's sourceRoots). Dry run by default (reports per-file add counts and any mixed-content elements that need a manual <span data-i18n>); --write applies changes. Idempotent, honours data-i18n-ignore (skips the element and its subtree), never touches code-like elements (code, pre, kbd, samp, var) or empty/numeric-only text, and never emits a valued marker. Does not call an LLM.

Key options: --write

See also: Marking HTML for translation


generate-ui-languages ​

Synopsis: ai-i18n-tools generate-ui-languages [--master <path>] [--dry-run]

Write ui-languages.json to languagesManifestPath (defaults to {ui.flatOutputDir}/ui-languages.json) using sourceLocale + targetLocales and the bundled data/ui-languages-complete.json (or --master). Warns and emits TODO placeholders for locales missing from the master file. If you have an existing manifest with customised label or englishName values, they will be replaced by master catalog defaults — review and adjust the generated file afterwards.

Key options: --master, --dry-run


translate-ui ​

Synopsis: ai-i18n-tools translate-ui [-l <codes>] [--force] [--dry-run] [-j <n>]

Translate UI strings only (strings.json → locale JSON). Requires features.translateUIStrings.

Key options: -l / --locale, --force, --dry-run, -j / --concurrency

-l / --locale: comma-separated target locales (default: config targetLocales minus sourceLocale). --force: re-translate all entries per locale (ignore existing translations). --dry-run: no writes, no API calls. -j parallelises locales; within each locale, config uiBatchConcurrency (default 2) parallelises LLM batches (chunks of 50 strings, then plural groups). There is no CLI flag for uiBatchConcurrency. Each successful batch is written to strings.json and the flat locale file before the next batch starts. sync-ui and the UI step of sync use the same write.

A stored translation whose placeholders do not match its source is translated again. The check covers a renamed name ({schedule} becoming {cronograma}), a dropped or invented token, and a format-spec change ({price:,.2f} becoming {price}). The count is printed before the batch, including on --dry-run. A row whose model is user-edited is left in place and only warned about. A string that is only placeholders and punctuation, such as {state} · {title}, is copied and not sent to a model. A batch that renames a placeholder is rejected and the next model in the chain is tried with that error appended. The dashboard flags the same rows and asks before saving a translation that breaks a placeholder.


sync-ui ​

Synopsis: ai-i18n-tools sync-ui [-l <codes>] [--force] [--dry-run] [-j <n>]

Extract, then translate UI strings (requires features.translateUIStrings). UI-only — no documentation, SVG, or json[]. Same -l, --force, --dry-run, and -j options as translate-ui.


proofread-ui ​

Synopsis: ai-i18n-tools proofread-ui [-l <code>] [--chunk <n>] [--dry-run] [--json] [-j <n>]

Runs extract first (requires features.translateUIStrings) so each selected catalog matches source, then performs an LLM review of source-locale UI strings (spelling, grammar). --ui-block limits extract and review to one block. Terminology hints come from glossary.userGlossary CSV only (same scope as translate-ui — UI catalogs are not fed back in, so bad copy is not reinforced as glossary). Uses the active LLM provider (its API-key env var).

Exits 1 on failure (missing feature flag, extract failure, missing/invalid catalog, missing API key, or when all batches fail); exit 0 when the run completes successfully (findings are advisory). Writes proofread-ui-results_<timestamp>.log under cacheDir as a human-readable report (summary, issues, not-reviewed rows, and per-string OK rows); the terminal prints summary counts and issues only (no [ok] lines per string). A batch that fails, or a model response that is shorter than the batch and has no usable index on each slot, counts those strings as not reviewed. Their issues are dropped so a short array is not applied to the wrong strings. Prints the log filename on the last line. With --json, human-style output goes to stderr. Links use path:line like the dashboard UI strings link button.

Key options: -l / --locale, --chunk (default 50), --dry-run, --json, -j / --concurrency


export-ui-xliff ​

Synopsis: ai-i18n-tools export-ui-xliff [-l <codes>] [-o <dir>] [--untranslated-only] [--dry-run]

Export strings.json to XLIFF 2.0 (one .xliff per target locale). Read-only; no API.

Key options: -l / --locale, -o / --output-dir, --untranslated-only, --dry-run

-o / --output-dir: output directory (default: same folder as the catalog). --untranslated-only: only units missing a translation for that locale.

Released under the MIT License.