sukitly/glot-i18n

Glot i18n Skill

This skill guides you through detecting and fixing internationalization (i18n) issues in Next.js projects using next-intl.

Prerequisites

• glot MCP server must be configured and available
• Project should have a .glotrc.json configuration file (run glot init if missing)
• Project uses next-intl for translations

When to Use This Skill

Activate this skill when:

• User asks to fix i18n, internationalization, or translation issues
• User mentions hardcoded text that should be translated
• User wants to find missing translation keys
• User needs to sync translations across multiple locales
• User mentions "glot" or asks to use glot tools

Core Workflow

IMPORTANT: Follow this order to minimize rework!

1. scan_overview     → Understand the overall state
2. Fix hardcoded    → Replace text with t() calls, add keys to primary locale
3. Fix primary_missing → Add missing keys to primary locale
4. Fix replica_lag   → Sync keys to other locales
5. Fix untranslated  → Translate values that are identical to primary locale

Why this order matters:

• Fixing hardcoded issues may create new primary_missing issues
• Fixing primary_missing may create new replica_lag issues
• Replica_lag fixes may create new untranslated issues (if text is copied without translation)
• Following this order prevents duplicate work

Available Tools

| Tool | Purpose | When to Use | | ---------------------- | ------------------------------------- | ------------------------------------- | | get_config | Get project configuration | First, to understand project setup | | get_locales | List available locale files | To see which languages are configured | | scan_overview | Get statistics of all issues | Always start here to understand scope | | scan_hardcoded | List hardcoded text issues | When fixing hardcoded text | | scan_primary_missing | List keys missing from primary locale | After fixing hardcoded issues | | scan_replica_lag | List keys missing from other locales | After fixing primary_missing | | scan_untranslated | List values identical to primary locale | After fixing replica_lag (or anytime) | | add_translations | Add keys to locale files | When adding new translation keys |

Step-by-Step: Fixing Hardcoded Text

1. Get Overview First

Call: scan_overview
Parameters: { "project_root_path": "<project_path>" }

Check the hardcoded.total_count to understand scope.

2. Get Detailed Hardcoded Issues

Call: scan_hardcoded
Parameters: { "project_root_path": "<project_path>", "limit": 20 }

Each item contains:

• file_path: The TSX/JSX file
• line, col: Location
• text: The hardcoded text found
• source_line: The actual source code line

3. For Each Issue, Determine the Key Name

Follow key naming conventions:

• Use camelCase for keys
• Organize by component or page namespace
• Be descriptive but concise

Examples: | Text | Suggested Key | |------|---------------| | "Submit" | common.submit or buttons.submit | | "Welcome to our app" | homePage.hero.welcomeMessage | | "Enter your email" | auth.emailPlaceholder | | "Loading..." | common.loading |

4. Modify the Source Code

Replace hardcoded text with t() calls:

Before:

<button>Submit</button>
<input placeholder="Enter email" />
<p>Welcome to our app</p>

After:

<button>{t("common.submit")}</button>
<input placeholder={t("auth.emailPlaceholder")} />
<p>{t("homePage.hero.welcomeMessage")}</p>

Ensure the component has useTranslations hook:

import { useTranslations } from "next-intl";

export function MyComponent() {
  const t = useTranslations();
  // ... or with namespace:
  // const t = useTranslations("homePage");

  return <p>{t("hero.welcomeMessage")}</p>;
}

5. Add Keys to Locale Files

Call: add_translations
Parameters: {
  "project_root_path": "<project_path>",
  "translations": [
    {
      "locale": "en",
      "keys": {
        "common.submit": "Submit",
        "auth.emailPlaceholder": "Enter your email",
        "homePage.hero.welcomeMessage": "Welcome to our app"
      }
    }
  ]
}

Nested keys (e.g., common.submit) are automatically expanded to nested JSON structure.

6. Handle Pagination

If pagination.has_more is true, continue with next offset:

Call: scan_hardcoded
Parameters: { "project_root_path": "<project_path>", "limit": 20, "offset": 20 }

Step-by-Step: Fixing Primary Missing Keys

After fixing hardcoded issues, some keys might be used in code but missing from locale files.

1. Scan for Missing Keys

Call: scan_primary_missing
Parameters: { "project_root_path": "<project_path>" }

