Skip to main content
The clean command removes unused or orphan translation keys from your locale JSON files.

​
Usage

npx glot clean [OPTIONS]

​
Options

​
--apply
boolean
default:"false"
Actually delete keys. Without this flag, glot runs in dry-run mode and only shows what would be deleted.
​
--unused
boolean
default:"false"
Only clean unused keys (defined in locale files but not used in code).
​
--orphan
boolean
default:"false"
Only clean orphan keys (exist in non-primary locales but not in primary locale).
​
--path
string
default:"."
Directory to check.

​
Dry-Run Mode (Default)

By default, glot runs in dry-run mode to preview changes: 
npx glot clean
Output: 
Dry-run mode: showing keys that would be deleted

Would delete from messages/en.json:
  - common.oldButton
  - settings.deprecated

Would delete from messages/es.json:
  - common.oldButton
  - settings.deprecated
  - extra.orphanKey (orphan - not in primary locale)

4 keys would be deleted. Run with --apply to delete.

​
Apply Changes

To actually delete the keys: 
npx glot clean --apply
Output: 
Deleted from messages/en.json:
  - common.oldButton
  - settings.deprecated

Deleted from messages/es.json:
  - common.oldButton
  - settings.deprecated
  - extra.orphanKey

✓ 4 keys deleted

​
Clean Specific Key Types

​
Unused Keys Only

Remove keys that exist in locale files but are never used in code: 
npx glot clean --unused --apply

​
Orphan Keys Only

Remove keys that exist in non-primary locales but not in the primary locale: 
npx glot clean --orphan --apply
When neither --unused nor --orphan is specified, both types are cleaned.

​
Safety Checks

Glot includes safety mechanisms to prevent accidental data loss:
Glot will refuse to clean if:
  • Dynamic keys are detected - Template literals with expressions like t(`key.${id}`) can’t be statically analyzed
  • Parse errors exist - Some files couldn’t be parsed correctly
If you see this message: 
Cannot clean: dynamic keys detected in codebase
These keys use runtime values and cannot be statically analyzed:
  - src/components/Dynamic.tsx:15 - t(`items.${item.type}`)

Fix or suppress these before cleaning.
You’ll need to either:
  1. Replace dynamic keys with static alternatives
  2. Use // glot-message-keys "pattern.*" to declare which keys are used dynamically
Do NOT use glot-disable-next-line for dynamic keys when using clean. While it suppresses the warning, it doesn’t tell glot which keys are actually used. This means clean may incorrectly delete keys that are dynamically referenced.

​
Handling Dynamic Keys

// Before: Dynamic key causes clean to fail
{
  items.map((item) => t(`items.${item.type}`));
}

// After: Declare expected keys with explicit list
// glot-message-keys "items.basic", "items.premium", "items.enterprise"
{
  items.map((item) => t(`items.${item.type}`));
}

// Or with glob pattern to match all keys under items.*
// glot-message-keys "items.*"
{
  items.map((item) => t(`items.${item.type}`));
}

​
Examples

​
Preview All Cleanable Keys

npx glot clean

​
Clean Everything

npx glot clean --apply

​
Clean Only Unused Keys in Specific Directory

npx glot clean --unused --apply --path ./src

Directives

Use glot-message-keys for dynamic keys

Orphan Keys

Understanding orphan key detection

Missing Keys

Understanding missing key detection