Multi-Framework i18n MCP Server (i18n-mcp)

Production-quality Model Context Protocol (MCP) server for automated internationalization across React Native, React (web), Next.js, Flutter, and Angular projects.

Designed for AI coding agents (Antigravity, Claude Code, Cursor, Gemini CLI, etc.) to inspect projects, detect hardcoded user-facing strings with AST precision, understand existing i18n architectures, resolve ambiguous text candidates collaboratively, generate semantic translation keys, translate them, replace source code safely, and validate results.

Supported Frameworks

Related MCP server: kaeris-mcp

Key Principles & Innovations

• Framework Adapters Architecture: Decoupled core i18n engine with dedicated adapters (IFrameworkAdapter) that normalize component sinks, text props, feedback callees, and hook conventions per framework.

• Two-Stage Hybrid String Detection:

  • Stage 1 (Deterministic AST Fast-Pass): Categorizes 90%+ strings with zero latency using the 4-Pillar classifier (Structural Text Sinks, Code Token Filtering, Inverted Non-Sink Default, Semantic Role Tagging). Obvious UI is marked CONFIRMED_UI; code tokens/styles/URLs are CONFIRMED_TECHNICAL; boundary cases are tagged AMBIGUOUS.

  • Stage 2 (Agent Semantic Batch Resolution): Coding agents (or developers) inspect ambiguous candidates and provide structured decisions via candidateDecisions: { [candidateId]: boolean } to generate_i18n_plan or internationalize.

• AST First, Regex Second: Precision parsing of AST nodes rather than fragile regular expressions.

• Safety First & Conservative Defaults: Dry-run by default (dryRun: true, apply: false). Stale-plan protection with source SHA-256 hashes prevents accidental overwrites.

• Human-in-the-Loop Orchestration: Generates deterministic unified diff previews for review before disk mutations occur.

MCP Tools

analyze_project

Analyzes a project without modifying any files.

• Inputs: projectPath (string, optional)

• Returns:

  • framework: React Native / React / Next.js / Flutter / Unknown

  • language: TypeScript / JavaScript / Dart

  • packageManager: npm / yarn / pnpm / bun / flutter pub

  • i18n: Library (react-i18next, next-intl, flutter_localizations, etc.), locale directory, source and target locales, config file

  • namespaces: Existing and inferred namespaces

  • projectStructure: Feature and screen directory layout

  • accessPatterns: Detected hooks and translation functions (useTranslation, t, i18n.t, Trans, etc.)

  • warnings: Actionable warnings (missing target locales, inconsistent namespace files, malformed JSON/ARB)

scan_hardcoded_texts

Scans a React Native project (as well as React, Next.js, and Flutter) or requested scope for hardcoded strings using AST analysis without modifying any files.

• Inputs:

  • projectPath (string, optional): Project root directory.

  • scope (string | string[], optional): Single file, directory, or glob pattern.

  • include / exclude (string[], optional): Custom inclusion/exclusion globs.

  • onlyUserFacing (boolean, optional, default true): If false, includes technical strings.

  • minConfidence (number, optional, default 0.0): Confidence score filter (0.0 to 1.0).

  • ambiguousOnly (boolean, optional, default false): If true, returns only ambiguous strings requiring agent/human resolution.

• Returns:

  • Detections with id (file:line:col), file, line, column, text, type, classification, confidence, semanticRole (CONFIRMED_UI, CONFIRMED_TECHNICAL, AMBIGUOUS), suggestedNamespace, suggestedKey, and variables.

generate_i18n_plan

Analyzes detected hardcoded strings and produces a complete, deterministic, reviewable i18n migration plan with zero filesystem mutations.

• Inputs:

  • projectPath / scope / include / exclude: Scope parameters.

  • sourceLocale / targetLocales: Locale settings.

  • confidenceThreshold (number, optional, default 0.7): Minimum score for automatic replacement.

  • includeAmbiguous (boolean, optional, default false): Include ambiguous strings marked for review.

  • candidateDecisions (record, optional): Map of candidate ID or text to boolean decision (true = approve as user-facing, false = skip as technical).

• Returns: Complete I18nPlan including replacements, hook insertions, new translation keys, and source hashes.

apply_i18n_plan

Safely and atomically applies an approved i18n migration plan to the project (React Native, React, Next.js, Flutter).

