FAQ & Troubleshooting

Frequently asked questions and common issues

General

Does glot work with i18next / react-intl / other i18n libraries?

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.

Does glot work with Vue, Angular, or Svelte?

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.

Does glot support YAML, PO, or XLIFF translation files?

No. Glot only supports JSON locale files (e.g., messages/en.json). This is the format used by next-intl.

Can I use glot in a monorepo?

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.

Does glot modify my source code?

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.

How fast is glot?

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.

What versions of Next.js and next-intl are supported?

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.

Does glot work on Windows, macOS, and Linux?

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

Why is some text not being detected?

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

I'm getting false positives — how do I suppress them?

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.

Why does "glot clean" refuse to run?

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.

Why are brand names / technical terms flagged?

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 says "Directory does not exist" for my includes path

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.

Where should I place .glotrc.json?

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

What exit codes does glot use?

Code	Meaning
0	No errors (warnings may exist)
1	Errors 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.

How do I adopt glot in a project with many existing issues?

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.

Related

Configuration

Full configuration reference

Directives

Inline suppression directives

How Detection Works

Supported patterns and limitations