glot

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

📖 Full Documentation

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

npm install -D glotctl

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

// messages/en.json - key is missing!
{
  "common": {
    "cancel": "Cancel"
  }
}

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:

// messages/en.json (primary)
{
  "common": {
    "submit": "Submit"
  }
}

// messages/es.json (replica)
{
  "common": {
    "submit": "Enviar",
    "legacyText": "Texto antiguo" // Not in 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:

// messages/en.json (primary)
{
  "common": {
    "submit": "Submit"
  }
}

// messages/zh.json - same as English!
{
  "common": {
    "submit": "Submit"
  }
}

error: "common.submit"  [untranslated]
  --> ./messages/en.json:3:1
  = note: ("Submit") identical in: zh
  = used: ./src/components/Form.tsx:12:18

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 issues and prevent new ones:

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

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

1. Add glot to CI immediately
2. 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