glot clean

Remove unused translation keys from locale files

The clean command removes unused or orphan translation keys from your locale JSON files.

Usage

npm

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:

npm

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:

npm

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:

npm

npx glot clean --rules unused --apply

Orphan Keys Only

Remove keys that exist in non-primary locales but not in the primary locale:

npm

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

npm

npx glot clean

Clean Everything

npm

npx glot clean --apply

Clean Only Unused Keys with Custom Source Root

npm

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

Related

Directives

Use glot-message-keys for dynamic keys

Orphan Keys

Understanding orphan key detection

Missing Keys

Understanding missing key detection