Skip to main content

​
General

No. Glot is designed specifically for next-intl. Translation key analysis (missing, unused, orphan, replica-lag, etc.) relies on next-intl’s useTranslations and getTranslations patterns.However, hardcoded text detection works regardless of your i18n library — it simply finds text in JSX/TSX that isn’t wrapped in a translation function.
No. Glot only parses JSX/TSX files and is built for Next.js projects. It uses swc (the same parser Next.js uses) to parse your source code.
No. Glot only supports JSON locale files (e.g., messages/en.json). This is the format used by next-intl.
Yes. Set sourceRoot and messagesRoot to point to the correct locations:
.glotrc.json
{
  "primaryLocale": "en",
  "messagesRoot": "./packages/i18n/messages",
  "includes": [
    "apps/web/src/app/[locale]",
    "apps/web/src/components",
    "packages/ui/src"
  ]
}
See Common Configurations for more examples.
Only two commands modify files, and both require explicit --apply flags:
  • glot baseline --apply — inserts // glot-disable-next-line comments
  • glot fix --apply — inserts /* glot-message-keys */ comments
  • glot clean --apply — removes unused keys from JSON locale files
Without --apply, these commands only show a preview (dry run). All other commands (check, init, serve) are read-only.
Glot is built in Rust and uses swc for parsing, making it very fast. Typical performance:
  • Small projects (~50 files): under 1 second
  • Medium projects (~500 files): 1–3 seconds
  • Large projects (~2000+ files): 3–10 seconds
Performance depends on the number of files scanned and locale file sizes. You can limit what’s scanned via the includes and ignores configuration options.
Glot works with any version of Next.js (App Router and Pages Router) and any version of next-intl, as long as your project follows the standard patterns:
  • useTranslations / getTranslations for obtaining translation functions
  • JSON-based locale files (e.g., messages/en.json)
Glot analyzes source code statically — it doesn’t import or execute your project, so there are no runtime version constraints.
Yes. Glot is distributed as a pre-compiled npm package with binaries for:
  • macOS (Apple Silicon and Intel)
  • Linux (x64 and ARM64)
  • Windows (x64)
If you install via npm install -D glotctl, the correct binary is selected automatically.

​
Detection Issues

Common reasons:
  1. File not in includes paths — glot only scans directories listed in your .glotrc.json includes config. Check that the file’s directory is included.
  2. File is a test file — by default, ignoreTestFiles is true, which skips *.test.*, *.spec.*, and __tests__/ files.
  3. Text has no alphabetic characters — glot only flags text containing at least one Unicode alphabetic character. Pure numbers (123) and symbols (---, $100) are ignored.
  4. Suppressed by directive — check if there’s a glot-disable-next-line or glot-disable comment above the text.
  5. Attribute not in checkedAttributes — only attributes listed in checkedAttributes are checked. Custom attributes like label or description are not checked by default.
  6. Text matches ignoreTexts pattern — check your .glotrc.json for ignored text patterns.
Run with -v (verbose) to see which files are being scanned:
npx glot check -v
Several options, from most to least specific:
  1. Single line: Add // glot-disable-next-line (or {/* glot-disable-next-line */} in JSX) above the line.
  2. Block: Wrap with // glot-disable and // glot-enable.
  3. Specific text patterns: Add to ignoreTexts in .glotrc.json: 
    { "ignoreTexts": ["TODO", "N/A", "Lorem ipsum"] }
  4. Entire file: Place // glot-disable on line 1 or 2.
  5. Entire directory: Add the path to ignores in .glotrc.json.
See Directives for details.
glot clean refuses to run when your code has unresolved dynamic keys — translation keys that use variables or template literals that glot can’t statically analyze:
// glot can't know which keys this uses
t(`status.${code}`)
This is a safety feature to prevent accidentally deleting keys that are used dynamically.Fix: Declare your dynamic keys with glot-message-keys annotations:
// glot-message-keys "status.active", "status.inactive", "status.pending"
t(`status.${code}`)
Or use the fix command to auto-insert them:
npx glot fix --apply
Then glot clean will run safely.See Unresolved Keys and glot fix for details.
Glot flags any text containing alphabetic characters. Brand names like “Google” or technical terms like “TypeScript” will be flagged.Suppress them per-line:
{/* glot-disable-next-line */}
<span>Acme Corporation</span>
Or globally via ignoreTexts:
{ "ignoreTexts": ["Acme Corporation", "TypeScript"] }

​
Configuration Issues

Glot validates that directories in includes exist. Common causes:
  1. Wrong relative path — paths in includes are relative to sourceRoot. If sourceRoot is "./src" and you have "includes": ["app"], glot looks for ./src/app.
  2. Dynamic route syntax — [locale] is treated as a literal folder name. Make sure the folder [locale] actually exists on disk.
  3. Missing directory — the directory may not exist in your project. Update includes to match your actual structure.
Place it in your project root (next to package.json). Glot searches upward from the current directory until it finds .glotrc.json or a .git directory.See Configuration Resolution for the full search algorithm.

​
CI / Integration Issues

CodeMeaning
0No errors (warnings may exist)
1Errors found
Errors (exit code 1): hardcoded text, missing keys, type mismatches.Warnings (exit code 0): orphan keys, untranslated values, unused keys, replica-lag, unresolved keys.This means glot check in CI will only fail the build on actual errors, not warnings.
Use the baseline workflow:
  1. Run npx glot baseline --apply to suppress all existing hardcoded text warnings
  2. Add glot check to CI — new issues will be caught immediately
  3. Gradually fix existing issues and remove suppression comments over time
See Baseline Command for details.

Configuration

Full configuration reference

Directives

Inline suppression directives

How Detection Works

Supported patterns and limitations