How to find and delete unused translation keys

As your application evolves, new features get added and old views get removed. Translation keys that once served a purpose stick around in your files long after the code that referenced them is gone. Over time, these orphaned keys inflate file sizes, confuse translators, and make it harder to understand the real scope of your localization work.

This is a maintenance problem that affects almost every i18n system that lacks a structured cleanup workflow. SimpleLocalize gives you two complementary approaches to solve it: a last seen date filter for one-off cleanup, and an automated deprecation workflow that keeps keys in sync with your codebase on every import.

What causes unused translation keys to accumulate?

Before fixing the problem, it helps to understand where the clutter comes from:

• Replacing features without cleanup: New keys get added for new features, but old keys from removed views are never deleted.
• Renaming keys during refactors: A key gets renamed in code but the old identifier stays in the translation file.
• Dropping language support: A language gets removed from the product but its keys remain in the TMS.
• Duplicate keys across modules: Similar strings exist under different key names in different namespaces. Using namespaces to isolate keys by feature or team area helps prevent this, and also prevents accidental deprecation when only one part of the app is uploaded at a time.
• Outdated source content: The source string changes but related translation keys are not updated or removed. You can use review statuses to catch stale translations automatically.

Without a system to track which keys are actually in use, these accumulate silently.

Two ways to clean up unused keys

Option 1: Use the last seen date filter (manual cleanup)

Every time you upload translation files to SimpleLocalize, the platform records the last seen date for each key present in the upload. Keys that were not part of the most recent import keep their previous last seen date.

This makes it straightforward to identify stale keys: anything with a last seen date older than your most recent upload is likely no longer referenced in your codebase.

Upload translations to SimpleLocalize

Start by uploading your current translation files to SimpleLocalize, either through the web interface, the SimpleLocalize CLI, or the REST API.

Learn more about importing translation files to SimpleLocalize

Find keys by last seen date

Once uploaded, open the translation editor and use Filters to search for keys by their last seen date. Filter for keys last seen before your most recent upload, and you have a list of candidates for removal.

For example: if you uploaded your files today (April 30th), filter for keys with a Last seen date of April 29th or earlier. Anything older than that was not present in the latest upload and is a strong candidate for removal.

You can also display the last seen date directly in the translation editor or sort translation keys to visually identify stale keys.

Delete the unused keys

Hold Ctrl or ⌘ and click any key to open Bulk Actions. Select all filtered keys or pick specific ones, then use Delete keys to remove them. Your next export will contain only the keys that are still actively used.

This approach works well for periodic cleanups, but it requires manual review each time. For teams that want the process to happen automatically as part of their normal workflow, the deprecation workflow is a better fit.

Option 2: Use the deprecation workflow (automated, recommended)

SimpleLocalize now supports a dedicated deprecation workflow built from three import and export options that work together. Instead of deleting keys immediately, this approach marks orphaned keys as deprecated during import, keeps them available for review, and excludes them from exports automatically. When a deprecated key reappears in a future upload (for example, if a feature is brought back), it is reactivated automatically.

Deprecation is not deletion. Deprecated keys stay in your project until you manually remove them. They are simply flagged and excluded from exports if you choose so. Your translations are safe, reviewable, and fully recoverable at any point. No automated process deletes anything.

The three options are:

All three options are available via the web UI, the CLI, and the REST API.

How the workflow fits together

Here is what happens during a typical development cycle:

1. A developer removes a feature. The translation key for that feature no longer appears in the source code or translation file.
2. On the next CI/CD run, translations are uploaded with DEPRECATE_NOT_PRESENT_KEYS enabled. The missing key is automatically marked as deprecated in SimpleLocalize.
3. When translations are downloaded or exported (for example, to be bundled with the app), EXCLUDE_DEPRECATED_KEYS option ensures the deprecated key is not included.
4. If the feature is later re-introduced and the key reappears in the upload, ACTIVATE_PRESENT_KEYS option removes the deprecated flag automatically.

The result: your exported translation files stay clean and in sync with your codebase, with no manual intervention required.

Set up the deprecation workflow

In the web UI

When uploading a file through the interface, look for the import options section. Enable Deprecate not present keys and Activate present keys as needed. For exports, enable Exclude deprecated keys in the download options.

In the CLI

Add the options to your simplelocalize.yml configuration file:

uploadOptions:
  - DEPRECATE_NOT_PRESENT_KEYS
  - ACTIVATE_PRESENT_KEYS
 
downloadOptions:
  - EXCLUDE_DEPRECATED_KEYS

Then run your standard upload and download commands:

simplelocalize upload
simplelocalize download

Note: Make sure you are running the latest version of the SimpleLocalize CLI to access the deprecation options. Update with npm install -g simplelocalize-cli or check the CLI changelog for the version that introduced these flags.

You can instantly delete not present keys by adding the DELETE_NOT_PRESENT_KEYS option to your upload, but we recommend using deprecation first to review the keys before permanent removal.

Via the REST API

Pass the options as part of your import or export request body:

// Import request
{
  "importOptions": ["DEPRECATE_NOT_PRESENT_KEYS", "ACTIVATE_PRESENT_KEYS"]
}
 
// Export request
{
  "exportOptions": ["EXCLUDE_DEPRECATED_KEYS"]
}

Working with deprecated keys in the editor

Deprecated keys remain visible in the SimpleLocalize translation editor so your team can review them before permanent removal. You can filter by deprecated status to see all flagged keys at a glance, inspect their last content, and delete them in bulk when you are ready.

This gives you an audit trail: keys are not silently removed the moment they disappear from a file. You have a chance to confirm the removal is intentional before it becomes permanent.

Which approach should you use?

Here is a quick guide to help you choose between the last seen date filter and the deprecation workflow based on your needs:

For most teams with a CI/CD pipeline already in place, the deprecation workflow is the better long-term choice. It adds almost no overhead to your existing upload and download steps, and it means you never have to think about key cleanup as a separate task.

Integrating cleanup into your CI/CD pipeline

Whether you use the deprecation workflow or rely on the last seen date filter, the best results come from integrating SimpleLocalize into your regular deployment process rather than treating cleanup as an occasional manual task.

Tools like Translation Hosting make it possible to deliver fresh translations via CDN without needing to rebuild and redeploy your application. Combined with the GitHub Actions integration, you can set up a pipeline where keys are uploaded on every push, deprecated keys are flagged automatically, and approved translations are pulled and published without any manual steps.

Related: Continuous localization: What it is, why it matters, and how to implement it

Keeping your translation files clean is not a one-off task. With the right workflow in place, it happens automatically with every release, so your translators always work with accurate, up-to-date content, and your exported files never carry the weight of code you deleted six months ago.

Ready to declutter? Open your SimpleLocalize project, run a Last Seen filter, and see how many orphaned keys are already waiting to be cleared. If the number surprises you, that is a good sign it is time to set up the deprecation workflow and let it run automatically from here on.