• Inputs:

  • plan or planPath: The approved I18nPlan.

  • dryRun (boolean, optional, default false): Calculates changes and returns diffs without modifying files.

  • createBackup (boolean, optional, default false): Creates .bak copies before writing changes.

  • failOnWarnings (boolean, optional, default false): Aborts if warnings exist.

• Returns: Applied changes summary, modified files list, and diff preview.

translate_i18n

Translates missing keys across target locale files (JSON or Flutter ARB) using pluggable cloud translation providers (deepl, openai, gemini), built-in dictionaries, custom glossaries, or AI agent translations with Context-Aware Prompting without overwriting existing translations.

• Inputs:

  • projectPath: Project root directory.

  • sourceLocale, targetLocales: Locales to translate.

  • namespaces: Target namespaces to translate.

  • provider ("auto" | "deepl" | "openai" | "gemini" | "dictionary", optional, default "auto"): Cloud translation provider. Completely optional and non-blocking; seamlessly falls back to offline dictionaries if unconfigured, offline, or timed out.

  • apiKey (string, optional): Cloud translation API key (or set DEEPL_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY in environment).

  • formality ("formal" | "informal" | "neutral", optional): Desired tone / grammatical formality (e.g. German "Sie" vs "du", French "vous" vs "tu", Spanish "usted" vs "tú").

  • context (object, optional): Explicit contextual clues including role ("BUTTON", "TITLE", "PLACEHOLDER"), componentName, elementTag, propName, filePath, description, maxLength, and surroundingText.

  • glossary (object, optional): Brand glossary containing neverTranslate brand terms and terms dictionary mappings.

  • dryRun: Preview translation changes without writing to disk.

  • providedTranslations (optional map of { [locale]: { [key]: translation } }).

• Context-Aware Intelligence:

  • Automatically infers UI role classifications from key naming conventions (e.g. *_BUTTON, *_TITLE, *_PLACEHOLDER, *_ERROR, *_TOOLTIP, *_NAV).

  • Automatically extracts Flutter ARB @key.description translator notes to guide LLM disambiguation and parts of speech.

  • Injects structured context clues into OpenAI system prompts, Gemini instructions, and DeepL API context & formality parameters.

validate_i18n

Validates i18n implementation for missing translations, interpolation variable mismatches, orphan keys, unused dead keys, and malformed files across JSON and ARB catalogs.

• Inputs: projectPath, locales, namespaces, checkSourceCode, checkUnusedKeys, pruneUnusedKeys, scope.

generate_i18n_types

Generates compile-time TypeScript definitions (resources.d.ts) with module augmentation for i18next / react-i18next / next-intl from source locale catalogs, ensuring strict autocomplete and compile-time key safety.

• Inputs: projectPath, outputPath (default: src/@types/resources.d.ts), writeToDisk (boolean, default: true).

generate_pseudolocale

Generates pseudo-localized catalogs (qps-ploc, en-XA, qps-plocm bidi) from source locale files for L10n stress-testing. Tests font glyph support, text expansion (+35%), UI layout clipping, and identifies hardcoded unextracted strings while safely preserving variables and HTML tags.

• Inputs: projectPath, sourceLocale, targetLocale (default: "qps-ploc"), strategy ("accented" | "bidi" | "expansion" | "all"), expansionRatio (default: 0.35), delimiter ("brackets" | "exclamation" | "none"), namespaces, dryRun.

format_catalogs

Cleans, sorts, and formats translation catalogs (JSON and ARB) alphabetically or aligned with source locale key ordering, eliminating merge conflicts and inconsistent indentation.

• Inputs: projectPath, locales, namespaces, sortOrder ("alphabetical" | "align-with-source"), indent (default: 2), dryRun.

audit_rtl

Audits codebase for Right-to-Left (RTL) and bidirectional layout bugs, detecting physical spacing (marginLeft/marginRight), alignment (textAlign: left), physical Tailwind utility classes (ml-, mr-, text-left), Flutter physical offsets (EdgeInsets.only(left:), Alignment.centerLeft), directional icons, and missing RTL root configs, with automated logical property migration (fix: true).

• Inputs: projectPath, scope, targetLocales (e.g. ['ar', 'he']), fix (boolean, default: false), dryRun (boolean, default: true).

audit_plurals

Audits translation catalogs (JSON and Flutter ARB) against official Unicode CLDR plural and gender rules, detecting missing mandatory categories (e.g., Arabic zero/two/few/many, Russian few/many), missing mandatory other fallback branches, and variable mismatches, with automated scaffold fixing (fix: true).

