What It Validates
The module checks your hand-written kit configuration against the locale table Nuxt actually resolved, during the build, where a problem can fail rather than scroll past. Two checks run, right before the artifact is written.
Keys the Module Derives
locales, localeDirs and defaultLocale are derived from your Nuxt config.
Declaring any of them by hand as well is an error naming the file and the key:
apps/admin/.i18n-mcp.json declares "defaultLocale", which this module derives
from your Nuxt config. Remove it — keeping both means two sources of truth and
no way to tell which won.
Remove the key. Its value now comes from i18n.defaultLocale, i18n.locales
and each layer's resolved locale directory. To narrow or reorder locales, change
the Nuxt config, which is where Nuxt reads them from too.
Both configuration files are checked, not only the JSON one: .i18n-mcp.json
and i18n-kit.config.* are each searched for on their own, walking up from the
app's root directory, so a layered repository with its config at the root and
its apps in subdirectories is covered.
A config file that cannot be read, or one whose default export is not an object, is reported as a warning and skipped — the CLI owns the config schema and reports a malformed config with a better message than this check could.
protectedLocales That Protect Nothing
protectedLocales excludes locales from automatic translation, and a reference
that matches nothing protects nothing. Each entry is resolved against the
published locale table, by code first, then language, then file:
| Result | Level | Message |
|---|---|---|
| Matches no locale | error | "de-DE-formal" matches no locale, so it protects nothing, followed by the available codes — or by No locales resolved from your i18n configuration at all. when the table is empty |
| Matches several locales | error | Names the field it matched on and every candidate code, and asks you to use one of those codes |
Matches one locale, by language or file rather than code | warning | Suggests the code instead: a locale added later with the same language tag would make the reference ambiguous without anyone touching the line that wrote it |
Codes are unique by construction; language tags are not. The CLI resolves locale references with the same precedence, so a reference that passes here resolves the same way at translate time.
Entries from both configuration files are checked together.
failOnInvalidConfig
Errors fail the build by default. The thrown message counts the problems and points at the option:
Your i18n-kit configuration does not agree with your Nuxt config (2 problem(s),
listed above). Set i18nKit.failOnInvalidConfig to false to report without
failing.
export default defineNuxtConfig({
modules: ['@nuxtjs/i18n', '@the-i18n-kit/nuxt'],
i18nKit: {
failOnInvalidConfig: false,
},
})
With it off, every diagnostic is still printed at its own level — errors as errors — and the build continues. Warnings never fail the build either way.
protectedLocales entry that matches nothing looks protected in your config,
protects nothing in practice, and now says so only in build output nobody reads.What It Does Not Check
- Field types and unknown fields. The CLI validates your config against its zod schema and reports those. This module reads the file to see which keys it declares, and validates nothing else.
- Anything outside the app it is installed in. Each app's module instance checks the nearest configuration files above its own root directory.
- Whether the locale files exist on disk. The check is against the table Nuxt resolved. A locale whose file is missing is a question for the CLI, which reads the directories.