Each item shows:

• key: The missing key name
• file_path: Where it's used
• line: Line number

2. Add Missing Keys

For each missing key, determine the appropriate translation value and add it:

Call: add_translations
Parameters: {
  "project_root_path": "<project_path>",
  "translations": [
    {
      "locale": "en",
      "keys": {
        "missingKey1": "Translation value 1",
        "missingKey2": "Translation value 2"
      }
    }
  ]
}

Step-by-Step: Fixing Replica Lag

Keys that exist in primary locale but missing in other locales.

1. Scan for Replica Lag

Call: scan_replica_lag
Parameters: { "project_root_path": "<project_path>" }

Each item shows:

• key: The key name
• value: Value in primary locale
• exists_in: Primary locale code
• missing_in: Array of locales missing this key

2. Sync to Other Locales

Option A: Copy primary value (for same-language variants or as placeholder)

Call: add_translations
Parameters: {
  "project_root_path": "<project_path>",
  "translations": [
    { "locale": "de", "keys": { "common.submit": "Submit" } },
    { "locale": "fr", "keys": { "common.submit": "Submit" } }
  ]
}

Option B: Ask user for translations

If the user can provide translations, use their values. Otherwise, copy the primary value as a placeholder with a TODO comment in the code or a note to the user.

Step-by-Step: Fixing Untranslated Values

Values that are identical to the primary locale may indicate text was copied without being translated.

1. Scan for Untranslated Values

Call: scan_untranslated
Parameters: { "project_root_path": "<project_path>" }

Each item shows:

• key: The translation key
• value: The value (same in both locales)
• locale: The non-primary locale with the issue
• primary_locale: The primary locale code

2. Translate the Values

For each untranslated key, provide the correct translation:

Call: add_translations
Parameters: {
  "project_root_path": "<project_path>",
  "translations": [
    { "locale": "de", "keys": { "common.submit": "Absenden" } },
    { "locale": "fr", "keys": { "common.submit": "Soumettre" } }
  ]
}

Note: Some values may intentionally be the same across locales (e.g., brand names, technical terms). Use your judgment or ask the user.

Key Naming Conventions

Namespace Structure

<area>.<section>.<element>

Examples:

• common.buttons.submit - Shared UI elements
• auth.login.title - Authentication pages
• dashboard.sidebar.menuItem - Dashboard specific
• errors.validation.required - Error messages

Rules

1. Use camelCase: welcomeMessage not welcome-message
2. Be specific: auth.loginButton not just login
3. Group by feature: Keep related keys together
4. Avoid deep nesting: Max 3-4 levels

Special Cases

Plurals (if using next-intl plural support):

{
  "items": "{count, plural, =0 {No items} =1 {One item} other {# items}}"
}

Variables:

{
  "greeting": "Hello, {name}!"
}

Common Patterns

JSX Text Content

// Before
<h1>Welcome</h1>

// After
<h1>{t("page.welcome")}</h1>

Attributes (placeholder, title, alt, aria-*)

// Before
<input placeholder="Search..." />
<img alt="User avatar" />

// After
<input placeholder={t("common.searchPlaceholder")} />
<img alt={t("common.userAvatar")} />

Conditional Text

// Before
{
  isLoading ? "Loading..." : "Submit";
}

// After
{
  isLoading ? t("common.loading") : t("common.submit");
}

Template Literals

// Before
<p>{`Welcome, ${userName}`}</p>

// After (using next-intl variables)
<p>{t("greeting", { name: userName })}</p>
// In JSON: "greeting": "Welcome, {name}"

Important Notes

1. Work in batches: Fix 10-20 issues at a time, then verify
2. Re-scan after fixes: Run scan_overview again to verify progress
3. Handle pagination: Check has_more field and continue if needed
4. Preserve formatting: When modifying TSX, maintain existing code style
5. Import hook: Ensure useTranslations is imported in modified components
6. Test after changes: Recommend user runs the app to verify translations work

Troubleshooting

"Config file not found"

Run glot init in the project root to create .glotrc.json

Keys not being detected

Check that messages_dir in config points to correct locale files directory

Some text not detected as hardcoded

The text must contain at least one alphabetic character. Pure numbers/symbols are ignored.