next-intl-mcp-server

MCP server for next-intl — i18n tooling for Next.js App Router.

Table of Contents

• About
• Features
• Tools
  • next_intl_internalize
  • next_intl_sync_locales
  • next_intl_validate_icu
  • next_intl_scaffold
• Resources
• Prompts
  • review_i18n_completeness
  • translate_messages
  • audit_locale_file
• Configuration
  • Claude Code
  • Cursor
  • VS Code
  • Codex
• Contributing
• Changelog
• License

About

next-intl-mcp-server provides MCP-compatible AI clients with deep, deterministic knowledge of next-intl — the leading i18n library for the Next.js App Router.

Instead of relying on boilerplate or expecting the AI to infer the correct API usage, this server offers purpose-built tools to transform components, detect inconsistencies across locale files, validate ICU syntax, and scaffold complete project setups — with or without URL-based routing.

(back to top)

Features

• 🔄 Transform any component to use next-intl with a single call
• 🌍 Detect missing or outdated translation keys across locale files
• ✅ Validate ICU message syntax before deployment
• 🏗️ Scaffold a complete project setup for both routing modes
• 📚 Built-in reference guides for components, ICU syntax, and setup
• 🤖 Structured prompt templates for review, translation, and auditing workflows
• 🔒 Fully local execution — runs over stdio with no network calls
• ⚡ No installation required — works instantly via npx

(back to top)

Tools

next_intl_internalize

Transforms a Next.js TSX component into a fully internationalized version. It detects the component type (server-async, client, or shared), extracts all hardcoded strings (including JSX content, accessibility attributes, and metadata), injects the appropriate API (getTranslations or useTranslations), and returns both the transformed source code and ready-to-use message JSON for each target locale.

Use next_intl_internalize on this component with targetLocales ["en", "pt"]:

export default async function HeroSection() {
  return (
    <section>
      <h1>Welcome to our platform</h1>
      <button aria-label="Start for free">Get started</button>
    </section>
  );
}

next_intl_sync_locales

Compares multiple locale JSON files against a reference locale and reports missing keys, extra or stale entries, and a suggested patch for each locale. The patch is a minimal JSON structure containing [TODO:locale] placeholders, ready to merge.

Use next_intl_sync_locales with referenceLocale "en" and these locales:
{
  "en": "<contents of messages/en.json>",
  "pt": "<contents of messages/pt.json>"
}

next_intl_validate_icu

Validates ICU message syntax across a locale file using a brace-depth parser. It detects unbalanced braces, missing required other categories in plural or select blocks, unclosed rich-text tags, and invalid key naming.

Use next_intl_validate_icu with the content of my messages/pt.json before I deploy.

next_intl_scaffold

Generates a complete next-intl boilerplate for a Next.js App Router project. Supports two routing modes:

• locale-prefix — locale included in the URL (/en/about). Generates routing.ts, navigation.ts, request.ts, proxy.ts, next.config.ts, app/[locale]/layout.tsx, and starter message catalogs.
• none — no locale in the URL, ideal for admin panels and SPAs. Resolves locale via cookie, header, or domain, and optionally includes a switchLocale Server Action.

Scaffold a next-intl project with locales ["en", "pt", "es"],
defaultLocale "en", routing "none", localeSource "cookie".

(back to top)

Resources

Built-in reference guides available to your AI client at any time — no additional prompting required.

URI	Description
next-intl://guide/component-patterns	API selection guide, component examples, and common pitfalls
next-intl://guide/icu-syntax	Full ICU reference: interpolation, plural, select, ordinal, date/number, rich text
next-intl://guide/setup	Setup guide with file structure and routing mode comparison

Prompts

Structured prompt templates designed to guide multi-step workflows.

review_i18n_completeness

Generates a structured review for a component. It identifies hardcoded strings, verifies correct API usage, checks for missing NextIntlClientProvider, and returns a checklist alongside internationalized code and message JSON.

Review this component for i18n completeness.

translate_messages

Creates a translation prompt that preserves ICU syntax. It translates only values, keeps keys intact, preserves placeholders ({name}, {count, plural, …}) and rich-text tags (<link>…</link>), and applies correct pluralization rules per language.

Translate messages/en.json to "pt,es,fr" preserving all ICU placeholders.

audit_locale_file

Builds a complete audit prompt for a locale file. It checks ICU syntax, validates key naming conventions, detects untranslated values, and flags suspicious placeholders — returning a structured report with severity levels.

Audit messages/pt-BR.json and report all issues with severity.

Configuration

You can use any MCP client to interact with the next-intl MCP server. Below are setup instructions for the most popular clients.

Claude Code

Add to your project's .mcp.json for team-wide sharing:

{
  "mcpServers": {
    "next-intl": {
      "command": "npx",
      "args": ["-y", "next-intl-mcp-server"]
    }
  }
}

Or add globally via CLI:

claude mcp add next-intl -- npx -y next-intl-mcp-server

Verify with claude mcp list.

See the Claude Code MCP documentation for more details.

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "next-intl": {
      "command": "npx",
      "args": ["-y", "next-intl-mcp-server"]
    }
  }
}

Enable the server in Cursor Settings. A green indicator confirms activation.

See the Cursor MCP documentation for more details.

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "next-intl": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "next-intl-mcp-server"]
    }
  }
}

Open the file and click Start next to the server entry.

See the VS Code MCP documentation for more details.

Codex

Add to ~/.codex/config.toml:

[mcp_servers.next-intl]
command = "npx"
args = ["-y", "next-intl-mcp-server"]

Restart Codex to load the server.

See the Codex MCP documentation for more details.

(back to top)

Contributing

If you'd like to contribute, review our contribution guidelines and open an issue or pull request.

(back to top)

Changelog

See CHANGELOG for a complete and human-readable history of changes.

(back to top)

License

Distributed under the MIT License. See LICENSE for details.

(back to top)