glotctl

glotctl is an efficient command-line interface (CLI) tool designed to help developers with internationalization (i18n) issues in Next.js projects utilizing next-intl. This tool simplifies the i18n process by providing crucial functionalities aimed at enhancing the localization of web applications.

Key Features

• Hardcoded Text Detection: Quickly identify untranslated text in JSX or TSX files that should utilize translation functions, ensuring that all strings are appropriately prepared for localization.
• Missing Key Detection: Detect keys referenced in your code that are absent in locale files, allowing for proactive resolution of potential issues in translations.
• Orphan Key Detection: Find unused keys within locale files, which helps maintain clean and manageable translation datasets.
• AI Integration: Utilize the MCP server for AI coding agents to streamline the process further.

Usage Examples

To initialize the configuration for your project, execute:

npx glot init

To conduct a comprehensive check for all i18n issues, run:

npx glot check

What glotctl Detects

Hardcoded Text

An example of hardcoded text that should be replaced with translation references:

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

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

The detection output example:

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

Missing Keys

Example code using a key that is not defined in locale files:

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

Expected output for a missing key:

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

An example of an orphan key that exists in locale files but is not utilized in the code:

// messages/en.json
{
  "common": {
    "submit": "Submit",
    "oldButton": "Old Text" // Never used
  }
}

Output for orphan keys:

warning: common.oldButton  orphan-key
  --> ./messages/en.json
  |
  | Key exists in locale file but is not used in code

To clean up orphan keys, use:

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

Managing Existing Projects

For projects with numerous hardcoded strings, the baseline command can help to suppress current warnings while enabling new checks:

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

This approach allows for immediate integration of glotctl into CI processes while giving teams time to address existing issues gradually.

AI Integration

glotctl also supports MCP for integration with AI coding agents. Configuration examples include:

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

For comprehensive details and configurations, visit the Full Documentation.