• Inputs: projectPath, locales (e.g. ['ar', 'ru', 'pl']), namespaces, fix (boolean, default: false), dryRun (boolean, default: true).

audit_formatting

Audits project source code (React Native, React, Vue, Flutter, Next.js) for unlocalized formatting anti-patterns:

• Hardcoded Currency Concatenation: Flagging expressions like `$${price}`, price + " €", and Flutter '\$${item.price}', with automated migration to Intl.NumberFormat or Flutter NumberFormat.simpleCurrency.

• Unlocalized Decimals: Detects .toFixed() or .toStringAsFixed() where decimal points/commas depend on user locale.

• Hardcoded Percentages: Detects `${discount}%` and migrates to localized percentage formatting.

• Unparameterized Date & Time: Detects bare .toLocaleDateString() and .toLocaleTimeString() calls with automated migration to Intl.DateTimeFormat(undefined, { dateStyle: "medium" }).

• Inputs: projectPath, scope, categories (CURRENCY, NUMBER, PERCENTAGE, DATE, TIME), fix (boolean, default: false), dryRun (boolean, default: true).

export_translations

Exports translation catalogs (JSON or Flutter ARB) into standard XLIFF (1.2 / 2.0) or TMX 1.4 exchange files for professional translation agencies and Translation Management Systems (Crowdin, Lokalise, Phrase, Smartling, Trados).

• Inputs: projectPath, format ("xliff-1.2" | "xliff-2.0" | "tmx-1.4"), sourceLocale, targetLocales, namespaces, outputPath, includeNotes (boolean, default true).

import_translations

Imports translated strings from standard XLIFF (1.2 / 2.0) or TMX 1.4 exchange files back into project translation catalogs (JSON or Flutter ARB), with unified diff support and collision safety.

• Inputs: projectPath, filePath, content, format, targetLocales, overwrite (boolean, default true), dryRun (boolean, default false).

deduplicate_i18n

Audits catalogs for exact duplicate keys, fuzzy near-duplicates, and cross-namespace redundancy using normalized Levenshtein similarity, with optional automated key consolidation and source code call-site updates.

• Inputs: projectPath, sourceLocale, similarityThreshold (number 0.5-1.0, default 0.85), exactOnly (boolean), crossNamespaceOnly (boolean), targetNamespace (default "common"), consolidate (boolean, default false), dryRun (boolean, default true), scope.

internationalize

End-to-end orchestration tool combining analysis, scanning, candidate resolution, planning, modification, translation, and validation into a unified workflow.

• Inputs:

  • projectPath (string, optional)

  • scope (string[], optional)

  • dryRun (boolean, optional, default true): Simulates execution and returns a unified diff.

  • apply (boolean, optional, default false): Applies code replacements and locale additions.

  • translate (boolean, optional, default false): Translates missing strings for target locales.

  • provider ("auto" | "deepl" | "openai" | "gemini" | "dictionary", optional): Pluggable cloud translation provider with non-blocking fallback.

  • apiKey (string, optional): API key for cloud translation.

  • providedTranslations (record, optional): Agent-supplied translations for missing or ambiguous terms.

  • candidateDecisions (record, optional): Map of ambiguous candidate IDs to boolean approval.

  • sourceLocale, targetLocales, namespaces, include, exclude, createBackup.

• Returns: Full lifecycle report with status (NO_CHANGES, PLAN_READY, APPLIED, APPLIED_WITH_WARNINGS, REVIEW_REQUIRED, FAILED).

ICU MessageFormat & Plural Parity

• Flutter ARB: Fully supports ICU plural syntax ({count, plural, =0{no items} =1{1 item} other{{count} items}}) with automated @key.placeholders metadata generation (count: { type: "num", format: "compact" }) required by flutter gen-l10n.

