Vue I18n Jest Transformer

Common errors

• 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 <)

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

• Error: Cannot find module 'vue-i18n-jest' from 'jest.config.js'

  cause The `vue-i18n-jest` package is referenced in `jest.config.js` but is not installed as a development dependency.
  fix Install the package using your preferred package manager: `npm install --save-dev vue-i18n-jest` or `yarn add -D vue-i18n-jest`.

• Minimum Node.js version of 12.0.0 is required. You are running 10.x.x.

  cause Attempting to use `vue-i18n-jest` version 1.1.0 or newer with an unsupported Node.js runtime (version 10.x).
  fix Upgrade your Node.js environment to version 12 or a later compatible version. Consult your project's `.nvmrc` or CI/CD configuration.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Manually ensure that `vue-jest` (specifically version 4.x) is installed in your project's `devDependencies` alongside `vue-i18n-jest`.
• gotcha `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.
  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.

Install

• npm install vue-i18n-jest npm
• yarn add vue-i18n-jest yarn
• pnpm add vue-i18n-jest pnpm

Imports

• Jest Configuration (Vue SFC i18n blocks)
  wrong:

  // jest.config.js
  module.exports = {
    transform: {
      '^.+\.vue$': 'vue-i18n-jest' // Incorrectly trying to use it as the primary Vue transformer
    }
  };

  correct:

  // jest.config.js
  module.exports = {
    // ... other Jest configurations
    globals: {
      'vue-jest': {
        transform: {
          'i18n': 'vue-i18n-jest' // This line enables the transformer for i18n blocks
        }
      }
    }
  };

  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`.
• Direct Transformer Reference (Less Common)
  wrong:

  import { process } from 'vue-i18n-jest'; // This package exports a default function, not named exports for direct usage

  correct:

  // jest.config.js
  module.exports = {
    transform: {
      '^.+\.(i18n|json5)$': 'vue-i18n-jest' // Example: directly mapping i18n custom blocks if extracted to separate files
    }
  };

  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.
• CommonJS/ESM Module Import (Discouraged)
  wrong:

  const i18nTransformer = require('vue-i18n-jest');
  // or
  import i18nTransformer from 'vue-i18n-jest';

  correct:
  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.

Quickstart

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

// jest.config.js
const path = require('path');

module.exports = {
  // Specify test environment (e.g., jsdom for browser-like DOM environment)
  testEnvironment: 'jsdom',
  // List of file extensions Jest should look for
  moduleFileExtensions: ['js', 'json', 'vue', 'ts'],
  // How to transform files based on their extension
  transform: {
    '^.+\.vue$': 'vue-jest', // Use vue-jest for Vue SFCs
    '^.+\.js$': 'babel-jest', // Use babel-jest for JavaScript files
    '^.+\.ts$': 'ts-jest'    // Use ts-jest for TypeScript files (if applicable)
  },
  // Global settings for specific transformers, especially for vue-jest
  globals: {
    'vue-jest': {
      // Enable vue-i18n-jest to process <i18n> blocks within Vue SFCs
      transform: {
        'i18n': 'vue-i18n-jest' 
      }
    }
  },
  // Set up module name mapping for imports, e.g., '@/components' for 'src/components'
  moduleNameMapper: {
    '^@/(.*)$': path.resolve(__dirname, 'src/$1')
  },
  // Snapshot serializer for Vue components (recommended for better readability)
  snapshotSerializers: [
    'jest-serializer-vue'
  ]
  // Ensure vue and vue-template-compiler are installed as devDependencies.
  // This setup assumes a basic Vue 2 project with TypeScript (optional) and Babel.
};