vite-bundled-i18n

0.7.2 verified Mon Apr 27 auth: no javascript

Route-aware i18n bundler for Vite that extracts translation keys via AST analysis at build time and emits per-route scope-matched JSON bundles. Current stable version is 0.7.2, released with weekly or bi-weekly cadence. Unlike traditional i18n libraries (react-i18next, vue-i18n) that load all translations globally, vite-bundled-i18n tree-shakes translations per page, reducing payload from thousands of keys to only the ones needed for the current route. Supports React, Vue, and vanilla JS with a shared ~50-line core, optional compiled Map modules for O(1) lookup, SSR with automatic hydration, type-safe placeholder validation, and a testing utility. Requires Node >=20, peer deps: react >=18, react-dom >=18, vue ^3.0.0, eslint >=8.

Common errors

error Error [ERR_REQUIRE_ESM]: Must use import to load ES Module: /node_modules/vite-bundled-i18n/index.js ↓

cause Trying to require() an ESM-only module from CJS

fix

Switch your project to ESM ("type": "module" in package.json) or use dynamic import: const { i18nPlugin } = await import('vite-bundled-i18n');

error TypeError: i18nPlugin is not a function ↓

cause Using deprecated export name 'viteBundledI18n' (pre-0.7.0) or importing wrong symbol

fix

Import as: import { i18nPlugin } from 'vite-bundled-i18n'

error Module '"vite-bundled-i18n/react"' does not provide an export named 't' ↓

cause Typo in import path or using wrong framework (e.g., trying to import t from '/vue' in React project)

fix

Check the correct subpath: for React use '/react', for Vue '/vue', for vanilla '/vanilla'

Warnings

breaking Version 0.7.0 changed the plugin export name from 'viteBundledI18n' to 'i18nPlugin'. Old imports will fail with 'undefined is not a function'. ↓

fix Replace 'import { viteBundledI18n } from 'vite-bundled-i18n'' with 'import { i18nPlugin } from 'vite-bundled-i18n''.

breaking Version 0.6.0 migrated from CJS to ESM-only. CommonJS require() throws 'ERR_REQUIRE_ESM'. ↓

fix Use dynamic import() or switch project to ESM ("type": "module" in package.json).

deprecated The 'createScopeMapClient' function is deprecated since version 0.7.0 in favor of runtime plugin configuration. ↓

fix Use the plugin's built-in scope map handling; remove calls to createScopeMapClient.

gotcha Translation files must be named with locale code (e.g., 'en.json', 'de.json') and placed inside a 'locales' directory at project root by default. Files elsewhere won't be picked up. ↓

fix Ensure translation files are in 'src/locales/' or configure with 'bundling.localesDir'.

gotcha The t() function is not available from the root import; you must import from a framework-specific subpath (e.g., 'vite-bundled-i18n/react'). ↓

fix Use 'import { t } from 'vite-bundled-i18n/react'' for React projects.

Install

npm install vite-bundled-i18n

yarn add vite-bundled-i18n

pnpm add vite-bundled-i18n

Imports

i18nPlugin
wrong
```
const i18nPlugin = require('vite-bundled-i18n')
```
correct
```
import { i18nPlugin } from 'vite-bundled-i18n'
```
ESM-only; no CJS support. Must be imported as named export; no default export.
t
wrong
```
import { t } from 'vite-bundled-i18n'
```
correct
```
import { t } from 'vite-bundled-i18n/react'
```
The t function is exported from framework-specific subpath: '/react', '/vue', or '/vanilla'. Importing from root will not include the function.

createI18nTestPlugin

wrong

import { createI18nTestPlugin } from 'vite-bundled-i18n'

correct

import { createI18nTestPlugin } from 'vite-bundled-i18n/testing'

Testing utilities are exported from '/testing' subpath. From version 0.5.0 onwards.

Quickstart

Shows minimal setup: configure Vite plugin, use useI18n hook in React component, create a JSON locale file.

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { i18nPlugin } from 'vite-bundled-i18n';

export default defineConfig({
  plugins: [
    react(),
    i18nPlugin()
  ]
});

// src/App.tsx
import { useI18n } from 'vite-bundled-i18n/react';

export default function App() {
  const { t } = useI18n();
  return <h1>{t('greeting', { name: 'World' })}</h1>;
}

// src/locales/en.json
{
  "greeting": "Hello, {{name}}!"
}