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", "vue", "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. |
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. Keys are locale codes (e.g., 'de-DE', 'en-US', 'de-DE-formal'), values describe register, regional conventions, or other locale-specific guidance. |
examples | object[] | — | Either config file | Few-shot translation examples that demonstrate the project's style. The agent uses these as reference when generating translations. |
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. |
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, remove_orphan_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" | — | Either config file | Override the auto-detected locale file format. Useful when both formats exist or auto-detection picks wrong. |
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. Not supported by the "google" provider, which rejects it rather than ignoring it. |
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.
orphanScan
Each entry is an object:
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
ignorePatterns | string[] | no | — | Glob patterns for translation keys to exclude from orphan detection (e.g., "common.datetime.months.*"). Use * to match a single key segment, ** to match any depth. |
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. |
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. |