Missing Keys

Understanding missing translation key detection

Severity: Error — causes exit code 1 and fails CI builds.

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:

Function	Context	Import
useTranslations	Client components	next-intl
getTranslations	Server components	next-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

   npm

   npx glot check missing
   

   pnpm

   pnpm exec glot check missing
   

   yarn

   yarn glot check missing
   

   bun

   bunx 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:

   npm

   npx glot check missing
   

   pnpm

   pnpm exec glot check missing
   

   yarn

   yarn glot check missing
   

   bun

   bunx 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>;
   
   Use glot fix to automatically insert these comments:

   npx glot fix --apply
   

   See glot fix for details.

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).

Related

Directives

Use glot-message-keys for dynamic keys

Orphan Keys

Find unused translation keys

Check Command

Run missing key detection