Orphan Keys

Understanding orphan and unused translation key detection

Severity: Warning — does not affect exit code or fail CI builds.

Glot detects translation keys that are defined in your locale files but never used in your code.

Types of Orphan Keys

Unused Keys

Keys that exist in locale files but are never referenced in code:

messages/en.json

{
  "common": {
    "submit": "Submit", // Used in code
    "oldButton": "Old Text" // Never used - orphan
  }
}

Replica Orphans

Keys that exist in non-primary locales but not in the primary locale. This typically happens when:

• A key was deleted from the primary locale but not from other locales
• A key was accidentally added to a non-primary locale

The term “replica lag” refers to the synchronization gap between your primary and secondary locales:

messages/en.json (primary)

{
  "common": {
    "submit": "Submit"
  }
}

messages/es.json

{
  "common": {
    "submit": "Enviar",
    "legacy": "Legacy" // Orphan - not in primary locale
  }
}

Why This Matters

Orphan keys:

• Increase translation file size unnecessarily
• Cause confusion for translators
• May indicate incomplete code cleanup
• Add maintenance burden

Severity

Orphan keys are reported as warnings (not errors) because:

• They don’t break functionality
• They may be intentionally kept for future use
• Removal is optional

Running Orphan Detection

npmbash npx glot check orphan

pnpmbash pnpm exec glot check orphan

yarnbash yarn glot check orphan

bunbash bunx glot check orphan

Output:

warning: common.oldButton  orphan-key
  --> ./messages/en.json
  |
  | Key exists in locale file but is not used in code
  |

warning: common.legacy  orphan-key
  --> ./messages/es.json
  |
  | Key exists in non-primary locale but not in primary locale (en)
  |

✘ 0 errors, 2 warnings

Cleaning Up Orphan Keys

Use the clean command to remove orphan keys:

npm

# Preview what would be deleted
npx glot clean

# Actually delete orphan keys
npx glot clean --apply

pnpm

# Preview what would be deleted
pnpm exec glot clean

# Actually delete orphan keys
pnpm exec glot clean --apply

yarn

# Preview what would be deleted
yarn glot clean

# Actually delete orphan keys
yarn glot clean --apply

bun

# Preview what would be deleted
bunx glot clean

# Actually delete orphan keys
bunx glot clean --apply

Clean Only Specific Types

npm

# Only unused keys (in all locales)
npx glot clean --unused --apply

# Only replica orphans (only in non-primary locales)
npx glot clean --orphan --apply

pnpm

# Only unused keys (in all locales)
pnpm exec glot clean --unused --apply

# Only replica orphans (only in non-primary locales)
pnpm exec glot clean --orphan --apply

yarn

# Only unused keys (in all locales)
yarn glot clean --unused --apply

# Only replica orphans (only in non-primary locales)
yarn glot clean --orphan --apply

bun

# Only unused keys (in all locales)
bunx glot clean --unused --apply

# Only replica orphans (only in non-primary locales)
bunx glot clean --orphan --apply

Common Causes

Removed Features

A feature was removed but translations weren’t cleaned up:

// Deleted component
// function OldFeature() {
//   return <div>{t('oldFeature.title')}</div>;
// }

{
  "oldFeature": {
    "title": "Old Feature" // Now orphaned
  }
}

Refactored Keys

Keys were renamed but old ones weren’t removed:

// Before
t("btn.submit");

// After
t("button.submit");

{
  "btn": {
    "submit": "Submit" // Orphaned
  },
  "button": {
    "submit": "Submit" // Active
  }
}

Copy-Paste Locales

Locale files copied from another project with unused keys.

Keeping Keys Intentionally

If you want to keep certain keys without using them (e.g., for future features), you can:

1. Add a comment (though glot will still report them)
2. Reference them in a special file that glot ignores
3. Accept the warnings as informational

Dynamic Keys Warning

If your code uses dynamic translation keys, glot cannot determine if a key is truly unused:

// glot can't track this usage
t(`items.${item.type}`);

In this case, clean will refuse to run to prevent accidental deletion.

Related

Clean Command

Remove orphan keys

Missing Keys

Find missing translation keys