{"id":22700,"library":"vite-plugin-i18next-loader","title":"vite-plugin-i18next-loader","description":"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.","status":"active","version":"3.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/alienfast/vite-plugin-i18next-loader","tags":["javascript","vite-plugin","loader","i18next","locales","yaml","json","typescript"],"install":[{"cmd":"npm install vite-plugin-i18next-loader","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-i18next-loader","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-i18next-loader","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required 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.","package":"vite","optional":false}],"imports":[{"note":"The package is ESM-only since v3. If using CommonJS, you must use dynamic import or convert your project to ESM.","wrong":"const i18nextLoader = require('vite-plugin-i18next-loader')","symbol":"default","correct":"import i18nextLoader from 'vite-plugin-i18next-loader'"},{"note":"Options is a TypeScript interface; import it as a type to avoid runtime errors if your bundler tries to include it.","wrong":"import { Options } from 'vite-plugin-i18next-loader'","symbol":"Options","correct":"import type { Options } from 'vite-plugin-i18next-loader'"},{"note":"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.","wrong":"import resources from 'vite-plugin-i18next-loader'","symbol":"virtual module:virtual:i18next-loader","correct":"import resources from 'virtual:i18next-loader'"}],"quickstart":{"code":"// File: vite.config.ts\nimport { defineConfig } from 'vite';\nimport i18nextLoader from 'vite-plugin-i18next-loader';\n\nexport default defineConfig({\n  plugins: [i18nextLoader({ paths: ['./node_modules/foo/locales', './locales'] })],\n});\n\n// File: app.ts\nimport i18n from 'i18next';\nimport resources from 'virtual:i18next-loader';\n\ni18n.init({ resources });\n\ni18n.t('key');\n\n// Ensure your locale files exist in the specified paths, e.g.:\n//   ./locales/en/foo.json\n//   ./locales/de/bar.yaml","lang":"typescript","description":"Configures the Vite plugin with multiple locale paths and imports the generated virtual module for i18n initialization."},"warnings":[{"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.","message":"v3.0.0 switched from glob-all to glob, changing exclusion/ignore behavior. The `ignore` option now uses glob patterns instead of minimatch patterns.","severity":"breaking","affected_versions":">=3.0.0"},{"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).","message":"The plugin requires Node >=20 as of v3.1.3. Running on older Node versions will cause runtime errors.","severity":"gotcha","affected_versions":">=3.1.3"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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`.","message":"v3.0.0 dropped CommonJS support entirely. The package is now ESM-only.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"HMR may not work correctly if the locale files are outside the Vite project root or if they contain syntax errors in YAML/JSON.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run `npm install -D vite-plugin-i18next-loader` or `yarn add -D vite-plugin-i18next-loader`.","cause":"Package not installed or not found by Node.js resolver.","error":"Error: Cannot find module 'vite-plugin-i18next-loader'"},{"fix":"Use `import` instead of `require()`. If you must use CommonJS, use dynamic import: `const i18nextLoader = (await import('vite-plugin-i18next-loader')).default`.","cause":"Using `require()` to import an ESM-only package.","error":"ERR_REQUIRE_ESM"},{"fix":"Make sure to add `i18nextLoader({...})` to the `plugins` array in your `vite.config.ts`.","cause":"The Vite plugin is not loaded or configured correctly.","error":"Failed to resolve import \"virtual:i18next-loader\" from \"src/app.ts\""},{"fix":"Verify that the locale files exist in the specified directories and match the default or custom `include` patterns.","cause":"No matching JSON or YAML files exist in the specified `paths` or they are filtered out by `include`/`ignore`.","error":"Error: No locale files found in paths: [list of paths]"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}