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.

Input	Required	Default	Description
provider	✅	—	openai, anthropic, or google
model	✅	—	Model name
api_key	✅	—	API key for the provider
layer	✅	—	Layer name (e.g. common, dashboard)
locales	—	all except source	Comma-separated target locales
source_locale	—	from .i18n-mcp.json	Reference locale
keys	—	all missing	Comma-separated keys to translate
batch_size	—	50	Keys per LLM call
concurrency	—	provider default	Parallel LLM calls
dry_run	—	false	Preview without writing files
commit_message	—	auto-generated	Custom commit message
peer_deps	—	—	Space-separated npm packages (e.g. @google/genai)

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:

Variable	Required	Default	Description
I18N_PROVIDER	✅	—	openai, anthropic, or google
I18N_MODEL	✅	—	Model name
I18N_API_KEY	✅	—	API key for the provider
I18N_LAYER	✅	—	Layer name
I18N_LOCALES	—	all except source	Comma-separated target locales
I18N_SOURCE_LOCALE	—	from .i18n-mcp.json	Reference locale
I18N_KEYS	—	all missing	Comma-separated keys
I18N_BATCH_SIZE	—	50	Keys per LLM call
I18N_CONCURRENCY	—	provider default	Parallel LLM calls
I18N_DRY_RUN	—	false	Preview without writing
I18N_INSTALL_PEER_DEPS	—	—	Space-separated npm packages
I18N_COMMIT_MESSAGE	—	auto-generated	Custom commit message
I18N_MR_COMMENT	—	true	Post summary comment on MR

.i18n-cleanup variables:

Variable	Required	Default	Description
I18N_LAYER	✅	—	Layer name
I18N_INSTALL_PEER_DEPS	—	—	Space-separated npm packages

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

Framework	Locale Format	Auto-Detection
Nuxt (v3+)	JSON	nuxt.config.ts with @nuxtjs/i18n
Laravel (9+)	PHP arrays	artisan, composer.json, lang/
Generic	JSON or PHP	localeDirs + defaultLocale in .i18n-mcp.json

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.

Field	Required	Description
defaultLocale	✅	Your reference locale — the source of truth for key completeness
localeDirs	✅	Paths to locale directories (relative to project root)
locales	❌	Explicit locale codes. If omitted, auto-discovered from filenames

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.

All config options

Field	Purpose
framework	Force framework detection: "nuxt", "laravel", or "generic"
context	Free-form project background for the agent
layerRules	Rules for which layer a new key belongs to
glossary	Term dictionary for consistent translations
translationPrompt	System prompt for all translation requests
localeNotes	Per-locale instructions (formality, terminology)
examples	Few-shot translation examples
orphanScan	Per-layer ignore patterns for orphan detection
reportOutput	true or path — write large tool output to disk instead of returning it inline
samplingPreferences	Override model preferences for translate_missing
localeDirs	Locale directories for the generic adapter
defaultLocale	Default locale code (required for generic adapter)
locales	Explicit list of locale codes

---

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