{"id":12501,"library":"vue-i18n-jest","title":"Vue I18n Jest Transformer","description":"vue-i18n-jest is a specialized Jest transformer designed to enable the correct parsing and transformation of `<i18n>` custom blocks within Vue Single File Components (SFCs) during unit testing. It specifically targets Vue 2 applications and integrates with `vue-jest@v4`. This package is crucial for developers who store their internationalization messages directly within their Vue components and need Jest to understand and process these blocks for testing. The current stable version is 1.1.1, released in October 2021. Its release cadence has been sporadic. It differentiates itself by providing a dedicated bridge for `vue-jest` to handle i18n custom blocks, which is not natively supported by `vue-jest` alone for Vue 2 testing environments.","status":"maintenance","version":"1.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/intlify/vue-i18n-jest","tags":["javascript","i18n","jest","vue","vue-i18n"],"install":[{"cmd":"npm install vue-i18n-jest","lang":"bash","label":"npm"},{"cmd":"yarn add vue-i18n-jest","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-i18n-jest","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for the Vue 2 applications being tested.","package":"vue","optional":false},{"reason":"Peer dependency critical for compiling Vue 2 templates and SFCs in a Jest environment.","package":"vue-template-compiler","optional":false}],"imports":[{"note":"vue-i18n-jest is consumed as a string reference within Jest's configuration. It must be nested under `globals['vue-jest'].transform.i18n` to handle custom i18n blocks within Vue 2 SFCs, complementing `vue-jest`.","wrong":"// jest.config.js\nmodule.exports = {\n  transform: {\n    '^.+\\.vue$': 'vue-i18n-jest' // Incorrectly trying to use it as the primary Vue transformer\n  }\n};","symbol":"Jest Configuration (Vue SFC i18n blocks)","correct":"// jest.config.js\nmodule.exports = {\n  // ... other Jest configurations\n  globals: {\n    'vue-jest': {\n      transform: {\n        'i18n': 'vue-i18n-jest' // This line enables the transformer for i18n blocks\n      }\n    }\n  }\n};"},{"note":"While its primary use is through `vue-jest`, `vue-i18n-jest` is technically a Jest transformer and could be mapped directly to specific file extensions (e.g., `.i18n` or `.json5` if your i18n content lives in standalone files). Direct programmatic import of its module is not its typical use case.","wrong":"import { process } from 'vue-i18n-jest'; // This package exports a default function, not named exports for direct usage","symbol":"Direct Transformer Reference (Less Common)","correct":"// jest.config.js\nmodule.exports = {\n  transform: {\n    '^.+\\.(i18n|json5)$': 'vue-i18n-jest' // Example: directly mapping i18n custom blocks if extracted to separate files\n  }\n};"},{"note":"Jest transformers are loaded by their string name during configuration. Attempting to manually `require` or `import` the module into JavaScript/TypeScript code for direct invocation of its `process` method is not the standard or recommended way to use this package.","wrong":"const i18nTransformer = require('vue-i18n-jest');\n// or\nimport i18nTransformer from 'vue-i18n-jest';","symbol":"CommonJS/ESM Module Import (Discouraged)"}],"quickstart":{"code":"// jest.config.js\nconst path = require('path');\n\nmodule.exports = {\n  // Specify test environment (e.g., jsdom for browser-like DOM environment)\n  testEnvironment: 'jsdom',\n  // List of file extensions Jest should look for\n  moduleFileExtensions: ['js', 'json', 'vue', 'ts'],\n  // How to transform files based on their extension\n  transform: {\n    '^.+\\.vue$': 'vue-jest', // Use vue-jest for Vue SFCs\n    '^.+\\.js$': 'babel-jest', // Use babel-jest for JavaScript files\n    '^.+\\.ts$': 'ts-jest'    // Use ts-jest for TypeScript files (if applicable)\n  },\n  // Global settings for specific transformers, especially for vue-jest\n  globals: {\n    'vue-jest': {\n      // Enable vue-i18n-jest to process <i18n> blocks within Vue SFCs\n      transform: {\n        'i18n': 'vue-i18n-jest' \n      }\n    }\n  },\n  // Set up module name mapping for imports, e.g., '@/components' for 'src/components'\n  moduleNameMapper: {\n    '^@/(.*)$': path.resolve(__dirname, 'src/$1')\n  },\n  // Snapshot serializer for Vue components (recommended for better readability)\n  snapshotSerializers: [\n    'jest-serializer-vue'\n  ]\n  // Ensure vue and vue-template-compiler are installed as devDependencies.\n  // This setup assumes a basic Vue 2 project with TypeScript (optional) and Babel.\n};","lang":"javascript","description":"This configuration snippet for `jest.config.js` demonstrates how to integrate `vue-i18n-jest` into your Jest setup to correctly parse `<i18n>` custom blocks within Vue 2 Single File Components when using `vue-jest`."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 12 or higher. Check your project's `engines` field in `package.json` and your CI/CD environment.","message":"Starting with version 1.1.0, Node.js version 10 is no longer supported. Projects must upgrade to Node.js 12 or newer to use this version and subsequent releases.","severity":"breaking","affected_versions":">=1.1.0"},{"fix":"Ensure your project is a Vue 2 application and `vue-jest` version 4.x is installed. For Vue 3, alternative solutions for i18n block transformation might be required or are handled differently by `vue-jest` v5.","message":"This transformer is specifically designed for `vue-jest@v4`, which is used for testing Vue 2 applications. It is not compatible with `vue-jest@v5` or testing environments for Vue 3.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Manually ensure that `vue-jest` (specifically version 4.x) is installed in your project's `devDependencies` alongside `vue-i18n-jest`.","message":"As of v1.1.1, `vue-jest` was removed from `vue-i18n-jest`'s peerDependencies. While no longer explicitly listed, `vue-jest@v4` remains a functional dependency for this package to operate correctly.","severity":"gotcha","affected_versions":">=1.1.1"},{"fix":"Ensure `vue` (e.g., `^2.5`) and `vue-template-compiler` (e.g., `^2.5`) are installed as `devDependencies` in your project, matching the required peer dependency versions.","message":"`vue` and `vue-template-compiler` are essential peer dependencies for any Vue 2 testing setup using `vue-jest`. Failure to install compatible versions will lead to Jest errors.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify that `vue-i18n-jest` is installed and correctly added to your `jest.config.js` under `globals['vue-jest'].transform.i18n` as shown in the quickstart example.","cause":"The `vue-i18n-jest` transformer is not correctly configured in `jest.config.js`, causing Jest to fail when parsing `<i18n>` blocks within Vue SFCs.","error":"Jest encountered an unexpected token. This usually means that you are trying to import a file which Jest cannot parse, e.g. a .vue file with a custom block you have not configured a transformer for. (SyntaxError: Unexpected token <)"},{"fix":"Install the package using your preferred package manager: `npm install --save-dev vue-i18n-jest` or `yarn add -D vue-i18n-jest`.","cause":"The `vue-i18n-jest` package is referenced in `jest.config.js` but is not installed as a development dependency.","error":"Error: Cannot find module 'vue-i18n-jest' from 'jest.config.js'"},{"fix":"Upgrade your Node.js environment to version 12 or a later compatible version. Consult your project's `.nvmrc` or CI/CD configuration.","cause":"Attempting to use `vue-i18n-jest` version 1.1.0 or newer with an unsupported Node.js runtime (version 10.x).","error":"Minimum Node.js version of 12.0.0 is required. You are running 10.x.x."}],"ecosystem":"npm"}