CLI — Scaffolding & Codegen

The vue-i18n-kit CLI helps scaffold and audit locale JSON files.

# Via npx (no install needed)
npx vue-i18n-kit <command> [options]

# Or after installing the package
vue-i18n-kit <command> [options]

This page covers the scaffolding and generation commands — init, add, merge, types, split, merge-ns. For the audit and reporting commands (check, prune, stale, export, import, stats), see CLI — Audit & Reports.

init — Interactive setup wizard

Launches an interactive wizard that scaffolds the entire localization setup.

vue-i18n-kit init

What it does:

1. Auto-scans the project for an existing createVueI18nPlugin call and pre-fills locale codes as defaults.
2. Prompts for locale codes, display names, and flag emojis.
3. Prompts for the locales directory and toolkit directory paths.
4. Detects vite.config.ts / nuxt.config.ts and optionally adds vueI18nMapPlugin automatically.
5. Handles existing locale JSON files — keep, overwrite, or copy structure from another locale.
6. Writes i18n-kit.config.json, i18n-tools/locales.config.json, locale JSON stubs.

Running vue-i18n-kit init on an existing project offers three choices: use the current config as-is, update settings, or reinitialize from scratch.

i18n Ally integration — the wizard optionally generates .vscode/settings.json for i18n Ally with inline translation previews and missing-key highlighting.

add — Add a new locale

Copies the structure of an existing locale file into a new one.

vue-i18n-kit add fr
vue-i18n-kit add fr --from en --empty
vue-i18n-kit add de --dir src/i18n --from en --empty

Flag	Default	Description
--dir <path>	src/locales	Locales directory.
--from <locale>	first file in dir	Source locale to copy structure from.
--empty	false	Write empty strings instead of copying source values.

merge — Merge a shared dictionary

Deep-merges a base or corporate JSON dictionary into project locale files. Only adds missing keys by default — existing translations are left untouched unless --overwrite is passed.

vue-i18n-kit merge shared/base.json --dry
vue-i18n-kit merge shared/base.json
vue-i18n-kit merge updates.json --locale ru --overwrite

Flag	Default	Description
--dir <path>	src/locales	Locales directory.
--locale <code>	all locales	Only merge into this locale code.
--overwrite	false	Overwrite existing keys instead of skipping them.
--dry	false	Preview changes without writing any files.
--no-sort	false	Skip alphabetical sort of result keys.

Keys listed in ignore.prune and locked in i18n-kit.config.json are never overwritten — even with --overwrite.

types — Generate TypeScript types

Generates a TranslationKey union type from a reference locale file. Gives you autocomplete and compile-time key checking when calling t().

vue-i18n-kit types
vue-i18n-kit types --out src/types/i18n.d.ts --locale en --watch

Flag	Default	Description
--out <path>	src/i18n.d.ts	Output file path.
--locale <code>	first in config	Locale to use as the key source.
--dir <path>	src/locales	Locales directory.
--watch	false	Regenerate automatically when the locale file changes.

Generated file example:

// src/i18n.d.ts — generated by vue-i18n-kit, do not edit

export type TranslationKey = 'buttons.cancel' | 'buttons.submit' | 'greeting' | 'items'

declare module 'vue-i18n-kit' {
  interface Register {
    key: TranslationKey
  }
}

With the Register augmentation the compiler will error on unknown keys:

const { t } = useT()
t('buttons.submit') // ✓
t('buttons.submitt') // ✗ TypeScript error

split — Split a monolithic locale into namespaces

Splits each {locale}.json into per-namespace files: {locale}/{namespace}.json.

vue-i18n-kit split
vue-i18n-kit split --dir src/locales --out src/locales/split --dry

Flag	Default	Description
--dir <path>	localesDir from config	Source locales directory.
--out <path>	<dir>/split	Output directory.
--dry	false	Preview without writing files.

merge-ns — Merge namespace files back into flat JSON

Reverse operation of split: reads all *.json files in each locale subdirectory and merges them into a single {locale}.json.

vue-i18n-kit merge-ns
vue-i18n-kit merge-ns --dir src/locales/split --out src/locales --dry