# Getting Started

# 💿 Installation

Use npm (opens new window) or a compatible tool.

npm install --save-dev eslint @intlify/eslint-plugin-vue-i18n

Requirements

ESLint v5.0.0 or later
Node.js v14.17.x, v16.x or later

# 🚀 Usage

Configure your .eslintrc.* file.

For example:

module.export = {
  extends: [
    'eslint:recommended',
    // Recommended
    'plugin:@intlify/vue-i18n/recommended'
  ],
  rules: {
    // Optional.
    '@intlify/vue-i18n/no-dynamic-keys': 'error',
    '@intlify/vue-i18n/no-unused-keys': [
      'error',
      {
        extensions: ['.js', '.vue']
      }
    ]
  },
  settings: {
    'vue-i18n': {
      localeDir: './path/to/locales/*.{json,json5,yaml,yml}', // extension is glob formatting!
      // or
      // localeDir: {
      //   pattern: './path/to/locales/*.{json,json5,yaml,yml}', // extension is glob formatting!
      //   localeKey: 'file' // or 'path' or 'key'
      // }
      // or
      // localeDir: [
      //   {
      //     // 'file' case
      //     pattern: './path/to/locales1/*.{json,json5,yaml,yml}',
      //     localeKey: 'file'
      //   },
      //   {
      //     // 'path' case
      //     pattern: './path/to/locales2/*.{json,json5,yaml,yml}',
      //     localePattern: /^.*\/(?<locale>[A-Za-z0-9-_]+)\/.*\.(json5?|ya?ml)$/,
      //     localeKey: 'path'
      //   },
      //   {
      //     // 'key' case
      //     pattern: './path/to/locales3/*.{json,json5,yaml,yml}',
      //     localeKey: 'key'
      //   },
      // ]

      // Specify the version of `vue-i18n` you are using.
      // If not specified, the message will be parsed twice.
      messageSyntaxVersion: '^9.0.0'
    }
  }
}

See the rule list

# `settings['vue-i18n']`

localeDir ... You can specify a string or an object or an array.
- String option ... A glob for specifying files that store localization messages of project.
- Object option
  - pattern (string) ... A glob for specifying files that store localization messages of project.
  - localeKey ('file' | 'path' | 'key') ... Specifies how to determine the locale for localization messages.
    - 'file' ... Determine the locale name from the filename. The resource file should only contain messages for that locale. Use this option if you use vue-cli-plugin-i18n. This option is also used when String option is specified.
    - 'path' ... Determine the locale name from the path. In this case, the locale must be had structured with your rule on the path. It can be captured with the regular expression named capture. The resource file should only contain messages for that locale.
    - 'key' ... Determine the locale name from the root key name of the file contents. The value of that key should only contain messages for that locale. Used when the resource file is in the format given to the messages option of the VueI18n constructor option.
  - localePattern ... Specifies how to determine pattern the locale for localization messages. This option means, when localeKey is 'path', you will need to capture the locale using a regular expression. You need to use the locale capture as a named capture ?<locale>, so it’s be able to capture from the path of the locale resources. If you omit it, it will be captured from the resource path with the same regular expression pattern as vue-cli-plugin-i18n.
- Array option ... An array of String option and Object option. Useful if you have multiple locale directories.
messageSyntaxVersion (Optional) ... Specify the version of vue-i18n you are using. If not specified, the message will be parsed twice. Also, some rules require this setting.

::: warn NOTE

The localePattern options does not support SFC i18n custom blocks (src attribute), only for resources of files to import when specified in VueI18n's messages options (VueI18n v9 and later, messages specified in createI18n) for resources of files to import.

:::

# Running ESLint from command line

If you want to run eslint from command line, make sure you include the .vue, .json, .json5, .yaml and .yml extension using the --ext option (opens new window) or a glob pattern because ESLint targets only .js files by default.

Examples:

eslint --ext .js,.vue,.json src
eslint "src/**/*.{js,vue,json}"
# Specify the extension you use.
# - use YAML?
# eslint --ext .js,.vue,.yaml,.yml src
# eslint "src/**/*.{js,vue,yaml,yml}"
# - use JSON5?
# eslint --ext .js,.vue,.json5 src
# eslint "src/**/*.{js,vue,json5}"

# How to use custom parser?

If you want to use custom parsers such as babel-eslint (opens new window) or typescript-eslint-parser (opens new window), you have to use parserOptions.parser option instead of parser option. Because this plugin requires vue-eslint-parser (opens new window) to parse .vue files, so this plugin doesn't work if you overwrote parser option.

Also, parserOptions configured at the top level affect .json and .yaml. This plugin needs to use special parsers to parse .json and .yaml, so to correctly parse each extension, use the overrides option and overwrite the options again.

- "parser": "babel-eslint",
  "parserOptions": {
+     "parser": "babel-eslint",
      "sourceType": "module"
  },
+ "overrides": [
+     {
+         "files": ["*.json", "*.json5"],
+         "extends": ["plugin:@intlify/vue-i18n/base"],
+     },
+     {
+         "files": ["*.yaml", "*.yml"],
+         "extends": ["plugin:@intlify/vue-i18n/base"],
+     }
+ ]

# More lint on JSON and YAML in `<i18n>` block

You can install eslint-plugin-jsonc (opens new window) and eslint-plugin-yml (opens new window). These 2 plugins support Vue custom blocks.

You can also use jsonc/vue-custom-block/no-parsing-error (opens new window) and yml/vue-custom-block/no-parsing-error (opens new window) rules to find JSON and YAML parsing errors.

# ❓ FAQ

# What is the "Use the latest vue-eslint-parser" error?

The most rules of eslint-plugin-vue-i18n require vue-eslint-parser to check <template> ASTs.

Make sure you have one of the following settings in your .eslintrc:

"extends": ["plugin:@intlify/vue-i18n/recommended"]
"extends": ["plugin:@intlify/vue-i18n/base"]

If you already use other parser (e.g. "parser": "babel-eslint"), please move it into parserOptions, so it doesn't collide with the vue-eslint-parser used by this plugin's configuration:

- "parser": "babel-eslint",
  "parserOptions": {
+     "parser": "babel-eslint",
      "ecmaVersion": 2017,
      "sourceType": "module"
  }

See also: "Use together with custom parsers" section.

# Why doesn't it work on .vue file?

Make sure you don't have eslint-plugin-html in your config. The eslint-plugin-html extracts the content from <script> tags, but eslint-plugin-vue requires <script> tags and <template> tags in order to distinguish template and script in single file components.

  "plugins": [
    "vue",
-   "html"
  ]

Make sure your tool is set to lint .vue and .json files.

CLI targets only .js files by default. You have to specify additional extensions by --ext option or glob patterns. E.g. eslint "src/**/*.{js,vue,json}" or eslint src --ext .vue,.json.o

← Introduction Available Rules →