---
slug: "glotctl"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/sukitly/glotctl@main/README.md"
repo: "https://github.com/sukitly/glotctl"
source_file: "README.md"
branch: "main"
---
# glot

A fast CLI for checking internationalization (i18n) issues in Next.js projects using [next-intl](https://next-intl.dev/).

📖 **[Full Documentation](https://glotctl.mintlify.app/)**

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

```bash
npm install -D glotctl
```

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

## Quick Start

```bash
# 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:

```tsx
// ❌ 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:

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

```jsonc
// 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:

```jsonc
// 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:

```jsonc
// 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:

```bash
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:

```bash
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](https://modelcontextprotocol.io/) for AI coding agents.

### OpenCode

Add to `opencode.json`:

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

### Claude Code

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

Or create `.mcp.json` in your project root:

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

### Cursor

Create `.cursor/mcp.json`:

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

See [MCP Server Documentation](https://glotctl.mintlify.app/agents/mcp) for available tools and workflow.

## License

MIT