the-i18n-kit

Translation file management for developers and AI agents. Find missing keys, remove dead ones, rename across all locales at once — from the terminal or from inside your AI coding session.

The Problem

Managing i18n at scale is tedious:

• You add a new UI component and need to create the translation key in every locale file — manually
• Over time, removed components leave behind hundreds of orphan keys nobody uses
• You rename a key and have to hunt it down across 30+ JSON files
• Your AI agent writes $t('some.key') and has no idea where the locale files live or what already exists
• translate_missing returns 50KB of JSON that floods your agent's context window

The-i18n-kit solves all of this.

How It Works

The-i18n-kit auto-detects your project structure (Nuxt, Laravel, or any generic setup), then gives you two interfaces:

A CLI for direct use in the terminal:

the-i18n-cli missing              # what's not translated yet?
the-i18n-cli orphans              # what keys are dead code?
the-i18n-cli rename old.key new.key   # rename across all locales at once
the-i18n-cli translate-key --layer root --key common.save --sourceLocale en-US --sourceValue "Save"  # update one key and translate targets
the-i18n-cli cleanup              # remove orphan keys (dry-run by default)

An MCP server that plugs into AI coding agents (Cursor, Claude, VS Code, Zed). Your agent can read, write, and maintain translation files as part of its normal workflow — with your glossary, tone notes, and layer rules loaded as context so translations stay consistent.

Agent adds $t('booking.confirm.title')
  → calls add_translations (writes exact values the agent provides)
  → calls translate_missing (fills remaining locales via MCP sampling)
Done. All 28 locales updated, consistent terminology, no manual work.

Agent changes wording for an existing key
  → calls translate_key with the source locale/value
  → MCP sampling refreshes target locales, including stale existing values when overwrite=true

Packages

Package	Version	Description
the-i18n-cli		CLI + core library — install globally
the-i18n-mcp		MCP server for AI agents

Quick Start

CLI

npm install -g the-i18n-cli

the-i18n-cli detect                    # verify project is auto-detected
the-i18n-cli missing                   # find missing translations
the-i18n-cli orphans                   # find unused translation keys
the-i18n-cli search --query "save"     # search keys and values
the-i18n-cli cleanup                   # remove orphan keys (dry-run by default)

→ Full CLI documentation

MCP Server

Add to your MCP host (VS Code, Cursor, Claude Desktop, Zed):

{
  "servers": {
    "the-i18n-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["the-i18n-mcp@latest"]
    }
  }
}

→ Full MCP documentation

CI / Automation

Auto-translate missing keys and find orphans in CI — no manual work. Runs on every MR/PR that touches locale files or source code.

Provider-agnostic. Bring your own API key for OpenAI, Anthropic, or Google.

GitHub Actions

# .github/workflows/i18n.yml
name: i18n

on:
  pull_request:
    paths:
      - i18n/locales/en.json
      - components/**/*.vue

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: fabkho/the-i18n-kit@main
        with:
          provider: google
          model: gemini-2.0-flash
          api_key: ${{ secrets.GEMINI_API_KEY }}
          layer: common

Translations are committed and pushed back to the PR branch. A summary comment is posted on the PR.

GitLab CI

Two reusable jobs: .i18n-translate and .i18n-cleanup.

# .gitlab-ci.yml
include:
  - remote: 'https://raw.githubusercontent.com/fabkho/the-i18n-kit/main/gitlab-ci.yml'

i18n-translate:
  extends: .i18n-translate
  variables:
    I18N_PROVIDER: google
    I18N_MODEL: gemini-2.0-flash
    I18N_API_KEY: $GEMINI_API_KEY
    I18N_LAYER: common
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - i18n/locales/en.json