• Next.js (next-intl): Generates single-key ICU MessageFormat plural definitions in message catalogs (messages/*.json).

• React / React Native (react-i18next): Automatically produces _one and _other dual key entries for standard i18next runtime resolution.

Layered Architecture

src/
├── mcp/                      # Model Context Protocol layer
│   ├── server.ts             # McpServer instance & stdio lifecycle
│   └── tools/                # 8 registered MCP tools
│       ├── analyze-project.ts
│       ├── scan-hardcoded-texts.ts
│       ├── generate-i18n-plan.ts
│       ├── apply-i18n-plan.ts
│       ├── translate-i18n.ts
│       ├── validate-i18n.ts
│       ├── internationalize.ts
│       └── generate-i18n-types.ts
│
├── core/                     # Framework-independent i18n engine
│   ├── discovery/            # Project & framework detection
│   ├── scanner/              # AST string scanner
│   ├── classifier/           # 4-Pillar classification engine
│   ├── namespace/            # Namespace assignment
│   ├── keys/                 # Semantic key generation
│   ├── translation/          # Contextual translation service
│   ├── replacement/          # Safe source transformation
│   ├── validation/           # Completeness & consistency checks
│   ├── planning/             # Deterministic plan generation
│   └── orchestration/        # End-to-end pipeline coordinator
│
├── integrations/
│   └── adapters/             # Pluggable framework adapters
│       ├── framework-adapter.interface.ts
│       ├── react-native.adapter.ts
│       ├── react-web.adapter.ts
│       ├── nextjs.adapter.ts
│       └── flutter.adapter.ts
│
├── models/                   # Strongly-typed models and contracts
└── utils/                    # Safe file I/O and stderr logger

Antigravity Agent Skill: /internationalize

The project includes an Antigravity Workspace Skill located at .agents/skills/internationalize/SKILL.md (and .claude/skills/internationalize/SKILL.md).

Supported Commands & Invocations

# Preview internationalization across the whole project (dry-run)
/internationalize

# Preview a specific feature directory
/internationalize src/features/auth

# Preview a single screen or component
/internationalize src/features/auth/LoginScreen.tsx

# Apply changes directly
/internationalize src/features/auth --apply

# Apply changes and generate French and Spanish translations
/internationalize src/features/auth --apply --translate --target-locales=fr,es

Two-Stage Interactive Safety Workflow

1. Developer or Agent invokes /internationalize src/features/auth.

2. MCP scans the code and returns PLAN_READY with unified diff and any ambiguous candidates tagged AMBIGUOUS.

3. Agent quickly reviews ambiguous items (e.g. <Button label="Save" /> $\rightarrow$ true) and passes resolutions via candidateDecisions.

4. Developer confirms "apply".

5. Agent executes with apply: true, updating source code, creating locale keys, running translations, and validating results.

Running the MCP Server

Stdio Transport Configuration

Add the server to your MCP client configuration (Claude Desktop, Cursor, Gemini CLI, etc.):

{
  "mcpServers": {
    "react-native-i18n": {
      "command": "node",
      "args": ["<path-to-i18n-mcp>/dist/mcp/server.js"]
    }
  }
}

Development & Verification

# Build TypeScript
npm run build

# Run unit and integration tests (58 test files, 417 tests)
npm test

# Typecheck
npm run typecheck

CLI Usage

For debugging and local development without an MCP client:

# Scan hardcoded strings in current project
npx i18n-mcp scan

# Scan specific project directory
npx i18n-mcp scan ./my-project

# Scan with scope (e.g. specific feature or file)
npx i18n-mcp scan ./my-project --scope src/features/auth

# Export catalogs to standard XLIFF (1.2 / 2.0) or TMX for translation agencies
npx i18n-mcp export ./my-project --format xliff-1.2 --target-locales fr es de --out ./exports

# Import translated XLIFF or TMX files back into catalogs
npx i18n-mcp import ./my-project --file ./exports/en_fr.xlf

# Audit catalogs for exact and fuzzy duplicate keys and consolidate redundancies
npx i18n-mcp dedupe ./my-project --threshold 0.85 --consolidate

# Audit and migrate unlocalized currency, number, percentage, and date formatting
npx i18n-mcp formatting ./my-project --categories CURRENCY NUMBER PERCENTAGE DATE --fix

# Audit and scaffold Unicode CLDR plural categories across catalogs
npx i18n-mcp plurals ./my-project --locales ar ru pl --fix

# Audit RTL layout and auto-fix physical properties to logical
npx i18n-mcp rtl ./my-project --target-locales ar he --fix

# Translate missing keys with context-aware formality
npx i18n-mcp translate ./my-project --target-locales fr es --formality formal --provider openai

# Generate TypeScript type definitions (resources.d.ts)
npx i18n-mcp types ./my-project

# Preview generated types without writing
npx i18n-mcp types ./my-project --dry-run

# Output raw JSON
npx i18n-mcp scan ./my-project --json