Registry / web-framework / vite-plugin-i18next-loader

vite-plugin-i18next-loader

library3.1.3jsnpmunverified

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.

web-framework

npm install vite-plugin-i18next-loader

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-I18NEX

vite-plugin-i18next-loader

web-frameworkjavascriptv3.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import i18nextLoader from 'vite-plugin-i18next-loader'

✗ const i18nextLoader = require('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

✓ import type { Options } from 'vite-plugin-i18next-loader'

✗ import { 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

✓ import resources from 'virtual:i18next-loader'

✗ import resources from 'vite-plugin-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.

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

Debug

Known issues

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

affects: >=3.0.0

gotchaThe 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).

affects: >=3.1.3

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

affects: >=3.0.0

breakingv3.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`.

affects: >=3.0.0

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

affects: >=2.0.0

Errors

Common errors & fixes

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

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

ERR_REQUIRE_ESM

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

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

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: No locale files found in paths: [list of paths]

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.

Upgrade

Version history

3.1.3latest on npm

Audit

Dependencies

viterequiredRequired as a peer dependency; plugin is designed to work with Vite builds and provides Vite-specific hooks like `resolveId` and `load`. HMR relies on Vite's module graph.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/alienfast/vite-plugin-i18next-loader ↗

packagehttps://www.npmjs.com/package/vite-plugin-i18next-loader ↗