> ## Documentation Index > Fetch the complete documentation index at: https://hyperlocalise.dev/llms.txt > Use this file to discover all available pages before exploring further. # check > Check localized files for not-localized content, orphaned keys, missing target files, and translation hygiene issues. ## Usage ```bash theme={null} hyperlocalise check [--config ] [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 `<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`](/commands/extract) filename prefixes from **source** keys before comparing them to target keys, using the same rules as [`pack --prefix-id`](/commands/pack). 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`](/commands/pack). 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`](/commands/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 ```bash theme={null} hyperlocalise check --bucket docs ``` ```bash theme={null} hyperlocalise check --no-fail --json-report report.json ``` ```bash theme={null} hyperlocalise check --format text --no-fail --output-file report.txt ``` ```bash theme={null} hyperlocalise check --format json --no-fail --output-file report.json ``` ```bash theme={null} hyperlocalise check --check orphaned_key --check missing_target_file ``` ```bash theme={null} hyperlocalise check --fix --locale fr --bucket ui ``` ```bash theme={null} hyperlocalise check --fix --fix-dry-run --no-fail ``` ```bash theme={null} git diff --cached | hyperlocalise check --diff-stdin --no-fail ``` Check sources with prefixed ids against packed target files: ```bash theme={null} hyperlocalise check --prefix-id ``` ```bash theme={null} git diff --cached | hyperlocalise check --diff-stdin --prefix-id --no-fail ``` ## See also * [extract](/commands/extract) * [pack](/commands/pack) * [status](/commands/status) * [run](/commands/run)