GitHub - Sukitly/glotctl: A fast CLI tool for checking internationalization (i18n) issues in Next.js projects using next-intl.

glot

A fast CLI for checking internationalization (i18n) issues in Next.js projects using next-intl.

Features

🔍 Hardcoded Text Detection - Find untranslated text in JSX/TSX
🌐 Untranslated Detection - Detect values identical to primary locale
🔑 Missing Key Detection - Identify keys used in code but missing from locale files
🧹 Orphan Key Detection - Find keys in replica locales not in primary locale
🤖 AI Integration - MCP server for AI coding agents

Installation

The npm package is glotctl, but the CLI command is glot.

Quick Start

# Initialize configuration
npx glot init

# Check for all i18n issues
npx glot check

What Glot Detects

Hardcoded Text

Untranslated strings in JSX that should use translation functions:

// ❌ Detected by glot
<button>Submit</button>
<input placeholder="Enter email" />

// ✅ Using next-intl
<button>{t("submit")}</button>
<input placeholder={t("emailPlaceholder")} />

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

Missing Keys

Translation keys used in code but not defined in locale files:

// Code uses this key
const t = useTranslations("common");
return <button>{t("submit")}</button>;

error: "common.submit"  [missing-key]
  --> ./src/components/Button.tsx:3
  |
  | Translation key "common.submit" is used but not defined

Orphan Keys

Keys in replica locales that don't exist in the primary locale:

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

Untranslated Values

Values in non-primary locales that are identical to the primary locale, possibly not translated:

warning: "common.submit"  [untranslated]
  --> ./messages/zh.json:3:0
  = note: "Submit"
  = hint: Value is identical to primary locale (en), possibly not translated

Clean up orphan keys:

npx glot clean         # Preview
npx glot clean --apply # Apply

Existing Projects

For projects with many existing hardcoded strings, use baseline to suppress current warnings and prevent new ones:

npx glot baseline         # Preview
npx glot baseline --apply # Apply

This inserts // glot-disable-next-line comments, allowing you to:

Add glot to CI immediately
Gradually fix existing issues over time

AI Integration (MCP)

Glot provides an MCP server for AI coding agents.

OpenCode

Add to opencode.json:

{
  "mcp": {
    "glot": {
      "type": "local",
      "command": ["npx", "glot", "serve"],
      "enabled": true
    }
  }
}

Claude Code

claude mcp add --transport stdio glot -- npx glot serve

Or create .mcp.json in your project root:

{
  "mcpServers": {
    "glot": {
      "command": "npx",
      "args": ["glot", "serve"]
    }
  }
}

Cursor

Create .cursor/mcp.json:

{
  "mcpServers": {
    "glot": {
      "command": "npx",
      "args": ["glot", "serve"]
    }
  }
}

See MCP Server Documentation for available tools and workflow.

License

MIT