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.

Add to .vscode/mcp.json:

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

Add to .zed/settings.json:

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

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.

Prompts

Resources

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"
}

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