# Reported issues for nuxt-i18n-mcp

Pod holds 23 of 143 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [nuxt-i18n-mcp](/mcp/nuxt-i18n-mcp).

## Most discussed

### Idea: layer-aware ESLint integration for monorepos (evaluate upstreaming to @intlify first)

Idea / not scheduled. Captured from the anny-ui lint evaluation (2026-08-11, MR anny-ui!2025).

## Problem

`@intlify/eslint-plugin-vue-i18n` models one flat message catalog per locale. In layered monorepos (Nuxt layers, multi-app setups) that model breaks:

- `no-duplicate-keys-in-locale` reports the layer architecture itself as duplicates (measured: **2,620 warnings** on anny-ui — override relationships are indistinguishable from mistakes).
- `no-missing-keys` only works with union semantics (

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/289) · 2026-08-11 · closed · 4 comments

### Spec: AST-only scanning — flip the JS/TS/Vue default, add the PHP/Blade frontend, evacuate PHP from the core

Completes the migration #332 specifies. Phase gates were measured on real corpora before this was written; the numbers are in Further Notes.

## Problem Statement

The scanner that decides which translation keys are alive — and therefore which ones `remove-orphans` may delete — has two answers to that question. The AST frontend answers by resolving what a name is bound to; the regex path answers by pattern-matching text, with heuristics whose failure modes are deleting a used key (#298) or prote

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/399) · 2026-08-22 · open · 3 comments

### Spec: adopt MCP 2026-07-28 once the TypeScript SDK ships it

**Activation trigger**: a `@modelcontextprotocol/sdk` release with `LATEST_PROTOCOL_VERSION = '2026-07-28'` (check: `npm view @modelcontextprotocol/sdk version` + the `types.js` constant). Until then this spec is **blocked — do not start**. Re-check in a few weeks; the revision is currently a draft.

## Problem Statement

MCP 2026-07-28 ([changelog](https://modelcontextprotocol.io/specification/2026-07-28/changelog), [Claude announcement](https://claude.com/blog/bringing-mcp-2026-07-28-to-claude

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/218) · 2026-08-09 · closed · 3 comments

### Layer logic: unify duplicated claim/ownership glue (has a silent-drop bug), add layer graph + find_duplicate_keys

From the 2026-08-09 layer-logic analysis, triggered by a real anny-ui finding: 14 keys duplicated between root and app-shop's layer (`pages.account.settings.businessAccount.*`), **8 with divergent German source text** — an incomplete root→app migration that no current kit tool can detect.

## Findings

1. **The alias/ownership claim logic is implemented twice and has silently diverged** (`adapters/nuxt/index.ts` ~147-176 in `loadAndMergeApps` vs ~349-381 in `discoverLocaleDirs`): different takeo

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/202) · 2026-08-09 · closed · 3 comments

### Spec: replace MCP sampling with direct provider calls + agent fallback

MCP sampling is deprecated as of protocol 2026-07-28 (SEP-2577). This spec removes it entirely and replaces it with two first-class translation modes. Synthesized from the 2026-08-08 assessment and a field report from an agent using the MCP in Claude Code.

## Problem Statement

The kit's headline feature — auto-translating missing keys — depends on MCP sampling, which is deprecated and was never supported by major hosts anyway (Claude Code among them). In such hosts, `translate_missing` reports

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/198) · 2026-08-08 · closed · 3 comments

### Generate the configuration reference from the shared schema

## Parent
#300

## What to build
The full configuration reference, generated from the shared zod schema.

Since #328 there are two hand-written config formats — the typed `i18n-kit.config.ts` and the older JSON file — plus policy declarable in `nuxt.config.ts`. The reference documents every field once and states which files it can be declared in.

## Acceptance criteria
- [ ] Every config field is documented with its type, constraints and description
- [ ] Both hand-written config file formats a

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/350) · 2026-08-16 · closed · 2 comments

### ci: reference pipelines gate on exit codes instead of jq arithmetic

## Parent
#246

## What to build

Move the shipped reference pipelines off `jq` arithmetic and onto exit codes.

Both the GitHub Action and the two GitLab job templates currently decide success by reading JSON fields out of command output. That coupling to undocumented output shapes is the root cause of the anny-ui pipeline breakage — the templates read `.summary.totalOrphans` when the field is `.summary.orphanCount`, and treated `orphanKeys` as an array when it is an object keyed by layer. Thos

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/254) · 2026-08-10 · closed · 2 comments

### mcp: expose findEmptyTranslations as a tool (the CLI commands are restored)

## Parent
#246

## What to build
Make the whole command surface reachable and discoverable.