i18n-cleanup:
  extends: .i18n-cleanup
  variables:
    I18N_LAYER: root
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - components/**/*.vue
        - i18n/locales/*.json

Translations are pushed to the MR branch. Orphan findings are posted as an MR comment with expandable details. Cleanup artifacts (.i18n-reports/orphans.json) are retained for 7 days.

.i18n-translate variables:

.i18n-cleanup variables:

Enterprise setups (private registries, yarn, custom images): override before_script on the extending job. The template's image, before_script, tags, and cache are all overridable.

Supported Frameworks

Using with Any Framework (Generic Adapter)

For projects that aren't Nuxt or Laravel, create a .i18n-mcp.json at your project root:

{
  "defaultLocale": "en",
  "localeDirs": ["src/locales"],
  "locales": ["en", "de", "fr", "es"]
}

All tools work immediately.

localeDirs supports both flat and layered setups:

// Flat: all locale files in one directory
"localeDirs": ["src/i18n"]

// Layered: multiple directories with named layers
"localeDirs": [
  { "path": "src/i18n/common", "layer": "common" },
  { "path": "src/i18n/dashboard", "layer": "dashboard" }
]

💡 Tip: Let your AI agent generate this config. Ask it to inspect your locale file layout and create the .i18n-mcp.json — takes seconds.

Project Config

Drop a .i18n-mcp.json at your project root to give agents (and the CLI) project context:

{
  "$schema": "node_modules/the-i18n-mcp/schema.json",
  "context": "B2B SaaS booking platform",
  "glossary": {
    "Booking": "Core concept. Dutch: 'Boeking'.",
    "Resource": "A bookable entity (room, desk, person)"
  },
  "translationPrompt": "Professional but approachable tone. Keep translations concise.",
  "localeNotes": {
    "de": "Informal German (du)",
    "de-formal": "Formal German (Sie)"
  }
}

This context is automatically loaded by detect_i18n_config before any translation work, so agents use the right terminology and tone across all locales.

Agent Translation Workflow

When an AI agent builds a feature and adds new translation keys:

1. Agent adds $t('some.key') to the Vue/Blade component
2. Agent calls detect_i18n_config → loads .i18n-mcp.json (context, glossary, layerRules) into its session
3. Agent calls add_translations — writes exact translations the agent provides. No separate sampling involved.
4. Agent calls translate_missing → MCP sampling fills any locales the agent didn't cover via a separate LLM call.
5. When source wording changes, agent calls translate_key to refresh one key across target locales (including existing stale translations when overwrite=true).

The add-feature-translations MCP prompt codifies this as a reusable workflow. It also checks for duplicate keys via search_translations before writing.

Exact writes vs translation tools: add_translations and update_translations are pure write tools — they take locale-value maps and write them, no LLM involved. translate_missing fills only missing target values via sampling. translate_key translates one source key into target locales and can overwrite stale existing target values.

Handling Large Outputs

Tools like find_orphan_keys and get_missing_translations can return large payloads. Pass --output-file (CLI) or outputFile (MCP) to write the full report to disk and get only a compact summary back:

the-i18n-cli orphans --output-file /tmp/orphans.json
# → Wrote report to: /tmp/orphans.json
# → { orphanCount: 1103, filesScanned: 2526, ... }

// MCP call
{ "tool": "find_orphan_keys", "arguments": { "outputFile": "/tmp/orphans.json" } }
// → { "reportFile": "/tmp/orphans.json", "summary": { ... } }

Alternatively, set reportOutput: true in .i18n-mcp.json to always write reports to .i18n-reports/ in the project root.

How Orphan Detection Works

The scanner finds translation key references in source code:

Nuxt/Vue patterns: $t('key'), t('key'), $tc('key'), i18n.t('key'), template literals with $t

Laravel/PHP patterns: __('key'), trans('key'), @lang('key'), Lang::get('key'), trans_choice('key')

Bare string candidates: Any quoted dot-notation string in source ('some.key', "some.key") is treated as a potential key reference — regardless of whether it's inside a t() call. This catches patterns like { label: 'common.actions.save', i18n: true } and non-standard i18n call styles.

Dynamic key handling:

• Template literals: $t(`status.${val}`) → matches all keys under status.*
• String concatenation: t('prefix.' + var) → matches all keys under prefix.* (single-line and multiline forms both detected)
• Keys matched by dynamic patterns are reported as "uncertain" separately and excluded from cleanup

Scan scope:

• Scans recursively from the project root — all source files, all layers
• Standard ignore dirs (node_modules, .nuxt, .output, dist) excluded automatically

Development

pnpm install        # Install all dependencies
pnpm build          # Build all packages
pnpm test           # Run all tests
pnpm lint           # ESLint across all packages
pnpm typecheck      # TypeScript check all packages

Set DEBUG=1 to enable verbose logging to stderr.

Roadmap

• find_hardcoded_strings — detect user-facing strings not wrapped in translation calls
• move_translations — move keys between layers
• Glossary validation — check translations against glossary terms
• Flat JSON support — flatJson: true in vue-i18n config
• Pluralization support — vue-i18n plural forms and Laravel trans_choice

License

MIT