Skip to content

Agent skill

Install the ngx-translate skill to give a coding agent guidance for setup, migrations, and translation audits. Its bundled checker compares JSON catalogues for missing keys, extra keys, value types, and interpolation parameters.

The skill is available in the core repository. The checker runs directly from the skill folder; it does not need npm installation or a build step.

You need an agent that supports skills and can run local commands. The checker requires Node.js 22 or later.

  1. Get a separate checkout of the core repository’s develop branch:

    Terminal window
    git clone --branch develop --single-branch https://github.com/ngx-translate/core.git ngx-translate-skills
  2. Copy ngx-translate-skills/skills/ngx-translate into your agent’s configured skills directory. Keep SKILL.md, scripts/, and LICENSE together.

  3. Enable the skill using your agent’s instructions and ask it to check your catalogues. For example:

    Use the ngx-translate skill to compare public/i18n/fr.json and public/i18n/de.json against en.json.
    Explain missing keys and interpolation mismatches without modifying the files.

The skill checks the application’s installed library versions before choosing APIs for setup or migrations. For catalogue audits, it uses the bundled checker and explains the findings in the context of your application’s configuration.

You can run the checker without an agent. Replace /path/to/ngx-translate below with the installed skill directory, and /path/to/app/public/i18n with the directory containing your catalogues.

List the JSON files directly inside that directory:

Terminal window
node "/path/to/ngx-translate/scripts/check.mjs" list --root "/path/to/app/public/i18n"

The listing is sorted and excludes subdirectories and symlink entries. Use --directory feature to list a subdirectory relative to --root.

Compare target languages against the source catalogue:

Terminal window
node "/path/to/ngx-translate/scripts/check.mjs" audit --root "/path/to/app/public/i18n" --source en.json --target fr.json --target de.json

Repeat --target for each language. The --root argument is required; catalogue paths must be relative to it. Paths and symlinks that escape this root are rejected. The checker reads files without modifying them. Run node "/path/to/ngx-translate/scripts/check.mjs" --help for command usage.

An audit writes JSON to stdout with sourceFile and a results array. Each target report contains its file and these findings:

FieldMeaning
missingKeysKeys present in the source but absent from the target
extraKeysKeys present in the target but absent from the source
placeholderMismatchesKeys with missing or extra interpolation parameter names
typeMismatchesKeys whose scalar or empty-container types differ, with expected and actual types

For {"hello":"Hello {{name}}"} in en.json and {"hello":"Bonjour {{person}}"} in fr.json, the audit returns:

{
"sourceFile": "en.json",
"results": [
{
"file": "fr.json",
"missingKeys": [],
"extraKeys": [],
"placeholderMismatches": [{ "key": "hello", "missing": ["name"], "extra": ["person"] }],
"typeMismatches": []
}
]
}

The process exit code distinguishes findings from an incomplete audit:

Exit codeMeaning
0The audit completed with no differences, or a list/help command succeeded
1The audit completed with differences; read stdout
2Invalid arguments or an incomplete audit; read the JSON error on stderr

An error produces no partial report. Fix unreadable files or invalid input and rerun before treating any requested catalogue as checked. Malformed JSON, non-object catalogue roots, and ambiguous flat and nested keys that produce the same path are rejected.

The checker compares nested objects and dotted keys by flattened paths. Arrays use numeric indices. Placeholder checks follow the default TranslateDefaultParser syntax, such as {{name}} or {{ name }}. Repeated parameters and their order do not affect the comparison.

Account for fallback languages and merged loader resources before treating an absent key as a defect. The checker compares the files as supplied and does not emulate runtime translation lookup. Custom parsers and ICU/messageformat compilers need their own validation.

An extra key is absent from the source catalogue. It may still be used by the application, including through a dynamically constructed key. The checker does not scan application references, so confirm usage before deleting keys.

ResourceLimit
Targets per audit20
Catalogue size1 MiB per file
Catalogue entries10,000, including containers
Nesting depth100 levels
Directory listing1,000 JSON files
JSON output2 MiB

Commands return exit code 2 if a limit is exceeded. Compare fewer files, choose a smaller directory, or split catalogues as appropriate.

ImprintPrivacy