find_undefined_keys
Find keys referenced in source code but defined in NO locale layer the using app consumes — the direction that ships raw keys to production. The inverse of find_orphan_keys. Scope-aware: each scan unit (app) is checked against the layers it consumes (summary.searchedLayersByApp), so a key defined only in a layer the using app does not consume is still undefined for that app. Known limitation: extraction is line-based and static — dynamically built keys (template literals, concatenation) cannot be verified and are reported as uncertainKeys, never as hard findings. With write, the hard findings are also added to a locale file as empty translations, which is the first half of the fix; uncertain findings are never written.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
locale | string | no | Reference locale to resolve key definitions in (e.g., "en", "en-US"). Defaults to the project default locale. |
write | boolean | no | Add every undefined key to a locale file, with an empty string as its value, in the project default locale only. Existing values are never touched, and uncertain findings are never written. The layer is the one the using code resolves against; when that is more than one layer, the run refuses and asks for a layer name. Default: false, which only reports. |
layer | string | no | Layer to write the undefined keys into (e.g., "root", "app-admin"). Only read together with write, and only needed when the using code resolves against more than one layer. Call discover to list the layers. |
scanDirs | string[] | no | Absolute paths of the directories to scan for source usage. Overrides scope-aware scanning: every layer is then checked against these directories alone. Example: "/home/user/my-app/apps/admin". |
excludeDirs | string[] | no | Directory names to skip when scanning source files. Example: "storybook", "tests", "node_modules". |
outputFile | string | no | Absolute path to write the full JSON output to. Only a compact summary is returned to the caller, which is what you want for a result too large to read in one piece. Example: ".i18n-reports/undefined-keys.json" |
projectDir | string | no | Absolute path to the project root. Defaults to I18N_PROJECT_DIR, then server cwd. Example: "/home/user/my-app". |
Result
| Field | Type | Description |
|---|---|---|
undefinedKeys | object[] | Hard findings: keys that render raw at runtime. A write run leaves them listed, because the call sites are what a reader has to visit either way. |
uncertainKeys | object[] | Findings static extraction cannot verify. Never written, never counted by the gate. |
limitation | string | What this scan cannot see, in one paragraph. Read it before acting on the uncertain findings. |
written | object | Present only when write was asked for and the scan found something to write. |
summary | object | What the scan covered and what it found. This is what comes back when the full result is diverted to a file. |
reportFile | string | Absolute path the full JSON result was written to. Read the file for the findings; the summary below is all that came back. |
Behavior Hints
A host reads these to decide whether a call needs your confirmation first.
| Hint | Value |
|---|---|
readOnlyHint | false |
destructiveHint | false |
idempotentHint | true |
openWorldHint | false |
Paired CLI Command
The same operation runs from a terminal as the-i18n-cli check, whose page documents its flags.