The Artifact and Options
What Is in the File
{
"version": 1,
"generator": "@the-i18n-kit/nuxt@0.1.4",
"appDir": "/repo/apps/admin",
"defaultLocale": "en",
"fallbackLocale": "en",
"localeFileFormat": "json",
"locales": [
{ "code": "en", "language": "en-US", "file": "en.json", "name": "English" },
{ "code": "de-formal", "language": "de-DE", "file": "de-formal.json" }
],
"layers": [
{ "rootDir": "/repo/apps/admin", "localeDir": "/repo/apps/admin/i18n/locales" },
{ "rootDir": "/repo/layers/dashboard" },
{ "rootDir": "/repo/packages/ui", "localeDir": "/repo/packages/ui/i18n/locales" }
]
}
Three things follow from that shape:
- Locales carry all three reference forms.
code,languageandfileare published per entry, so a locale reference resolves without knowing@nuxtjs/i18n's field names. - Layer order is precedence. The app's own layer first, then what it extends, in the order Nuxt resolved.
- Layers without translations keep their entry. A layer carrying source code and no locale directory is still scanned for key usage.
The file does not carry layer names — the CLI derives those from each rootDir
relative to the directory you point it at — and it carries no kit policy.
What It Validates
Two checks run during the build, where a problem can fail rather than scroll past.
Keys the module derives. locales, localeDirs and defaultLocale declared
by hand are an error naming the file and the key. Both configuration files are
searched for, walking up from the app's root directory. To narrow or reorder
locales, change the Nuxt config.
protectedLocales that protect nothing. Each entry is resolved against the
published locale table, by code, then language, then file:
| Result | Level | Message |
|---|---|---|
| Matches no locale | error | Names the entry and lists the available codes |
| Matches several locales | error | Names the field it matched on and every candidate code |
Matches one, by language or file rather than code | warning | Suggests the code instead |
It does not validate field types or unknown fields — the CLI owns the schema — and it does not check whether locale files exist on disk.
Options
Options go under i18nKit in nuxt.config.ts. That block configures this module
and nothing else.
| Option | Type | Default | Effect |
|---|---|---|---|
enabled | boolean | true | With false, no artifact and no validation. The CLI falls back to adapter detection |
failOnInvalidConfig | boolean | true | With false, problems are printed at their own level and the build continues |
export default defineNuxtConfig({
modules: ['@nuxtjs/i18n', '@the-i18n-kit/nuxt'],
i18nKit: {
failOnInvalidConfig: false,
},
})
failOnInvalidConfig off restores the failure the check was written for:
a protectedLocales entry that matches nothing looks protected in your config,
protects nothing in practice, and now says so only in build output nobody reads.There is no option for the artifact's path. The CLI looks for
<app>/.nuxt/i18n-kit.json without loading your Nuxt config, so a custom
buildDir means the file is not found.
When the CLI Ignores the Artifact
Everything wrong with an artifact is a reason to fall back to loading the app through Nuxt, never an error:
| Situation | What the CLI does |
|---|---|
No .nuxt/i18n-kit.json | Loads the app, with no message — the state of every project that has not built |
| Not valid JSON, or not a shape this CLI understands | Warns with the reason and loads the app |
A nuxt.config it describes is newer than the artifact | Warns, suggests nuxt prepare, and loads the app |
| It describes no locale directories | Warns and loads the app |
Falling back is not free: loading the app needs @nuxt/kit in the project and a
nuxt.config.ts that evaluates in the CLI's environment. When that fails, the
Nuxt adapter reports it.
Two producer-side limits: the module publishes nothing without a resolved
@nuxtjs/i18n locale set, and it publishes JSON locale files only.