vite-plugin-i18next-loader

3.1.3 verified Mon Apr 27 auth: no javascript

Vite plugin that bundles i18next locale resources (JSON/YAML) as a virtual module during build, avoiding HTTP requests for locale files. Current stable version is 3.1.3, requires Node >=20, and peer dependency Vite >=3.1.6. It composes resources from one or many glob-matched directories, supports HMR, and allows overriding via ordered paths for white-labeling. Unlike alternatives that rely on runtime fetching or separate bundling, this plugin generates the entire `resources` structure at build time, enabling zero-config i18n loading.

Common errors

error Error: Cannot find module 'vite-plugin-i18next-loader' ↓

cause Package not installed or not found by Node.js resolver.

fix

Run npm install -D vite-plugin-i18next-loader or yarn add -D vite-plugin-i18next-loader.

error ERR_REQUIRE_ESM ↓

cause Using `require()` to import an ESM-only package.

fix

Use import instead of require(). If you must use CommonJS, use dynamic import: const i18nextLoader = (await import('vite-plugin-i18next-loader')).default.

error Failed to resolve import "virtual:i18next-loader" from "src/app.ts" ↓

cause The Vite plugin is not loaded or configured correctly.

fix

Make sure to add i18nextLoader({...}) to the plugins array in your vite.config.ts.

error Error: No locale files found in paths: [list of paths] ↓

cause No matching JSON or YAML files exist in the specified `paths` or they are filtered out by `include`/`ignore`.

fix

Verify that the locale files exist in the specified directories and match the default or custom include patterns.

Warnings

breaking v3.0.0 switched from glob-all to glob, changing exclusion/ignore behavior. The `ignore` option now uses glob patterns instead of minimatch patterns. ↓

fix Update your `ignore` patterns to follow glob syntax (e.g., '**/exclude.json' instead of 'exclude.json'). If you were using glob-all's array format, wrap patterns in an array.

gotcha The plugin requires Node >=20 as of v3.1.3. Running on older Node versions will cause runtime errors. ↓

fix Upgrade Node.js to version 20 or later, or stay on v3.1.2 which supported older Node versions (though with out-of-date dependencies).

gotcha The virtual module 'virtual:i18next-loader' does not exist at runtime if the Vite plugin is not properly loaded. You must ensure the plugin is included in your Vite config; otherwise, the import will fail. ↓

fix Double-check that `i18nextLoader()` is added to the `plugins` array in your Vite config. If you have multiple configs, ensure it's present in all builds.

breaking v3.0.0 dropped CommonJS support entirely. The package is now ESM-only. ↓

fix Convert your project to ESM (use 'type': 'module' in package.json) or use dynamic import: `const i18nextLoader = (await import('vite-plugin-i18next-loader')).default`.

gotcha HMR may not work correctly if the locale files are outside the Vite project root or if they contain syntax errors in YAML/JSON. ↓

fix Ensure locale files are within the Vite project directory and validate your YAML/JSON files for errors. If HMR still fails, check the Vite dev server logs for 'vite-plugin-i18next-loader' warnings.

Install

npm install vite-plugin-i18next-loader

yarn add vite-plugin-i18next-loader

pnpm add vite-plugin-i18next-loader

Imports

default
wrong
```
const i18nextLoader = require('vite-plugin-i18next-loader')
```
correct
```
import i18nextLoader from 'vite-plugin-i18next-loader'
```
The package is ESM-only since v3. If using CommonJS, you must use dynamic import or convert your project to ESM.
Options
wrong
```
import { Options } from 'vite-plugin-i18next-loader'
```
correct
```
import type { Options } from 'vite-plugin-i18next-loader'
```
Options is a TypeScript interface; import it as a type to avoid runtime errors if your bundler tries to include it.
virtual module:virtual:i18next-loader
wrong
```
import resources from 'vite-plugin-i18next-loader'
```
correct
```
import resources from 'virtual:i18next-loader'
```
The virtual module is generated by the plugin and is not a real file on disk. Importing from the package name itself is a common mistake that will fail.

Quickstart

Configures the Vite plugin with multiple locale paths and imports the generated virtual module for i18n initialization.

// File: vite.config.ts
import { defineConfig } from 'vite';
import i18nextLoader from 'vite-plugin-i18next-loader';

export default defineConfig({
  plugins: [i18nextLoader({ paths: ['./node_modules/foo/locales', './locales'] })],
});

// File: app.ts
import i18n from 'i18next';
import resources from 'virtual:i18next-loader';

i18n.init({ resources });

i18n.t('key');

// Ensure your locale files exist in the specified paths, e.g.:
//   ./locales/en/foo.json
//   ./locales/de/bar.yaml