Command reference

The linter installs as the npm package @loccy-dev/lint and runs as the loccy command. It has three subcommands:

npx loccy init     # scaffold loccy.yaml
npx loccy lint     # lint translations and usages
npx loccy format   # sort translation files

Run npx loccy --help or npx loccy <command> --help for inline help, npx loccy --version to print the version. See Get started for installation and setup.

#loccy init

Detects your project setup and generates loccy.yaml in the repo root: project configuration auto-detected from your codebase, plus commented styleguide and glossary examples for AI translations.

npx loccy init

This is the CLI equivalent of the IDE command "Loccy: Create Config File". Both generate the same file. See loccy.yaml for all options, including the styleguide format.

#loccy lint

Checks your translation files and key usage. With --fix, removes unused keys (the only auto-fixable issue). Sorting is a separate command; see loccy format.

npx loccy lint
npx loccy lint --fix

#Checks

Lint runs up to two check groups, controlled by the lint rules on each module's usages and translations:

Check group	Rule	Lives on	What it finds	Fixable with `--fix`
Missing translations	`noUntranslatedKeys`	`translations`	Keys with missing or empty values in checked locales	No
Usage	`noUnusedKeys`	`usages`	Keys defined in translations but never used in code	Yes, removes the keys from all translation files
Usage	`noUnresolvedKeys`	`usages`	Keys used in code but missing from translations	No

#Missing translations

Checks every key across locales. All locales detected in your translation files are checked, except partial-override locales in styleguide.locales (entries with an extends/style value), whose intentionally-empty keys are skipped; noUntranslatedKeys itself is a simple on/off boolean. Each reported key has one of three kinds:

Kind	Meaning
`missing`	Key is absent in one or more checked locales
`empty`	Key exists but its value is blank in one or more checked locales
`incomplete`	Both: absent in some locales and blank in others

For every reported key, the value (or its absence) is printed per locale. These issues require a manual fix, or use the IDE extension's Fill empty translations to fill the gaps.

#Usage

Runs only when usage scanning is configured (usages in the config). It scans your code for translation key usages and reports:

unused: keys present in translation files but never referenced in code. Fixable: --fix removes them from all translation files, cleaning up empty parent objects.
missing: keys referenced in code but absent from translation files, with the file:line locations where they are used. Not fixable automatically.

Both rules support key exclusion patterns in the config. See loccy.yaml.

#Sample output

✔ Loaded loccy.yaml (framework: react-i18next)
✔ Extracted 482 translations

Missing translations
  missing common:settings.title  locales/en/common.json
    de    (missing)
    en    Settings
  empty common:profile.bio  locales/en/common.json
    de    (empty)
    en    Tell us about yourself

Usage
  unused legacy.banner
  missing nav.reports  src/components/Nav.tsx:42

1 fixable issue, run loccy lint --fix
3 issues require manual fix

#Exit code

Lint exits with code 1 when any issues remain after the run (including fixable ones on a run without --fix), so it fails any CI pipeline that runs it as a merge gate.

#Debugging

Set LOCCY_LINT_DEBUG=1 to print extra diagnostics, such as which locales were detected in translation files and which are being checked by the missing-translations rule:

LOCCY_LINT_DEBUG=1 npx loccy lint

#loccy format

Deeply sorts keys in the translation files of every module that declares translations.sortKeys: true, rewriting each file sorted while preserving its indentation and trailing newline. Modules without sortKeys are left untouched; if no module opts in, format is a no-op.

npx loccy format          # sort files in place
npx loccy format --check  # report unsorted files and exit 1, writing nothing (for CI)

Sorting is deliberately split from loccy lint: lint reports problems and --fix only removes unused keys, while format is the one command that reorders keys: run it on demand or in a pre-commit hook. In CI, use --check: it verifies sort order and exits 1 if any file needs sorting, without rewriting anything. The IDE enforces the same sortKeys invariant automatically on every write. Like the other commands, format needs a loccy.yaml and accepts --config <path>.