glot check

Run i18n checks on your codebase

The check command is the core of glot. It scans your codebase for internationalization issues.

Usage

npm

npx glot check [CHECK_TYPES...] [OPTIONS]

Check Types

You can run specific checks or all checks at once:

Type	Description
hardcoded	Find untranslated text in JSX/TSX files
missing	Identify translation keys used in code but missing from locale files
orphan	Find unused translation keys defined in locale files

npm

# Run all checks (default)
npx glot check

# Run specific checks

npx glot check hardcoded
npx glot check missing
npx glot check orphan

# Run multiple specific checks

npx glot check hardcoded missing

Options

--path · string · default: "."

Directory to check. Defaults to current directory.

-v, --verbose · boolean · default: "false"

Enable verbose output for debugging.

Examples

Basic Check

Check the current directory for all i18n issues:

npm

npx glot check

Check Specific Directory

Check only the src directory:

npm

npx glot check --path ./src

Verbose Mode

Get detailed output including scanned files:

npm

npx glot check -v

Check Specific Issue Types

Run only hardcoded text detection:

npm

npx glot check hardcoded

Run hardcoded and missing key checks:

npm

npx glot check hardcoded missing

Output Format

Glot displays issues in a compiler-like format:

error: "Submit"  hardcoded-text
  --> ./src/components/Button.tsx:5:22
  |
5 |     return <button>Submit</button>;
  |                    ^

warning: common.oldKey  orphan-key
  --> ./messages/en.json
  |
  | Key exists in locale file but is not used in code
  |

✖ 2 problems (1 error, 1 warning)

Issue Severity

Severity	Exit Code	Description
Error	1	Hardcoded text, missing keys
Warning	0	Orphan keys (unused translations)

Understanding Issues

This section explains each issue type with examples and solutions.

Hardcoded Text (hardcoded-text)

Hardcoded text is user-facing content that should be translated but isn’t using a translation function.

Example: JSX text content

Problem code:

function Button() {
  return <button>Submit</button>;
}

Glot output:

error: "Submit"  hardcoded-text
  --> ./src/components/Button.tsx:2:18
  |
2 |   return <button>Submit</button>;
  |                  ^

Solution:

import { useTranslations } from 'next-intl';

function Button() {
  const t = useTranslations('common');
  return <button>{t('submit')}</button>;
}

Then add the key to your locale file:

messages/en.json

{
  "common": {
    "submit": "Submit"
  }
}

Example: Input placeholder

Problem code:

<input placeholder="Enter your email" />

Glot output:

error: "Enter your email"  hardcoded-text
  --> ./src/components/Form.tsx:5:8
  |
5 |   <input placeholder="Enter your email" />
  |          ^

Solution:

<input placeholder={t('emailPlaceholder')} />

Example: Ternary expressions

Problem code:

{isLoading ? "Loading..." : "Ready"}

Glot output:

error: "Loading..."  hardcoded-text
  --> ./src/components/Status.tsx:3:15
  |
3 |   {isLoading ? "Loading..." : "Ready"}
  |               ^

error: "Ready"  hardcoded-text
  --> ./src/components/Status.tsx:3:31
  |
3 |   {isLoading ? "Loading..." : "Ready"}
  |                               ^

Solution:

{isLoading ? t('loading') : t('ready')}

How to fix hardcoded text

Option 1: Use translation functions (Recommended)

Replace hardcoded text with t() calls:

// Before
<button>Submit</button>

// After
<button>{t('submit')}</button>

Option 2: Ignore specific text patterns

Add patterns to ignoreTexts in .glotrc.json:

{
  "ignoreTexts": ["TODO", "FIXME", "N/A", "Lorem ipsum"]
}

Option 3: Suppress with directive

Use glot-disable-next-line for specific cases:

{/* glot-disable-next-line */}
<code>console.log("debug")</code>

Option 4: Customize checked attributes

Only check specific attributes in .glotrc.json:

{
  "checkedAttributes": ["placeholder", "alt", "aria-label"]
}

For more details on detection rules and patterns, see Hardcoded Text Detection.

Missing Keys (missing-key)

