vite-i18n-by-design

1.1.3 verified Mon Apr 27 auth: no javascript

A Vite plugin that automatically loads and merges Vue I18n messages from a structured locales/<lang>/<namespace> folder, supporting JSON, YAML, and YML files with full HMR and TypeScript types. Current stable version 1.1.3. Maintained as needed. Key differentiator: zero-config virtual module 'virtual:i18n-messages' that integrates directly with vue-i18n and provides type safety. Recommended over static message loading for development due to HMR support.

Common errors

error Cannot find module 'virtual:i18n-messages' or its corresponding type declarations. ↓

cause TypeScript does not recognize the virtual module by default.

fix

Add the provided .d.ts file to your tsconfig include array, or use a path mapping.

error Error: Cannot find module 'yaml' ↓

cause YAML dependency not installed when using YAML files.

fix

Install yaml: npm install yaml

error TypeError: Messages must be an object or a function that returns an object. ↓

cause Invalid message structure after merging; likely nested incorrectly.

fix

Ensure each locale folder contains namespace files (e.g., locales/en/app.json), not direct message files.

Warnings

deprecated TypeScript declarations for virtual:i18n-messages require manual inclusion in tsconfig if auto-resolution fails. ↓

fix Add 'node_modules/vite-i18n-by-design/dist/virtual-i18n-messages.d.ts' to the include array in tsconfig.app.json.

gotcha Virtual module 'virtual:i18n-messages' is not available in Node.js scripts (SSR, testing without Vite). ↓

fix Use the named export 'loadMessages' from the package for Node.js usage.

gotcha YAML files require the 'yaml' package to be installed; missing it causes runtime errors. ↓

fix Run 'npm install yaml' as a project dependency.

gotcha Folder structure must be locales/<lang>/<namespace>.* without extra nesting; deeper structures are not supported. ↓

fix Flatten your locale files to the specified pattern.

Install

npm install vite-i18n-by-design

yarn add vite-i18n-by-design

pnpm add vite-i18n-by-design

Imports

default

wrong

import { i18nLoaderPlugin } from 'vite-i18n-by-design';

correct

import i18nLoaderPlugin from 'vite-i18n-by-design';

Default export only; named export does not exist.

virtual:i18n-messages
```
import messages from 'virtual:i18n-messages';
```
Virtual module provided by the plugin; must be used with Vite. Type declarations included in package.

loadMessages

wrong

import loadMessages from 'vite-i18n-by-design';

correct

import { loadMessages } from 'vite-i18n-by-design';

Named export for Node.js script usage; not suitable for browser or HMR.

Quickstart

Configures the Vite plugin, creates a vue-i18n instance with virtual messages, and mounts the app.

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import i18nLoaderPlugin from 'vite-i18n-by-design'

export default defineConfig({
  plugins: [
    vue(),
    i18nLoaderPlugin({ localesDir: 'locales' })
  ]
})

// src/i18n.ts
import { createI18n } from 'vue-i18n'
import messages from 'virtual:i18n-messages'

export const i18n = createI18n({
  legacy: false,
  locale: 'fr',
  fallbackLocale: 'en',
  messages
})

// main.ts
import { createApp } from 'vue'
import { i18n } from './i18n'
import App from './App.vue'

createApp(App).use(i18n).mount('#app')