Skip to main content

​
Usage

​
Default checks

Each check has a severity (error or warning) in the report JSON and in stylish output. Exit code 1 applies when any finding exists unless you pass --no-fail. With --quiet, only error findings count toward the exit code and printed/JSON output; warning-only runs exit 0. With --diff-stdin, check reads a unified git patch from stdin and validates changed keys only for supported key-value translation files: .json, .jsonc, and .arb. In this mode, the CLI ignores unsupported file types in the patch, treats configured files with no identifiable changed keys as a no-op, and skips file-level or document-level checks that do not fit key-scoped diff validation.

​
Error

  • not_localized: target key is missing or the target value is empty (after trimming)
  • missing_target_file: resolved target file does not exist
  • placeholder_mismatch: placeholders differ from the source
  • html_tag_mismatch: inline HTML tag names (known elements from the HTML tokenizer’s tag set) differ in sequence between source and target. Angle-bracket text in paths or docs—such as <name> in llm.profiles.<name>.provider—does not count as HTML for this check
  • icu_shape_mismatch: ICU structure differs from the source or is malformed (non-markdown files)
  • markdown_ast_mismatch: markdown or MDX document structure differs from the source (heading/component tree parity)

​
Warning

  • same_as_source: target value matches the source text. Common for brands, codes, or locale-neutral strings; use --exclude-check same_as_source if you want to hide these
  • orphaned_key: target key exists but the source key does not
  • whitespace_only: target value contains only whitespace
Selecting --check icu_shape_mismatch runs ICU checks only; it does not include markdown_ast_mismatch. Use both flags if you need ICU and MD/MDX structure checks together.

​
Flags

  • --config: path to config file
  • --locale: target locale filter (repeatable)
  • --group: filter by group name
  • --bucket: filter by bucket name
  • --file: filter by source file path. Not supported with --diff-stdin
  • --key: filter by translation key. With --diff-stdin, this becomes an extra intersection filter on top of the changed keys extracted from the patch. With --prefix-id, the filter is applied after stripping the source key prefix (use the packed id, for example title rather than src.components.app-header.title)
  • --prefix-id: strip extract --prefix-id filename prefixes from source keys before comparing them to target keys, using the same rules as pack --prefix-id. Use this when sources still have prefixed ids (for example src.components.app-header.title) but targets were packed without those prefixes (for example title). Target keys are never stripped. Also applies to --key filters and changed keys from --diff-stdin on source files. If two prefixed source keys strip to the same packed id, check exits with an error unless --ignore-duplicate-id is set. With --fix, findings report the packed id but retranslation uses the original prefixed source key
  • --ignore-duplicate-id: ignore duplicate packed ids and keep the first value. Same behavior as pack --ignore-duplicate-id. Useful with --prefix-id when multiple source ids strip to the same packed id
  • --diff-stdin: read a unified diff from stdin and validate changed keys only. Supports configured .json, .jsonc, and .arb files. Runs only key-scoped checks: not_localized, same_as_source, whitespace_only, placeholder_mismatch, html_tag_mismatch, and icu_shape_mismatch. Skips missing_target_file, orphaned_key, and markdown_ast_mismatch. Pair with --prefix-id when the diff touches prefixed source keys but targets use packed ids
  • --check: run only specific checks (repeatable)
  • --exclude-check: skip specific default checks (repeatable)
  • --format: output format (stylish default, text, or json). Stylish prints ESLint-style diagnostics grouped by file; when stdout is a terminal, severities use color (no color when piped or in typical CI logs).
  • --output-file: write the same human or JSON format as stdout to a file
  • --json-report: always write the full machine-readable JSON report to this path, regardless of --format (useful in CI: stylish logs plus a JSON artifact for tooling). Findings include annotationFile and annotationLine when the CLI can map a key to a line. For .md / .mdx segments with keys prefixed md., the line is taken from the markdown/MDX parse order (start of that translatable segment). For other files, resolution falls back to searching for a quoted key fragment or a substring of the segment text in the target file, which can mis-rank lines when the same text appears more than once
  • --no-fail: return exit code 0 even when findings exist
  • --quiet: omit warning findings from stdout, --output-file, and --json-report; use exit code 0 when the full result would be warnings only. The internal check still runs on all severities; --fix still plans from the full result (including warnings) so fixable issues are not skipped.
  • --fix: after reporting, retranslate fixable findings using the same AI pipeline as run (same config, profiles, and environment variables). Applies to keyed findings of types not_localized, whitespace_only, placeholder_mismatch, html_tag_mismatch, and icu_shape_mismatch. For markdown_ast_mismatch on .md/.mdx files (per-file findings, often without a key), --fix retranslates all aligned segments for that source/target/locale pair so structure can realign. Does not fix same_as_source (intentional copy), missing target files, or orphaned keys.
  • --fix-dry-run: with --fix, resolve planned translation tasks without writing targets or calling the model (still loads config and planning).
  • --workers: with --fix, number of parallel translation workers (default: number of CPU cores)

​
Examples

Check sources with prefixed ids against packed target files:

​
See also