vite-plugin-i18n

1.0.2 verified Mon Apr 27 auth: no javascript

A Vite plugin for internationalization (i18n) that integrates seamlessly with Vite's build process. Version 1.0.2 provides a simple way to manage translation files, auto-generate type-safe i18n functions, and optimize bundle size by tree-shaking unused translations. It supports JSON, YAML, and TypeScript translation files with hot-reload in development. Compared to alternatives like i18next or vue-i18n, it offers a lower overhead and tighter Vite integration. Release cadence is irregular with limited community adoption.

Common errors

error Cannot find module 'vite-plugin-i18n' or its corresponding type declarations. ↓

cause Package not installed or TypeScript cannot locate types.

fix

Run 'npm install vite-plugin-i18n' and ensure 'tsconfig.json' includes 'node_modules/@types'.

error TypeError: i18nPlugin is not a function ↓

cause Using CommonJS require instead of ESM import.

fix

Change 'const i18nPlugin = require(...)' to 'import i18nPlugin from ...'.

error [vite] Internal server error: Plugin 'vite-plugin-i18n' failed to load ↓

cause Configuration mismatch or missing required options.

fix

Check that 'locales' array and 'defaultLocale' are provided in plugin options.

Warnings

breaking The plugin requires Vite >= 2.0 and may not work with Vite 3+ without adjustments. ↓

fix Check compatibility with your Vite version; consider using an alternative like @intlify/vite-plugin-vue-i18n for newer Vite.

deprecated Some older configuration options like 'messagesDir' are deprecated in favor of 'localesDir'. ↓

fix Use 'localesDir' instead of 'messagesDir'.

gotcha The plugin generates type definitions only if 'typesOutput' is specified; otherwise, no types are emitted. ↓

fix Set 'typesOutput' to a file path to enable auto-generated types.

gotcha Non-ASCII characters in locale files may cause encoding issues on Windows. ↓

fix Save locale files as UTF-8 with BOM or use Unicode escape sequences.

Install

npm install vite-plugin-i18n

yarn add vite-plugin-i18n

pnpm add vite-plugin-i18n

Imports

i18nPlugin

wrong

const i18nPlugin = require('vite-plugin-i18n')

correct

import i18nPlugin from 'vite-plugin-i18n'

ESM-only; CommonJS require will fail. Use import.

defineI18n
wrong
```
import defineI18n from 'vite-plugin-i18n'
```
correct
```
import { defineI18n } from 'vite-plugin-i18n'
```
defineI18n is a named export, not default. Check docs for correct usage.

useI18n

wrong

import useI18n from 'vite-plugin-i18n'

correct

import { useI18n } from 'vite-plugin-i18n'

Named export for runtime usage.

Quickstart

Configures the plugin in vite.config.ts, then defines and uses i18n functions in a component.

import i18nPlugin from 'vite-plugin-i18n';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    i18nPlugin({
      locales: ['en', 'fr', 'de'],
      defaultLocale: 'en',
      messagesDir: 'src/locales',
      typesOutput: 'src/types/i18n.d.ts'
    })
  ]
});

// In a component:
import { defineI18n } from 'vite-plugin-i18n';
const { t } = defineI18n();
console.log(t('hello'));