Where Configuration Lives

Kit policy — what you tell the tool because it cannot see it for itself — goes in one of two files, both read straight from disk. Every field either accepts is in the field reference.

i18n-kit.config.ts

A TypeScript file with the config as its default export:

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

export default defineI18nKitConfig({
  context: 'A B2B booking platform.',
  glossary: { anny: 'Brand name. NEVER translate.' },
  protectedLocales: ['de-formal'],
})

defineI18nKitConfig returns its argument unchanged; its job is the type, so a misspelled protectedLocals is a red squiggle rather than a failed command. Import @the-i18n-kit/cli/config — the CLI aliases that specifier to the copy already running, so a config written against these docs loads under a bare npx in a project that never installed the package.

.mts, .js, .mjs, .cjs and .cts work too. With more than one in a directory the CLI uses the first in that order and warns, naming the rest.

.i18n-mcp.json

The same field names plus a $schema pointer for editor completion. This is what the-i18n-cli init writes:

{
  "$schema": "node_modules/@the-i18n-kit/mcp/schema.json",
  "context": "A B2B booking platform.",
  "protectedLocales": ["de-formal"]
}

How Each Is Found

Both are searched for from the project directory upward — the way ESLint and tsconfig.json resolve theirs — and the search stops at the first directory that has one. A config in an app directory shadows one at the repository root outright rather than merging with it, and there is no extends.

Because they are read from disk rather than from a build, their policy applies to the first command run in a checkout that has built nothing: a CI job that runs the kit before the build, or a container with only the repository mounted. That matters most for the keys that suppress work — protectedLocales, which excludes locales from automatic translation, and orphanScan and declaredNamespaces, which narrow what counts as an orphan key.

Choosing

Start with i18n-kit.config.ts: it is checked by your editor, needs no build, and works on every framework the kit supports. Keep .i18n-mcp.json if you already have one, or if something other than a person generates it.

You may use both. What you cannot do is declare the same key in each — that is an error naming both files, not a merge. See precedence.

Provider credentials are the one setting that never comes from either file: an API key comes from --apiKey or a provider environment variable, so it cannot be committed by accident.