Skip to main content

​
Usage

hyperlocalise check [--config <path>] [flags]

​
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 &lt;name&gt; in llm.profiles.&lt;name&gt;.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
  • --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
  • --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

hyperlocalise check --bucket docs

hyperlocalise check --no-fail --json-report report.json

hyperlocalise check --format text --no-fail --output-file report.txt

hyperlocalise check --format json --no-fail --output-file report.json

hyperlocalise check --check orphaned_key --check missing_target_file

hyperlocalise check --fix --locale fr --bucket ui

hyperlocalise check --fix --fix-dry-run --no-fail

git diff --cached | hyperlocalise check --diff-stdin --no-fail

​
See also