Misplaced Usages

A misplaced usage is a key referenced only from apps that do not consume its layer. Calling it used would protect a key on the strength of a reference that cannot resolve at runtime; calling it an orphan would delete a key a real call site depends on. So it gets its own bucket:

{
  "misplacedUsages": [
    { "key": "checkout.cart.title", "layer": "checkout", "usingApps": ["admin"] }
  ]
}

layer is where the key is defined. usingApps names the out-of-scope directories that referenced it — an app's name where an app owns the directory, a layer's name otherwise.

What Is Removed

summary.usedCount excludes misplaced keys and summary.misplacedCount counts them separately, so a misplaced key never inflates your used total. The --fail-on-orphans gate reads orphanCount only, and so does the Code Quality report — to fail a pipeline on misplaced usages, read misplacedCount yourself.

Fixing One

Every entry is one of three situations, and only you know which.

The key is in the wrong layer. One call carries it there with every locale that defines it:

the-i18n-cli move --layer checkout --key checkout.cart.title --toLayer admin

Add --newKey in the same call if the namespace no longer fits its new home.

The usage is a bug. A copied component or a stale import. Fix the call site to use a key its own layers define and the finding disappears on the next run. the-i18n-cli check is the same defect seen from the call site.

The app should consume that layer. Then the fix is in the app's own configuration, and the graph picks it up on the next run.

When You Will Not See Any

Misplaced usages need at least one directory outside a layer's scope, which single-app projects and configurations with no app information do not have — see the consumer graph for where the edges come from. Passing explicit scan directories to the orphan tools also switches to one combined usage set and turns the detection off, so an empty misplacedUsages from such a run says nothing about the project.

A dynamic pattern in an out-of-scope app matches conservatively: t(`${prefix}.title`) in a non-consuming app can mark every .title key in another layer as misplaced. Keep a literal leading segment and the report stays specific. The finding names apps and layers, not files; for file paths and line numbers, run the-i18n-cli orphans --usages --keys <key>.