Configuration

Base dictionary (extends)

The extends field in i18n-kit.config.json lets a project inherit translations from a shared base — for example, a corporate terminology dictionary maintained centrally in a monorepo or npm package.

// i18n-kit.config.json
{
  "extends": "../../shared-i18n"
}

When the editor reads a locale, base keys are merged underneath project keys — the project always wins. Base-only keys appear in the editor but are not written to project locale files on save.

Typical structure:

monorepo/
├── shared-i18n/
│   ├── en.json     ← base dictionary (company-wide terms)
│   └── ru.json
└── my-app/
    ├── i18n-kit.config.json   ← "extends": "../shared-i18n"
    └── src/locales/
        ├── en.json   ← app-specific overrides
        └── ru.json

Locked keys

The locked field in the base config declares keys that child projects cannot modify.

// shared-i18n/i18n-kit.config.json
{
  "localesDir": "locales",
  "locked": ["brand.name", "brand.tagline", "legal.*"],
}

Layer	Behaviour
Editor UI	Cell is greyed out with a lock icon; tooltip "Key locked by base dictionary"
PUT /api/locale/:code	Server returns 403 if a locked key value changes
merge --overwrite	Locked keys are skipped even with --overwrite
prune	Locked keys are never removed

Locked key patterns support globs: "legal.*" (all keys under legal), "brand.name" (exact), "**" (everything).

Validation rules (rules)

The rules section in i18n-kit.config.json configures the locale editor's validation behaviour. All fields are optional.

// i18n-kit.config.json
{
  "rules": {
    "interpolationPatterns": ["{var}", "{{var}}"],
    "lengthWarningFactor": 3,
    "warnOnHtmlTags": true,
    "warnOnIcuErrors": true,
    "warnOnDuplicateValues": true,
    "minValueLength": 0,
  },
}

Field	Default	Description
interpolationPatterns	["{var}"]	What counts as an interpolation variable. Also supports "{{var}}", ":param", "%(var)s".
lengthWarningFactor	2.5	Warn if value.length > ref.length × factor. Set to 0 to disable.
warnOnHtmlTags	true	Warn when values contain HTML tags.
warnOnIcuErrors	true	Warn on malformed ICU (unclosed braces, missing other{}).
warnOnDuplicateValues	true	Warn if a key has identical values across all locales.
minValueLength	0	Warn if value is shorter than this many characters (0 = off).

The same rules object can be passed to vueI18nCheckPlugin.

Ignore lists (ignore)

The ignore section lets you whitelist keys and paths that would otherwise trigger warnings or be removed by CLI tools.

// i18n-kit.config.json
{
  "ignore": {
    "prune": ["status.*", "dynamic.*"],
    "duplicates": ["brand.name", "app.version"],
    "unused": ["seo.*", "meta.*"],
    "scanExclude": ["src/tests/**", "scripts/**"],
  },
}

All patterns support glob syntax: * matches any single segment, ** matches any number of path segments.

ignore.prune patterns are also respected by the prune --dry preview.

Namespace mode (namespaces)

boolean · default: false. Enables namespace mode: treat top-level JSON keys as namespaces.

// i18n-kit.config.json
{
  "namespaces": true,
}

• CLI — enables vue-i18n-kit split / vue-i18n-kit merge-ns (see CLI — Scaffolding & Codegen).
• Editor — shows a namespace filter bar above the key table.
• Vite plugin — see Namespace Code Splitting for the runtime lazy-loading mechanism this pairs with.

Stale tracking (staleTracking)

boolean · default: false. Tracks when reference-locale values change so other locales can be flagged as "needs review." See Stale translation detection for the full mechanism — hashes are stored in i18n-kit.notes.json.

// i18n-kit.config.json
{
  "staleTracking": true,
}

Machine translation (translation)

Settings for the editor's auto-translate feature — engine selection and per-engine options. API keys are stored in the editor UI (localStorage), not in this file, for security. See Machine translation for how the two engines and placeholder handling work.

// i18n-kit.config.json
{
  "translation": {
    "engine": "deepl",
    "deepl": {
      "formality": "more",
    },
    "libretranslate": {
      "apiUrl": "https://libretranslate.com",
    },
  },
}

• translation.engine — 'libretranslate' | 'deepl' · default: 'libretranslate'.
• translation.deepl.formality — 'default' | 'more' | 'less' | 'prefer_more' | 'prefer_less' · default: 'default'. Only supported by some target languages (DE, FR, IT, ES, NL, PL, PT, JA, RU).
• translation.libretranslate.apiUrl — string, optional. LibreTranslate instance URL, for self-hosted deployments.

Translation memory (memory)

// i18n-kit.config.json
{
  "memory": {
    "enabled": true,
  },
}

• memory.enabled — boolean · default: true. Set to false to disable translation memory entirely. When enabled, past translations are stored in i18n-kit.memory.json and suggested as one-click chips when editing similar source strings in the editor.

Source scanning (scanner)

// i18n-kit.config.json
{
  "scanner": {
    "include": ["src/**/*.{vue,ts,tsx}"],
    "exclude": ["src/tests/**"],
  },
}

• scanner.include — string[]. Glob patterns for scanning t()/tm()/$t() key usage across source files — powers unused/phantom key detection and the editor's usage map.
• scanner.exclude — string[]. Glob patterns excluded from the scan. ignore.scanExclude (above) is merged into this list.
• scanner.lastScan — string, written automatically after each scan. Not meant to be hand-edited.

Auto-managed fields

The following top-level fields are written by vue-i18n-kit init/auto-config/the editor itself, not meant for manual editing — listed here so they aren't a mystery when you open a generated i18n-kit.config.json:

• version — config schema version (currently 1).
• localesDir — directory containing locale JSON files, relative to project root.
• toolkitDir — directory for generated toolkit files (locale map, entries map), relative to project root.
• locales — array of { code, path, meta, createdAt, updatedAt } entries, one per registered locale — the editor's own record of each locale file, distinct from the runtime plugin's locales option in Plugin Setup.
• integrations — { viteConfigPath?, nuxtConfigPath?, pluginAdded, lastUpdated }. Tracks whether vueI18nMapPlugin was already inserted into your Vite/Nuxt config, so init/auto-config don't insert it twice.