vite-plugin-vue-i18n-types

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!)
• 🎯 Zero config needed
• ⚡ Only rebuilds what changed
• 🛠️ Works as Vite plugin, CLI, or API

Quick Start

1. Install

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

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-types'

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 '@/i18n/i18n.gen'

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

npx vite-plugin-vue-i18n-types generate

3. Programmatic API

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

await generateI18nTypes({baseLocale: 'en'})

Virtual Module Imports

The plugin provides two virtual modules for different use cases:

virtual:vue-i18n-types/messages

Import just the translation messages:

import messages from 'virtual:vue-i18n-types/messages'

// Use with createI18n
const i18n = createI18n({
    locale: 'en',
    messages
})

virtual:vue-i18n-types

Import helper functions for creating i18n instances:

import { createI18nInstancePlugin } from 'virtual:vue-i18n-types'

// Auto-configured plugin
app.use(createI18nInstancePlugin())

Common Configuration

i18nTypes({
    baseLocale: 'en',                      // Your primary language
    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-types

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

- 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 |

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