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.
​
--rules
string[]
default:"all"
Rules to clean. Can be specified multiple times. If not specified, all rules are applied.Possible values:
  • unused - Keys defined in locale files but not used in code
  • orphan - Keys in non-primary locales but not in primary locale
​
--source-root
string
Override the source code root directory. Defaults to the value from configuration file.
​
--messages-root
string
Override the messages directory path. Defaults to the value from configuration file.
​
--primary-locale
string
Override the primary locale. Defaults to the value from configuration file.
​
-v, --verbose
boolean
default:"false"
Enable verbose output for debugging.

​
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 --rules unused --apply

​
Orphan Keys Only

Remove keys that exist in non-primary locales but not in the primary locale: 
npx glot clean --rules orphan --apply
When --rules is not specified, both unused and orphan keys 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 with Custom Source Root

npx glot clean --rules unused --apply --source-root ./src

Directives

Use glot-message-keys for dynamic keys

Orphan Keys

Understanding orphan key detection

Missing Keys

Understanding missing key detection