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, dev, ui, auto-config, 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.

dev — Start app + editor together

Starts your application's own dev server and the locale editor UI in parallel, in one terminal.

vue-i18n-kit dev
vue-i18n-kit dev --ui-port 4200
vue-i18n-kit dev --app-cmd "nuxt dev"

Flag	Default	Description
--ui-port <number>	4173	Port for the vue-i18n-kit ui server.
--app-cmd <cmd>	auto-detected scripts.dev	Override the app dev command instead of reading package.json.

The app command is auto-detected from package.json's scripts.dev, run with the package manager whose lockfile is present (npm, pnpm, or yarn). I18N_KIT_UI_URL is passed to the app process automatically, so vueI18nDevPlugin picks up the UI URL with no explicit config. Ctrl+C stops both processes together.

ui — Start the locale editor UI

Starts only the locale editor UI server, without your application.

vue-i18n-kit ui
vue-i18n-kit ui --port 4200

Flag	Default	Description
--port <number>	4173	Port to listen on.

auto-config — Non-interactive config sync

Re-discovers locales from your createVueI18nPlugin(...) call and updates vite.config.ts/nuxt.config.ts accordingly — no prompts. Useful in CI or as a postinstall/pre-commit script, unlike init which is interactive.

vue-i18n-kit auto-config

Takes no flags. Reads the createVueI18nPlugin(...) call as the single source of truth for which locales exist, then inserts or updates the vueI18nMapPlugin call in your Vite/Nuxt config so it stays in sync — this is the same step init performs interactively during initial setup.

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