Skip to main content
Glot detects translation keys that are used in your code but missing from your locale files.

​
What Are Missing Keys?

A missing key occurs when:
  1. Your code calls a translation function with a key: t('common.submit')
  2. That key doesn’t exist in your locale JSON files
This typically happens when:
  • A developer adds a translation call but forgets to add the key to locale files
  • A key is misspelled in the code
  • Keys are deleted from locale files but still used in code

​
Example

Code using a translation: 
function Button() {
  const t = useTranslations("common");
  return <button>{t("submit")}</button>;
}
Locale file missing the key:
messages/en.json
{
  "common": {
    "cancel": "Cancel"
    // "submit" is missing!
  }
}
Glot output: 
error: common.submit  missing-key
  --> ./src/components/Button.tsx:3
  |
  | Translation key "common.submit" is used but not defined in messages/en.json
  |

✖ 1 problem (1 error, 0 warnings)

​
Detection Methods

Glot identifies translation usage through:

​
Direct Function Calls

t("key");
t("namespace.key");

​
Template Literals (Warning)

Dynamic keys can’t be statically analyzed: 
t(`items.${type}`); // Warning: dynamic key

​
Supported Translation Hooks

Glot recognizes these next-intl translation functions:
FunctionContextImport
useTranslationsClient componentsnext-intl
getTranslationsServer componentsnext-intl/server
// useTranslations hook (client)
const t = useTranslations("namespace");
t("key"); // Detected as namespace.key

// getTranslations (server)
import { getTranslations } from "next-intl/server";
const t = await getTranslations("namespace");
t("key"); // Detected as namespace.key
Custom translation functions or renamed imports are not automatically detected. If you use a wrapper function, consider using glot-message-keys to declare keys.

​
Severity

Missing keys are reported as errors because they cause runtime issues:
  • In development: Often shows the key itself or an error message
  • In production: Can break the user experience

​
Fixing Missing Keys

1

Run Check

npx glot check missing
2

Review Issues

Check each missing key report to understand what’s needed.
3

Add Keys

Add the missing keys to your locale files:
messages/en.json
{
  "common": {
    "submit": "Submit",
    "cancel": "Cancel"
  }
}
4

Verify

Run the check again to confirm all keys are present:
npx glot check missing

​
Dynamic Keys

When glot encounters dynamic keys, it issues a warning: 
// This generates a warning
const t = useTranslations("items");
return <span>{t(`${item.type}.label`)}</span>;

warning: Dynamic key detected  dynamic-key
  --> ./src/components/Item.tsx:5
  |
5 |   return <span>{t(`${item.type}.label`)}</span>;
  |
  | Cannot statically analyze dynamic translation keys

​
Handling Dynamic Keys

Options for handling dynamic keys:
  1. Refactor to static keys (recommended): 
    const labels = {
  book: t("book.label"),
  video: t("video.label"),
};
return <span>{labels[item.type]}</span>;
  2. Declare expected keys (when refactoring is not feasible): 
    // glot-message-keys "book.label", "video.label"
return <span>{t(`${item.type}.label`)}</span>;
    Or use a glob pattern to match multiple keys: 
    // glot-message-keys "*.label"
return <span>{t(`${item.type}.label`)}</span>;
  3. Suppress the warning (last resort): 
    // glot-disable-next-line
return <span>{t(`${item.type}.label`)}</span>;
Option 2 (glot-message-keys) is preferred over option 3 because it explicitly declares which keys are used, enabling accurate tracking for the clean command.

​
Primary vs Non-Primary Locales

Missing key detection checks against the primary locale defined in your config:
.glotrc.json
{
  "primaryLocale": "en"
}
If a key is missing from messages/en.json, it’s reported as a missing key. If a key exists in en.json but not in es.json, it’s reported as replica lag (a different check).

Directives

Use glot-message-keys for dynamic keys

Orphan Keys

Find unused translation keys

Check Command

Run missing key detection