@kystverket/sprak-cli

CLI tool for detecting missing or incorrect translations in your i18n JSON files.

Installation

npm install @kystverket/sprak-cli

Usage

sprak check [configPath] [options]

The CLI reads a .sprak.json config file and runs checks against your translation files.

Arguments

| Argument | Description | | -------------- | --------------------------------------------------------------------------- | | [configPath] | Path to a .sprak.json config file. Auto-detected if omitted. |

Options

| Option | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------- | | -c, --config | Explicit path to a .sprak.json config file (overrides positional argument). | | --checks <list> | Comma-separated list of checks to run. Defaults to all. | | --json | Output results as JSON instead of formatted text. | | --no-fail | Always exit with code 0, even if issues are found. |

Exit Codes

| Code | Meaning | | ---- | -------------------------------------------------- | | 0 | No issues found (or --no-fail was used). | | 1 | Issues found. | | 2 | Error during execution (config not found, etc.). |

Checks

All checks compare translations against the mainLanguage defined in your config.

| Check | Description | | ---------------------- | --------------------------------------------------------------------------------------------- | | missing-keys | Keys present in the main language but missing from other languages. | | extra-keys | Keys present in other languages but not in the main language. | | empty-values | Keys with empty, null, or undefined values in any language. | | untranslated | Keys where a non-main language has an identical value to the main language. | | placeholder-mismatch | Keys where interpolation placeholders differ between the main language and other languages. |

Untranslated Check

The untranslated check skips values that are considered untranslatable:

• Very short strings (≤ 3 characters, e.g. "OK", "ID")
• URLs
• Email addresses
• Pure numbers

Placeholder Mismatch Check

Detects mismatched placeholders in these formats:

• {{name}} (i18next/ICU style)
• {0}, {1} (positional)
• %(name)s (Python style)
• %s, %d, %f (printf style)

Config File

The CLI reads a .sprak.json file with the following structure:

{
  "pattern": "i18n/:namespace/:language.json",
  "mainLanguage": "en",
  "sort": false,
  "jsonStyle": "nested",
  "delimiter": ".",
  "ignore": [
    { "key": "appName" },
    { "key": "nav.*", "checks": ["untranslated"] },
    { "key": "email", "checks": ["untranslated"], "languages": ["no"] }
  ]
}

| Field | Type | Required | Description | | -------------- | ----------------------- | -------- | ------------------------------------------------------------------ | | pattern | string | Yes | File path pattern with :language and optional :namespace placeholders. | | mainLanguage | string | Yes | Reference language code (e.g. "en"). | | sort | boolean | No | Sort keys alphabetically. Defaults to false. | | jsonStyle | "flat" \| "nested" | No | How keys are stored on disk. Defaults to "nested". | | delimiter | string | No | Delimiter for flat-style keys. Defaults to ".". | | ignore | IgnoreRule[] | No | Keys or patterns to ignore in checks. |

Ignore Rules

Each ignore rule has a key pattern and optional checks and languages arrays to limit which checks and languages the rule applies to:

| Field | Type | Required | Description | | ----------- | ---------- | -------- | ------------------------------------------------------------------ | | key | string | Yes | Key pattern to match (see patterns below). | | checks | string[] | No | Only ignore the key for these checks. All checks if omitted. | | languages | string[] | No | Only ignore the key for these languages. All languages if omitted. |

Key Patterns

• Exact match: "appName"
• Wildcard: "nav.*" (matches one level, e.g. nav.home)
• Deep wildcard: "nav.**" (matches any nesting depth under nav)

Language-Scoped Ignoring

Some translations are legitimately identical to the main language in certain languages (e.g. "Email" is the same in English and Norwegian). Use the languages field to suppress the untranslated check only for specific languages instead of ignoring the key globally:

{ "key": "email", "checks": ["untranslated"], "languages": ["no"] }

This ignores the untranslated warning for "email" in Norwegian only. Other languages are still checked.

Pattern Examples

| Pattern | Structure | | ------------------------------------ | -------------------------------------------- | | i18n/:language.json | One file per language | | i18n/:namespace/:language.json | Namespace folders with language files | | i18n/:language/:namespace.json | Language folders with namespace files |

Output

Default (Human-Readable)

  Config: i18n/i18n.sprak.json
  Main language: en
  Languages: en, no | Namespaces: default, common

  ━━━━━━━━━━━━━ Missing Keys (2) ━━━━━━━━━━━━━

    no      nav.home
    ⚠ Key "nav.home" exists in en but is missing in no

  ⚠ 2 issue(s) found
    Missing Keys: 2

JSON (--json)

[
  {
    "check": "missing-keys",
    "namespace": "default",
    "language": "no",
    "key": "nav.home",
    "message": "Key \"nav.home\" exists in en but is missing in no"
  }
]

Example

Run all checks with auto-detected config:

sprak check

Run specific checks:

sprak check --checks missing-keys,empty-values

Output as JSON (useful for CI):

sprak check --json

License

ISC