Configuration Fields
Generated from the zod schema in @the-i18n-kit/cli that validates your config, so it cannot list a field the tool rejects or omit one it accepts.
Where These Fields May Be Declared
Two files carry these fields and both validate against this same schema: i18n-kit.config.ts, or another accepted extension, and .i18n-mcp.json. Unless the Declared in column below says otherwise, a field may be declared in either.
The i18nKit block in nuxt.config.ts is not a third place for them. @the-i18n-kit/nuxt accepts its own module options there — enabled, failOnInvalidConfig — and reads no field on this page from it. The CLI reads what that module publishes from a build artifact, so a field declared beside your Nuxt config applied to nothing until something had been built, and a pipeline that installs the CLI and runs it against a checkout never builds.
| Restriction | Applies to | Means |
|---|---|---|
.i18n-mcp.json only | $schema, samplingPreferences | The schema accepts the key at runtime and the typed config's ProjectConfig interface leaves it out, so declaring it in i18n-kit.config.ts is a type error in your editor. |
Either file; rejected by @the-i18n-kit/nuxt | locales, localeDirs, defaultLocale | Either file accepts the key, and in a Nuxt project running @the-i18n-kit/nuxt it fails the build: Nuxt resolves these itself, and a hand-written second copy is a source of truth with no tiebreak. |
Fields
Every field is optional. The schema is strict, so a key it does not declare fails validation rather than being ignored — a misspelled field stops the command that read it.
A field marked deprecated still validates, so a config that has one keeps loading. Every loader strips it after validation and warns, naming the file it came from, so the value is accepted and then means nothing.
| Field | Type | Constraints | Declared in | Description |
|---|---|---|---|---|
$schema | string | — | .i18n-mcp.json only | Path or URL to the JSON schema for IDE autocompletion. |
framework | string | suggested: "nuxt", "laravel", "generic", "react" | Either config file | Force framework detection instead of auto-detecting from project structure. Any registered adapter name is accepted — the suggestions are the adapters that ship today, not the only permitted values. 'vue' is accepted as an alias for 'generic', which resolves Vue projects: declare localeDirs when the locale files are not in a conventional directory. |
context | string | — | Either config file | Free-form project background for the agent — business domain, user base, brand voice, anything that helps the agent understand the project. |
layerRules | object[] | — | Either config file | Rules that help the agent decide which layer a new translation key belongs to. The agent interprets the natural-language 'when' field. |
glossary | Record<string, string> | — | Either config file | Term dictionary for consistent translations. Keys are source terms, values describe the required translation or usage note. |
translationPrompt | string | — | Either config file | System prompt prepended to all translation requests (provider mode and agent-mode fallback contexts). Sets tone, style, and constraints. |
localeNotes | Record<string, string> | — | Either config file | Per-locale context included in translation prompts. Each key is matched against a locale's code, language tag, or file name (with or without extension) — whichever the project uses, e.g. 'de', 'de-DE' or 'de-DE.json'. Values describe register, regional conventions, or other locale-specific guidance. A key that matches no locale is reported and ignored. |
examples | object[] | — | Either config file | Few-shot translation examples that demonstrate the project's style. The agent uses these as reference when generating translations. |
declaredNamespaces | object[] | — | Either config file | Namespaces whose keys exist by contract rather than by a call site — sent by a backend, keyed by runtime data, built from a registry. Their keys are never reported as orphans and never written by check --write, in every layer. Each declaration is reported with the keys it matches, so one that matches nothing is visible as stale. |
orphanScan | Record<string, object> | — | Either config file | Per-layer configuration for orphan key detection. Map each layer name to its settings. Scan directories are automatically determined from each layer's root directory. |
localeDirs | (string | object)[] | — | Either file; rejected by @the-i18n-kit/nuxt | Locale directories for the generic adapter. Each entry is a path string (layer defaults to 'default') or an object with 'path' and 'layer' properties. |
defaultLocale | string | minimum length 1 | Either file; rejected by @the-i18n-kit/nuxt | Default locale code. Required for generic adapter activation. |
apps | object[] | — | Either config file | Which app consumes which layers — the consumer graph behind app-scoped orphan detection, misplaced-usage reports and unconsumed-layer warnings. Declaring it overrides both framework discovery and workspace inference. |
consumerGraph | "auto" | "off" | — | Either config file | Whether to infer the consumer graph from the package manager workspace and package.json dependencies when the framework provides no app information: 'auto' (default) infers it, 'off' keeps every layer in one app. |
locales | string[] | each entry: minimum length 1 | Either file; rejected by @the-i18n-kit/nuxt | Explicit list of locale codes to operate on. If absent, locales are auto-discovered from files on disk. |
protectedLocales | string[] | each entry: minimum length 1 | Either config file | Human-maintained locales excluded from automatic translation. Entries may be any locale ref (code, language tag, or file name); entries that do not match a known locale are ignored with a warning. Explicitly naming a protected locale in targetLocales overrides the protection (with a warning). |
reportOutput | true | string | — | Either config file | Enable file output for diagnostic tools (get_missing_translations, search_translations, find_orphan_keys, find_undefined_keys). When set, each tool writes its full JSON report to <reportOutput>/<toolName>.json and returns only a summary in the MCP response. Set to true for the default '.i18n-reports/' directory, or a string for a custom path. |
localeFileFormat | "json" | "php-array" | "yaml" | — | Either config file | Override the auto-detected locale file format. 'yaml' covers both .yaml and .yml files. Useful when several formats exist in one project or auto-detection picks wrong. |
translationMemory | boolean | — | Either config file | Write a translation memory to '.i18n-kit.lock.json' at the project root, recording per layer, key and target locale a hash of the source text each translation was made from, so later runs can tell targets that are still current from ones whose source has changed since. On by default: the first translate run writes the file, which belongs in version control like any other lockfile. Set to false to disable it — nothing is then read or written, and an existing file is left untouched. |
providerBaseUrl | string | minimum length 1 | Either config file | Base URL for the LLM provider — gateways, self-hosted model servers and corporate proxies that speak the provider's own protocol. Overrides the endpoint only, not the request shape or auth header. Overridden by the I18N_BASE_URL environment variable and by --baseUrl. |
samplingPreferences (deprecated) | unknown | — | .i18n-mcp.json only | Deprecated and ignored — MCP sampling was removed. Still accepted so existing config files keep validating. Configure a provider instead (e.g., I18N_PROVIDER/I18N_MODEL). |
Nested Shapes
These fields take a structure rather than a single value. The tables state what the structure holds; the descriptions are the schema's own.
layerRules
Each entry is an object:
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
layer | string | yes | — | Layer name (e.g., 'root', 'app-admin', 'app-shop', 'lang'). |
description | string | yes | — | What this layer contains — key namespaces, domain scope, etc. |
when | string | yes | — | Natural-language rule describing when a key should go in this layer. |
examples
Each entry: A single translation example. 'key' holds the dot-path translation key (e.g., 'common.actions.save'), 'note' an optional style comment, and every other property is a locale code (e.g., 'de-DE', 'en-US') mapped to its translated value.
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
key | string | yes | — | The dot-path translation key this example demonstrates (e.g., 'common.actions.save'). |
note | string | no | — | Optional style comment shown alongside the example. |
Properties beyond these are accepted rather than rejected, so a key from an older version of the kit does not fail your config. Anything the current schema does not list is ignored.
declaredNamespaces
Each entry is an object:
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
pattern | string | yes | minimum length 1 | Key pattern the declaration covers (e.g., "views.defaults.**"). Use * to match a single key segment, ** to match any depth. |
reason | string | yes | minimum length 1 | What keeps these keys alive, named so the report can say why they are protected (e.g., "sent by bookings-api as name_key"). |
orphanScan
Each entry is an object:
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
ignorePatterns | string[] | no | — | Glob patterns for translation keys to exclude from orphan detection in this layer (e.g., "common.datetime.months.*"). Use * to match a single key segment, ** to match any depth. For keys that exist by contract elsewhere, declare them under declaredNamespaces instead, which records why and reports what each pattern protects. |
Properties beyond these are accepted rather than rejected, so a key from an older version of the kit does not fail your config. Anything the current schema does not list is ignored.
localeDirs
Each entry takes one of these forms:
| Type | Constraints | Description |
|---|---|---|
string | minimum length 1 | Relative path to a locale directory. Layer name defaults to 'default'. |
object | — | — |
The object form holds:
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
path | string | yes | minimum length 1 | Relative path to a locale directory. |
layer | string | yes | minimum length 1 | Layer name for this locale directory. |
apps
Each entry is an object:
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
name | string | yes | minimum length 1 | App name, as it appears in orphan and status reports (e.g., 'shop', '@acme/admin'). |
layers | string[] | yes | each entry: minimum length 1 | Layer names this app can render — its own layer plus every shared layer it consumes. |
reportOutput
The value takes one of these forms:
| Type | Constraints | Description |
|---|---|---|
true | — | Set to true to write reports to the default '.i18n-reports/' directory. |
string | minimum length 1 | Custom directory path (relative to project root) where diagnostic tool reports are written. |