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 keys in non-primary locales not present in primary locale
untranslated	Find values identical to primary locale that may need translation
unused	Find keys in primary locale that are not used in code
replica-lag	Find keys in primary locale missing from other locales
type-mismatch	Find type conflicts between primary and replica locales (string vs array)
unresolved	Find keys that cannot be statically resolved (variables, template literals)

Severity

Each check type has a fixed severity level. Errors cause a non-zero exit code (exit 1); warnings do not.

Type	Severity	Exit Code
hardcoded	Error	1
missing	Error	1
type-mismatch	Error	1
orphan	Warning	0
untranslated	Warning	0
unused	Warning	0
replica-lag	Warning	0
unresolved	Warning	0

In CI pipelines, only errors will fail the build. Warnings are informational and won’t block your workflow.

npm

# Run all checks (default)
npx glot check

# Run specific checks
npx glot check hardcoded
npx glot check missing
npx glot check orphan
npx glot check untranslated
npx glot check unused
npx glot check replica-lag
npx glot check type-mismatch
npx glot check unresolved

# Run multiple specific checks
npx glot check hardcoded missing

Options

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

Examples

Basic Check

Check the current directory for all i18n issues:

npm

npx glot check

Override Source Root

Check a specific source directory:

npm

npx glot check --source-root ./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, type mismatches
Warning	0	Orphan keys, untranslated values, unused keys, replica-lag, unresolved keys

Understanding Issues

Each issue type is documented in detail on its own page. Here’s a quick summary:

Issue Type	Severity	Description	Details
hardcoded-text	Error	User-facing text not wrapped in t()	Hardcoded Text
missing-key	Error	Key used in code but not defined in locale files	Missing Keys
type-mismatch	Error	Value type differs between locales (causes runtime crashes)	Type Mismatch
orphan-key	Warning	Key in non-primary locale but not in primary	Orphan Keys
untranslated	Warning	Value identical to primary locale	Untranslated
unused-key	Warning	Key in primary locale but never used in code	Unused Keys
replica-lag	Warning	Key in primary locale missing from other locales	Replica Lag
unresolved-key	Warning	Dynamic key that can’t be statically analyzed	Unresolved Keys

Quick Fix Guide

Hardcoded text → Replace with t() call, or suppress with glot-disable-next-line. See Hardcoded Text.

Missing keys → Add the key to your locale file, or fix typos. See Missing Keys.

Type mismatches → Ensure all locales use the same type (string/array/object). See Type Mismatch.

Orphan keys → Add to primary locale or remove with glot clean --apply. See Orphan Keys.

Unused keys → Remove with glot clean --apply. See Unused Keys.

Replica lag → Add missing translations to non-primary locales. See Replica Lag.

Unresolved keys → Add glot-message-keys annotations or run glot fix --apply. See Unresolved Keys.

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

CI Examples

Glot works well in CI pipelines. Here are GitHub Actions examples:

npm .github/workflows/i18n.yml

name: i18n Check
on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npx glot check

Related

Hardcoded Text

Detect untranslated text in JSX/TSX

Missing Keys

Find keys used but not defined

Orphan Keys

Find unused translation keys in non-primary locales

Untranslated Values

Find values that may need translation

Unused Keys

Find keys in primary locale not used in code

Replica Lag

Find keys missing from replica locales

Type Mismatch

Find type conflicts between locales

Unresolved Keys

Find keys that cannot be statically resolved

Directives

Suppress specific warnings