Correction to the parent spec, found while ticketing: `detect`, `list-dirs`, `empty` and `scan` are not merely hidden from `--help`. The CLI entry point filters them out of the subcommand map before it is handed to citty, so they are absent from the executed command map too — `the-i18n-cli scan` fails today. This is a restore, not an unhide. (#195 makes the same observation.)

Then close the MCP gap: `di

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/252) · 2026-08-10 · closed · 2 comments

## Most recent

### Spec: @the-i18n-kit/eslint-plugin — contract rules and layer-aware scope rules, one plugin

Single spec for the ESLint plugin and all its rules. Folds in and supersedes #289 (layer-aware validation; the upstream-intlify evaluation is closed out below) and #421 (authoring rules). #420 motivates one rule. Measurement context: the anny-ui lint evaluation (2,620 false duplicate warnings from flat-catalog tooling) and the 2026-08-24 wire-driven-keys audit.

## Problem Statement

Two classes of i18n mistakes surface only after they are expensive:

1. **Authoring idioms that defeat the scanne

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/422) · 2026-08-24 · closed · 1 comment

### @the-i18n-kit/eslint-plugin: authoring rules that keep the scanner sound

## Parent

#289 tracks the *catalog-validation* side of ESLint integration (layer-aware `no-missing-keys` etc., upstream-intlify evaluation first) — that stays open and unchanged. This ticket is the other half: authoring-idiom rules that keep the scanner sound, which no upstream can provide because they enforce this kit's contract. #420 motivates the second rule.

Note: #289 described a repo-local `no-variable-prefix-i18n-keys` rule in anny-ui. The audit found it was never actually implemented —

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/421) · 2026-08-24 · closed · 1 comment

### Evacuate PHP from the core: reader and patterns behind the optional-peer seam

## Parent

#399 (Spec: AST-only scanning) — Phase 3.

## What to build

A JavaScript-project install carries no PHP, in code or dependencies. The PHP locale-file reader moves from hard dependency to optional peer behind the same project-root dynamic-import seam the parser uses, joining the single "Laravel projects install these" story. The Laravel pattern set and the PHP bare-candidate shape move into the PHP frontend directory. The missing-dependency error for a `php-array` project names exactl

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/406) · 2026-08-22 · closed · 1 comment

### Flip the PHP default — the bookings-api gate, and the contract trial

## Parent

#399 (Spec: AST-only scanning) — Phase 2 gate.

## What to build

The PHP frontend becomes the default for `php-array` projects, gated the same way the JS flip was: evidence over a real corpus, not the technique's appeal. Extend the differential harness to run the Laravel pattern set, run it over the bookings-api corpus (~4,240 PHP files, 45 Blade templates, 30+ locales including a formal/informal pair sharing a language tag), and diff the operations — check, status, missing, dry-run 

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/405) · 2026-08-22 · closed · 0 comments

### Blade lifting: directives and echoes parsed as the PHP they wrap

## Parent

#399 (Spec: AST-only scanning) — Phase 2.

## What to build

Blade templates understood as the PHP expressions they wrap: `@lang(…)`, `@choice(…)` and `{{ __(…) }}` lifted lexically out of the template and handed to the PHP parser, flowing through the same rules as every other call site. The lifting regex frames text only — it never decides what a key is. A Blade construct the lifter does not recognise degrades to the pattern fallback for that file, never to silence.

## Acceptance cr

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/404) · 2026-08-22 · closed · 0 comments

### PHP frontend: helpers, interpolation and concat as syntax, php-parser as optional peer

## Parent

#399 (Spec: AST-only scanning) — Phase 2.

## What to build

A PHP language frontend, opt-in and parallel to the JS flip: Laravel translation helpers (`__`, `trans`, `trans_choice`, `Lang::get`) recognised as syntax, double-quoted `"prefix.{$var}"` interpolation reported as a template argument, `.`-concatenation as a concat argument — the same call-site shapes every frontend emits, interpreted by the same rules. PHP-specific pressure on the contract (choice-call count arguments, Larav

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/403) · 2026-08-22 · closed · 0 comments

### Flip the JS/TS/Vue default to AST, delete the superseded heuristics — anny-ui gate

## Parent

#399 (Spec: AST-only scanning) — Phase 1.

## What to build

The AST frontend becomes the default scanner for JS/TS/Vue, with the pattern frontend running only for files the parser declines. In the same change, the heuristics the AST supersedes are deleted — the callee dot requirement, the textual const table and its substitution, static promotion of slotless dynamic matches — together with the test expectations that encoded their artifacts (the concat-prefix pseudo-key). Two mechanis

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/402) · 2026-08-22 · closed · 0 comments

### Write the translation modes concept page

Split out of #358.

## Why separately

#358 bundled orphan detection and translation modes into one ticket, and they do not share a blocker:

- Orphan detection is blocked by #332, whose implementation (#345) is in flight and **rewrites the subject** — writing that page now means writing it twice.
- Translation modes was blocked by #261, which is **an open spec with no implementation**. It describes behaviour that ships today.

So translation modes was held back by the grouping rather than by an

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/395) · 2026-08-22 · closed · 0 comments

### docs + schema: the config surface still describes nuxt.config.ts policy that #372 removed

## Problem

#372 made the config file the only place policy lives. `ModuleOptions` in `@the-i18n-kit/nuxt` is now exactly `enabled` and `failOnInvalidConfig`; the artifact carries no policy; nothing reads policy out of an `i18nKit` block.

**Three declaration sites became two, and several places still say three.** Two of them are user-facing.

## The published JSON Schema — fix this one first

`documentMeta.description` in `packages/cli/src/config/schema-json.ts` reads:

> Declare it as `.i18n-m

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/380) · 2026-08-17 · closed · 0 comments

