Skip to main content
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

bash npx 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: 
# Preview what would be deleted
npx glot clean

# Actually delete orphan keys
npx glot clean --apply

​
Clean Only Specific Types

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

# Only replica orphans (only in non-primary locales)
npx 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.

Clean Command

Remove orphan keys

Missing Keys

Find missing translation keys