nuxt-i18n-mcp

nuxt-i18n-mcp

MCP server for managing i18n translations in Nuxt projects. Provides 14 tools for the full translation lifecycle: read, write, search, rename, remove, find missing, auto-translate, and detect unused keys — all without loading entire locale files into context. Supports monorepos, Nuxt layers, and per-project configuration (glossary, tone, layer rules). Works with any MCP host (VS Code, Cursor, Zed, Claude Desktop).

Quick Start

1. Configure your MCP host

No install needed — your MCP host runs the server via npx.

VS Code / Cursor

Add to .vscode/mcp.json:

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

Zed

Add to .zed/settings.json:

{
  "context_servers": {
    "nuxt-i18n-mcp": {
      "command": "npx",
      "args": ["nuxt-i18n-mcp@latest"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "nuxt-i18n-mcp": {
      "command": "npx",
      "args": ["nuxt-i18n-mcp@latest"]
    }
  }
}

2. Ask your agent

That's it — no configuration needed. The server auto-detects your Nuxt config, layers, locales, and directory structure via @nuxt/kit. Just ask:

"Add a 'save changes' button translation in all locales"

"Find and fix all missing translations in the admin layer"

"Rename common.actions.delete to common.actions.remove across all locales"

Typical Workflow

1. detect_i18n_config        → understand project structure, locales, layers
2. list_locale_dirs           → see available layers with file counts and key namespaces
3. get_missing_translations   → find gaps between reference locale and targets
4. add_translations           → add new keys (requires layer param)
   translate_missing          → auto-translate missing keys via MCP sampling
5. find_orphan_keys           → find keys not referenced in source code
   cleanup_unused_translations → remove orphan keys in one step

Always call detect_i18n_config first — all other tools depend on the detected config.

Tools

Every write tool requires a layer parameter (e.g., "root", "app-admin"). Use list_locale_dirs to discover available layers.

Tool	Description
detect_i18n_config	Loads Nuxt config, returns locales, layers, directories, and project config. Call first.
list_locale_dirs	Lists locale directories grouped by layer, with file counts and top-level key namespaces
get_translations	Reads values for dot-path keys from a locale/layer. Use "*" as locale for all locales
add_translations	Adds new keys to a layer across locales. Fails if key already exists. Supports dryRun
update_translations	Updates existing keys in a layer. Fails if key doesn't exist. Supports dryRun
remove_translations	Removes keys from ALL locale files in a layer. Supports dryRun
rename_translation_key	Renames/moves a key across all locales in a layer. Conflict detection + dryRun
get_missing_translations	Finds keys present in reference locale but missing/empty in targets. "" counts as missing
find_empty_translations	Finds keys with empty string values. Checks each locale independently
search_translations	Searches by key pattern or value substring across layers and locales
translate_missing	Auto-translates via MCP sampling, or returns context for inline translation when sampling unavailable
find_orphan_keys	Finds keys in JSON not referenced in any Vue/TS source code
scan_code_usage	Shows where keys are used — file paths, line numbers, call patterns
cleanup_unused_translations	Finds orphan keys + removes them in one step. Dry-run by default

Prompts

Prompt	Description
add-feature-translations	Guided workflow for adding translations when building a new feature. Accepts optional layer and namespace
fix-missing-translations	Find and fix all missing translations across the project. Accepts optional layer

Resources

Resource	Description
i18n:///{layer}/{file}	Browse locale files directly (e.g., i18n:///root/en-US.json)

Monorepo Support

The server discovers all Nuxt apps with i18n configuration under the given projectDir. Pass the monorepo root and it walks the directory tree, finds every nuxt.config.ts with i18n settings, loads each app via @nuxt/kit, and merges the results. Each app's locale directories become separate layers.

monorepo/
├── apps/
│   ├── shop/          ← discovered, becomes "shop" layer
│   │   └── nuxt.config.ts (has i18n)
│   └── admin/         ← discovered, becomes "admin" layer
│       └── nuxt.config.ts (has i18n)
├── packages/
│   └── shared/        ← skipped, no nuxt.config with i18n
└── package.json

Discovery stops descending into a directory once it finds a nuxt.config — nested Nuxt layers are loaded by @nuxt/kit automatically.

Project Config

Optionally drop a .i18n-mcp.json at your project root to give the agent project-specific context. Everything is optional — the server passes it to the agent, which interprets the natural-language rules. The server walks up from projectDir to find the nearest config file (like ESLint or tsconfig resolution).

For IDE autocompletion, point to the schema:

{
  "$schema": "node_modules/nuxt-i18n-mcp/schema.json"
}

Field	Purpose
context	Free-form project background (business domain, user base, brand voice)
layerRules	Rules for which layer a new key belongs to, with natural-language when conditions
glossary	Term dictionary for consistent translations
translationPrompt	System prompt prepended to all translation requests
localeNotes	Per-locale instructions (e.g., "de-DE-formal": "Use 'Sie', not 'du'")
examples	Few-shot translation examples demonstrating project style
orphanScan	Per-layer config for orphan detection: scanDirs (overrides auto-discovered dirs) and ignorePatterns (glob)
reportOutput	true for default .i18n-reports/ dir, or a string for a custom path. Diagnostic tools write full output to disk and return only a summary in the MCP response

Full example

{
  "$schema": "node_modules/nuxt-i18n-mcp/schema.json",
  "context": "B2B SaaS booking platform. Professional but approachable tone.",
  "layerRules": [
    {
      "layer": "shared",
      "description": "Shared translations: common.actions.*, common.messages.*",
      "when": "The key is generic enough to be used in multiple apps"
    },
    {
      "layer": "app-admin",
      "description": "Admin dashboard translations",
      "when": "The key is only relevant to admin functionality"
    }
  ],
  "glossary": {
    "Buchung": "Booking (never 'Reservation')",
    "Ressource": "Resource (a bookable entity like a room, desk, or person)",
    "Termin": "Appointment"
  },
  "translationPrompt": "Use professional but approachable tone. Preserve all {placeholders}. Keep translations concise.",
  "localeNotes": {
    "de-DE-formal": "Formal German using 'Sie'. Used by enterprise customers.",
    "en-US": "American English.",
    "en-GB": "British English. Use 'colour' not 'color'."
  },
  "examples": [
    {
      "key": "common.actions.save",
      "de-DE": "Speichern",
      "en-US": "Save",
      "note": "Concise, imperative"
    }
  ],
  "orphanScan": {
    "shared": {
      "scanDirs": ["apps/shop", "apps/admin", "packages/shared"],
      "ignorePatterns": ["common.datetime.**", "common.countries.*"]
    },
    "app-admin": {
      "scanDirs": ["apps/admin"]
    }
  },
  "reportOutput": true
}

See playground/.i18n-mcp.json for a working example.

Features

• Zero config — reads nuxt.config.ts (including layers) automatically via @nuxt/kit. Works in monorepos.
• Safe writes — atomic file I/O (temp file + rename), indentation preservation, alphabetical key sorting, {placeholder} and @:linked ref validation.
• Full lifecycle — add, update, remove, rename, search, find missing, auto-translate, and clean up unused keys.
• Code analysis — find orphan keys not referenced in Vue/TS source, scan usage locations (file + line), bulk cleanup.
• Project-aware — optional .i18n-mcp.json for glossary, tone, layer rules, locale-specific instructions, and few-shot examples.
• Caching — config detection and file reads are cached (mtime-based). Writes invalidate automatically.
• Sampling support — translate_missing uses MCP sampling when available (VS Code). Falls back to returning context for inline translation (Zed, others).

Roadmap

• find_hardcoded_strings — detect user-facing strings not wrapped in $t()
• move_translations — move keys between layers (e.g., promote to shared)
• Glossary validation — check translations against glossary terms
• Flat JSON support — flatJson: true in vue-i18n config
• Pluralization support — vue-i18n plural forms
• Plain vue-i18n support — extract core into a monorepo, add a Vue/Vite adapter alongside the Nuxt one

Development

pnpm build          # Build via tsdown → dist/index.js
pnpm test           # Run all tests
pnpm test:perf      # Run performance benchmarks
pnpm lint           # ESLint
pnpm typecheck      # tsc --noEmit
pnpm start          # Start the server on stdio
pnpm inspect        # Open MCP Inspector for manual testing

License

MIT