Missing keys occur when your code references a translation key that doesn’t exist in your locale files.

Example: Using undefined key

Problem code:

function WelcomeBanner() {
  const t = useTranslations('home');
  return <h1>{t('welcomeMessage')}</h1>;
}

Locale file (missing the key):

messages/en.json

{
  "home": {
    "title": "Home"
    // "welcomeMessage" is missing!
  }
}

Glot output:

error: home.welcomeMessage  missing-key
  --> ./src/components/WelcomeBanner.tsx:3
  |
  | Translation key "home.welcomeMessage" is used but not defined in messages/en.json
  |

Solution:

Add the missing key to your locale file:

messages/en.json

{
  "home": {
    "title": "Home",
    "welcomeMessage": "Welcome to our site!"
  }
}

Example: Typo in key name

Problem code:

// Typo: "cancle" instead of "cancel"
<button>{t('cancle')}</button>

Glot output:

error: common.cancle  missing-key
  --> ./src/components/Form.tsx:8
  |
  | Translation key "common.cancle" is used but not defined in messages/en.json
  |

Solution:

Fix the typo in your code:

<button>{t('cancel')}</button>

How to fix missing keys

Option 1: Add the key to locale files (Most common)

messages/en.json

{
  "namespace": {
    "yourKey": "Your translation"
  }
}

Option 2: Fix typos in code

Check for misspelled keys and correct them.

Option 3: Handle dynamic keys

For dynamic keys that can’t be statically analyzed, declare them explicitly:

// glot-message-keys "items.book", "items.video", "items.audio"
return <span>{t(`items.${item.type}`)}</span>;

Or use glob patterns:

// glot-message-keys "items.*"
return <span>{t(`items.${item.type}`)}</span>;

For more details on dynamic keys and namespace handling, see Missing Keys Detection.

Orphan Keys (orphan-key)

Orphan keys are translations defined in your locale files but never used in your code.

Example: Unused translation

Locale file with unused key:

messages/en.json

{
  "common": {
    "submit": "Submit",
    "oldButtonText": "Click Me"  // Never used in code
  }
}

Glot output:

warning: common.oldButtonText  orphan-key
  --> ./messages/en.json
  |
  | Key exists in locale file but is not used in code
  |

Example: Replica orphan (sync issue)

Primary locale (en.json):

messages/en.json

{
  "common": {
    "submit": "Submit"
  }
}

Non-primary locale with extra key:

messages/es.json

{
  "common": {
    "submit": "Enviar",
    "legacyText": "Texto antiguo"  // Not in primary locale
  }
}

Glot output:

warning: common.legacyText  orphan-key
  --> ./messages/es.json
  |
  | Key exists in non-primary locale but not in primary locale (en)
  |

How to fix orphan keys

Option 1: Remove with glot clean (Recommended)

Preview orphan keys:

npx glot clean

Remove them:

npx glot clean --apply

Option 2: Keep intentionally

If you’re keeping keys for future use, you can:

• Accept the warnings (they don’t fail builds)
• The orphan check is just informational

Option 3: Reference the key somewhere

If the key should be used, add it to your code:

<button>{t('oldButtonText')}</button>

If your code uses dynamic translation keys, glot cannot determine if a key is truly unused. In this case, clean will refuse to run to prevent accidental deletion. Use glot-message-keys to declare dynamic keys explicitly.

For more details on orphan key types and cleanup, see Orphan Keys Detection.

Exit Codes

Code	Meaning
0	No errors found (warnings may exist)
1	Errors found

This makes glot suitable for CI/CD pipelines where you want to fail builds on errors.

Verbose Output

With -v flag, glot shows additional information:

Scanning directory: ./src
Found 42 TSX/JSX files
Checking file: ./src/components/Button.tsx
Checking file: ./src/components/Form.tsx
...

error: "Submit"  hardcoded-text
  --> ./src/components/Button.tsx:5:22

Related

Hardcoded Text

Detect untranslated text in JSX/TSX

Missing Keys

Find keys used but not defined

Orphan Keys

Find unused translation keys

Directives

Suppress specific warnings