vite-plugin-vue-i18n-typescript

Stop shipping broken translations! Get compile-time type safety for your Vue i18n JSON files.

🎮 Live Demo | 📚 Documentation | 🚀 Quick Start

Why This Plugin?

Without it: t('any.random.key') → ❌ Runtime errors your users see

With it: t('any.random.key') → ✅ TypeScript error at compile time

// ❌ TypeScript catches this typo instantly
t('welcom')  // Error: Did you mean 'welcome'?

// ✅ Full IDE autocomplete for all your translation keys
t('nav.home')  // IDE shows all available keys

Features:

• 🔥 True hot reload (no page refresh!)
• Built-in debug dashboards when debug: true
• Zero config needed with smart glob + batching defaults
• ⚡ Only rebuilds what changed and surfaces key conflicts
• 🛠️ Works as Vite plugin, CLI (i18n-typescript), or API

Quick Start

1. Install

npm install vue-i18n
npm install -D vite-plugin-vue-i18n-typescript

2. Add to Vite

/// <reference types="./vite-env-override" />
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import i18nTypes from 'vite-plugin-vue-i18n-typescript'

export default defineConfig({
  plugins: [
    vue(),
    i18nTypes(), // Zero config!
  ],
})

3. Use Type-Safe Translations

Create your locale JSON files in src/locales/:

// src/locales/en.json
{
    "welcome": "Welcome!",
    "nav": {
        "home": "Home"
    }
}

Use in components:

<script setup lang="ts">
import { useI18nTypeSafe } from 'virtual:vue-i18n-types'

const {t} = useI18nTypeSafe()

// TypeScript knows all your keys!
const msg = t('welcome')     // ✅ Autocomplete
const err = t('welcom')      // ❌ TypeScript error
</script>

That's it! Your translations are now type-safe.

Documentation

• 📖 Configuration Guide - All options explained
• 🔨 CLI Usage - For CI/CD and pre-commit hooks
• 🧩 API Reference - For custom build scripts
• 🔄 Migration Guide - From @intlify/unplugin-vue-i18n

Three Ways to Use

1. Vite Plugin (Recommended)

plugins: [i18nTypes()]  // Auto-generates types during dev

2. CLI Tool

# One-time run (no installation needed)
npx vite-plugin-vue-i18n-typescript generate

# After installing as devDependency
i18n-typescript generate

# In package.json scripts
"scripts": {
  "i18n:generate": "i18n-typescript generate"
}

Note: The binary is named i18n-typescript. Use npx vite-plugin-vue-i18n-typescript for ad-hoc runs, or i18n-typescript directly when installed locally.

3. Programmatic API

import {generateI18nTypes} from 'vite-plugin-vue-i18n-typescript/api'

await generateI18nTypes({baseLocale: 'en'})

Virtual Module Imports

The plugin provides virtual modules with everything you need:

Main Module: virtual:vue-i18n-types

import {
  useI18nTypeSafe,           // Type-safe composable
  createI18nInstance,         // Create i18n instance
  createI18nInstancePlugin,   // Create Vue plugin
  availableLocales,          // Array of locale codes
  fallbackLocales,           // Fallback mappings
  messages                   // All translations
} from 'virtual:vue-i18n-types'

// Use in components
const {t} = useI18nTypeSafe()

// Or create a plugin
app.use(createI18nInstancePlugin())

Sub-modules for Tree-shaking

Import only what you need:

// Just the messages
import { messages } from 'virtual:vue-i18n-types/messages'

// Just the available locales
import { availableLocales } from 'virtual:vue-i18n-types/availableLocales'

// Just the fallback chains
import { fallbackLocales } from 'virtual:vue-i18n-types/fallbackLocales'

Debug Dashboards

Enable debug: true in your Vite config and visit:

• /_virtual_locales.json for the merged locale payload
• /__locales_debug__ for metadata (hash, files, fallback map)

Perfect for validating generated data without leaving the browser.

Common Configuration

i18nTypes({
  baseLocale: 'en',                      // Your primary language (defaults to 'de')
  include: ['src/locales/**/*.json'],    // Where to find locale files
  // That's usually all you need!
})

See all configuration options →

Migration from @intlify/unplugin-vue-i18n

Takes 2 minutes:

# 1. Replace package
- npm uninstall @intlify/unplugin-vue-i18n
+ npm install -D vite-plugin-vue-i18n-typescript

# 2. Update vite.config.ts
- import VueI18nPlugin from '@intlify/unplugin-vue-i18n/vite'
+ import i18nTypes from 'vite-plugin-vue-i18n-typescript'

- VueI18nPlugin({ include: './src/locales/**' })
+ i18nTypes()

# 3. Update imports
- import messages from '@intlify/unplugin-vue-i18n/messages'
+ import messages from 'virtual:vue-i18n-types/messages'

Your JSON files work without changes!

Comparison

| Feature | This Plugin | @intlify/unplugin-vue-i18n | |----------------|-----------------------|----------------------------| | Type-safe keys | ✅ Full autocomplete | ⚠️ Limited | | True HMR | ✅ No page reload | ❌ Page reloads | | Setup | ✅ Zero config | ⚠️ Requires configuration | | Performance | ✅ Incremental updates | ⚠️ Full rebuilds |

What's New (v1.2.0)

New Features

• Merge-export CLI - Ship locale snapshots via i18n-typescript merge-export, including per-locale splits.
• Live debug dashboards - Hit /_virtual_locales.json or /__locales_debug__ when debug: true to inspect data.
• Batch tuning - Control large projects with the new fileBatchSize option.
• Automatic conflict alerts - The generator now flags duplicate keys during rebuilds.
• Simplified runtime output - Locale asset emission options were removed; builds now rely exclusively on the virtual module outputs.
• CLI rename - Local installs expose the i18n-typescript binary (use npx vite-plugin-vue-i18n-typescript generate for one-off runs).

FAQ

Default: src/locales/*.json. Change with include option.

Not yet - convert to JSON first.

i18nTypes({
    debug: true,
    virtualFilePath: 'src/debug.gen.ts' // Creates inspectable file
})

Requirements

• Node.js >= 20.19.0 or >= 22.12.0
• Vite >= 4.0.0 or >= 7.0.0
• Vue 3 with vue-i18n

Contributing

See GitHub repo.

License

MIT