Vue i18n Translation Extractor

Common errors

• [vue-i18n-extract] Error: vueFiles glob has no files.

  cause The glob pattern provided for `--vueFiles` (or in the config file) does not match any existing `.vue`, `.js`, or `.ts` files in your project. This often happens due to incorrect paths or typos in the pattern.
  fix Verify the `vueFiles` glob pattern in your command or configuration file. Use a tool like `ls -l './src/**/*.vue'` to confirm that files are matched by the pattern. Adjust the path or pattern as needed.

• [vue-i18n-extract] Error: languageFiles glob has no files.

  cause Similar to `vueFiles` not being found, this error indicates that the glob pattern for `--languageFiles` does not match any translation files (e.g., `.json`, `.yml`, `.yaml`) at the specified location.
  fix Check the `languageFiles` glob pattern. Ensure the path is correct and the file extensions (`.json`, `.yml`, `.yaml`) are included and properly escaped if necessary (e.g., `*.?(json|yml|yaml)`).

• TypeError: Cannot read properties of undefined (reading 'extractI18n')

  cause This typically occurs when attempting to use programmatic features (like `extractI18n`) in a CommonJS module context when the package is primarily designed for ES Modules, or when the named export is incorrect.
  fix For Node.js projects with `'type': 'module'`, use ES module imports: `import { extractI18n } from 'vue-i18n-extract';`. If sticking to CommonJS, check if a default export or different named exports are available, or use `await import('vue-i18n-extract')` for dynamic imports.

Warnings

• breaking Upgrading from `v1.x` to `v2.x` introduces significant breaking changes in configuration options. Several CLI arguments and config file properties have been renamed or removed.
  Fix: Review the official `vue-i18n-extract` documentation for v2.x to update `--vueFiles`, `--languageFiles`, and other options. Specifically, the `output` option was replaced by `dryRun` and `emit`.
• gotcha Incorrect glob patterns for `--vueFiles` or `--languageFiles` are a common cause of issues, leading to missing translations not being detected or files being ignored.
  Fix: Always test your glob patterns with a tool like `glob-tester` or `ls -l` combined with your pattern to ensure they correctly match the intended files. Pay close attention to file extensions and nested directory structures.
• gotcha When using `vue-i18n-extract` programmatically in an ES module (`'type': 'module'` in `package.json`) Node.js project, direct `require` statements for the library will fail with `SyntaxError: Unexpected token 'export'`.
  Fix: Ensure all imports are done using ES module syntax (e.g., `import { extractI18n } from 'vue-i18n-extract';`). If using older Node.js versions or CJS, configure a build step (like Babel or TypeScript compilation) to transpile imports.
• deprecated The underlying `vue-i18n` library has deprecated certain features like `$tc` and `tc` functions, especially for Composition API mode, and the `<i18n>` component in favor of `<i18n-t>`. While `vue-i18n-extract` aims to support various syntaxes, relying on deprecated `vue-i18n` features can lead to future compatibility issues.
  Fix: Migrate your `vue-i18n` usage to its latest recommended patterns, such as using `$t` or `t` for pluralization (with `n` parameter) and `<i18n-t>` components. Consult the `vue-i18n` migration guide for your specific version.

Install

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

Imports

• extractI18n
  wrong:

  const { extractI18n } = require('vue-i18n-extract');

  correct:

  import { extractI18n } from 'vue-i18n-extract';

  For programmatic usage in a modern Node.js or TypeScript environment, prefer ES module imports. CommonJS `require` is generally discouraged since v2+.
• readVueFiles

  import { readVueFiles } from 'vue-i18n-extract';

  This utility function assists in reading Vue SFCs and JavaScript/TypeScript files, returning their content for analysis. It's typically used within custom scripts.
• writeLocaleMessages

  import { writeLocaleMessages } from 'vue-i18n-extract';

  Used programmatically to write updated locale messages back to translation files. Ensure file paths are correct and permissions allow writing.

Quickstart

This `package.json` excerpt demonstrates how to integrate `vue-i18n-extract` into a project using npm scripts for reporting, adding, and removing translation keys.

{
  "name": "my-vue-i18n-app",
  "version": "1.0.0",
  "description": "My Vue.js i18n project",
  "main": "index.js",
  "scripts": {
    "i18n:report": "vue-i18n-extract report --vueFiles './src/**/*.?(js|ts|vue)' --languageFiles './src/locales/*.?(json|yml|yaml)' --ci",
    "i18n:add": "vue-i18n-extract report --vueFiles './src/**/*.?(js|ts|vue)' --languageFiles './src/locales/*.?(json|yml|yaml)' --add",
    "i18n:remove": "vue-i18n-extract report --vueFiles './src/**/*.?(js|ts|vue)' --languageFiles './src/locales/*.?(json|yml|yaml)' --remove"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "vue-i18n-extract": "^2.0.0"
  }
}