### cli: export hiddenCommands so tooling need not regex-parse cli.ts

## Context

`packages/cli/src/cli.ts` filters a module-private `hiddenCommands` set out of the registry before handing it to citty, so those names cannot be invoked at all. That is deliberate — `discover` covers `detect` and `list-dirs`, `find_empty_translations` covers `empty` — and #307 was the bug where `scan` got filtered by mistake and became a documented-but-unreachable command.

## Problem

The set is the only source of truth for which commands are user-facing, and it is not exported. The

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/370) · 2026-08-17 · closed · 0 comments

### check: findings exit 1 as a failed run, not 2 as a tripped gate

## Problem

The CLI has three exit codes, and the distinction between two of them is the whole point:

| Code | Means |
|---|---|
| 0 | Succeeded, no gate tripped |
| 1 | The run itself failed — bad API key, unreadable project |
| 2 | The run succeeded and a requested gate tripped — findings exist, the tool worked |

`check` does not honour it. Its `failWhen` routes through `runFailed` in `resolveExitCode`, so an undefined-key finding is reported as a *failed run*:

```
$ the-i18n-cli check --pr

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/369) · 2026-08-17 · closed · 0 comments

### config: examples entries without a key send "undefined" into the translation prompt

## Problem

`examples` is typed as `z.record(z.string(), z.string())` — a bare string map, requiring nothing. But the consumer treats `key` as mandatory:

```
return `- ${ex.key}: ${pairs}${note}`
```

An example entry without a `key` therefore renders as `- undefined: en: "…", de: "…"` and is sent to the provider as a style example. No validation error, no warning; the model is just handed the word `undefined` as a translation key to imitate.

`note` is genuinely optional and handled — `key` is

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/367) · 2026-08-17 · closed · 0 comments

### typed config: the self-alias and its error message only know the unscoped specifier

## Problem

`selfAlias()` in the typed-config loader resolves exactly one specifier:

```
{ 'the-i18n-cli/config': path }
```

That alias exists so a config file written against the docs works under `npx` in a project that never installed the package — the rescue path called out in #328.

Since the rename shipped (#315, #336), the documented package name is `@the-i18n-kit/cli`. A user following current docs writes:

```ts
import { defineI18nKitConfig } from '@the-i18n-kit/cli/config'
```

The al

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/361) · 2026-08-16 · closed · 0 comments

### Write the orphan detection concept page

## Parent
#300

## What to build
The two concept pages whose subject matter is actively changing, deliberately sequenced last among the prose.

**Orphan detection** — what evidence the scanner recognises, how findings are classified, and which classes are never removed. Its known blind spots matter more than its capabilities: the families it cannot see are exactly the ones a user must declare before trusting a cleanup. This is currently the deepest prose in the repository and it describes a scan

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/358) · 2026-08-16 · open · 1 comment

### Write the Getting Started paths and the home page

## Parent
#300

## What to build
The front door: the home page and the two on-ramps behind it.

This ticket supersedes #255, whose acceptance criteria are carried over here. The cold-start narrative it describes is the same content, retargeted from the README to the site, where it can be followed without assembling it from scattered flag tables.

**The agent on-ramp** takes a reader from nothing to a working MCP server, with configuration for each major host, and hands off to the tools reference

[Read the thread](https://github.com/fabkho/the-i18n-kit/issues/357) · 2026-08-16 · open · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/fabkho/nuxt-i18n-mcp/issues).