glot check

Run i18n checks on your codebase

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

Astro support currently covers translation key usage in supported .astro files (static keys, unresolved dynamic keys, and glot-message-keys declarations). The hardcoded rule does not run on .astro files yet.

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 (Astro not supported yet)
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 default severity level. Errors cause a non-zero exit code (exit 1). Warnings normally do not, unless you pass --error-on-warnings.

Type	Default Severity	Default Exit Code
hardcoded	Error	1
missing	Error	1
replica-lag	Error	1
untranslated	Error when used; Warning when no usage is found	1 for used issues; 0 for no-usage warnings
type-mismatch	Error	1
orphan	Warning	0
unused	Warning	0
unresolved	Warning	0

Use --error-on-warnings in CI if your project wants any remaining warning to fail the build. Use severities in .glotrc.json when you want to change a rule’s effective severity for the whole project.

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.

--error-on-warnings · boolean · default: "false"

Return exit code 1 when any warning is found. This does not rename warnings to errors in the output.

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, replica lag, used untranslated values, type mismatches
Warning	0 by default, 1 with --error-on-warnings	Orphan keys, unused keys, unresolved keys, no-usage untranslated values, or rules downgraded via config

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	Error when used; Warning when no usage is found	Value identical to primary locale	Untranslated
unused-key	Warning	Key in primary locale but never used in code	Unused Keys
replica-lag	Error	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.

Untranslated values → Translate the non-primary locale value. If the value is intentionally identical and used in source, suppress it with glot-disable-next-line untranslated. See Untranslated.

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, or warnings found with --error-on-warnings
2	Parse/config/runtime error

This makes glot suitable for CI/CD pipelines where you want to fail builds on errors or enforce stricter warning policies.

Verbose Output

With -v flag, glot shows additional information:

Scanning directory: ./src
Found 42 source 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