vue-i18n-next

Internationalization plugin for Vue.js

🥈 Silver Sponsors

🥉 Bronze Sponsors

Status: Beta

The current codebase has most of the existing features on Vue I18n v8.x and is usable.

Since the library is still unstable and because we want feedback on bugs and missing features, it will probably go through a few breaking changes.

If you use stable Vue I18n version, see this repository

⭐ New Features

Message Format Syntax

• Literal Interpolation
  • You can use a single quote ' and "Mustache" like ({ } ) to make the message literal.
  • e.g. foo{'@'}domain.com
• Message Functions
  • As with Vue's render function, vue-i18n-next (and future releases) support the Message functions.
  • Using the Message function has the following advantages:
    • Accelerate evaluation of vue-i18n messages (pre-compilation)
    • Support for complex i18n that cannot be handled by message format

Composition API

New style API for Vue Composition API. See the following docs:

• createI18n
  • I18nOptions
  • ComposerOptions
  • VueI18nOptions
• useI18n
  • ComposerOptions
• Composer
• VueI18n

<i18n-t> Component (formerly called <i18n> component)

You can use pluralization on the component. See the below examples:

• Example with using Composition API
• Example with using Legacy API

<i18n-d> Component

You can use datetime format on the component, like <i18n-n> component.

See the below examples:

• Example with using Composition API
• Example with using Legacy API

🍭 Examples

See the examples directory.

The examples are offered in thee following two API styles:

• composition
  • Examples with using new vue-i18n API optimized for Vue 3
• legacy
  • Examples with using vue-i18n API that are almost compatible with vue-i18n v8.x

🙋 About support for v9 and earlier

• v6 and earlier: drop supporting
• v7 and v8: become LTS upon vue-i18n v9 release with an 15 months maintenance lifespan

❗ Known issues

💥 Breaking changes compared to vue-i18n v8.x

Message Format Syntax

• Special characters
  • Since vue-i18n-next, the message format syntax is handled by the compiler.
  • List interpolation is no longer allowed for array-like objects (e.g. { '0': 'hello' }).
  • The following characters used in the message syntax are processed by the compiler as special characters:
    • {, }, @, $, |
  • If you want to use these special characters, you can use literal interpolation to get around it.
• Linked messages
  • No longer use grouping by brackets for key of linked messages.
  • v9 and later use named, list, and literal interpolations

APIs

• The return value of $t and t methods is string only. object and array values are no longer returned.
  • As an alternative way, you can use $tm / tm
• The return value of $tc and tc methods is string only. object and array values are no longer returned.
  • As an alternative way, you can use $tm / tm
• VueI18n class cannot used with new. It can only be used via the $i18n property of Vue instance.
  • In vue-i18n-next, by replacing new VueI18n with createI18n, you can use existing VueI18n options as they are.
  • See the examples/legacy directory.
• VueI18n.prototype.getChoiceIndex
  • -> Legacy API style: pluralizationRules option of createI18n factory function (like new VueI18n(...))
  • -> Compsable API style: pluralRules option of createI18nComposer factory function
• warnHtmlInMessage option:
  • Composition API: warnHtmlMessage boolean property, default true.
  • Legacy API: warnHtmlInMessage property.
  • For development mode, warning is default.
  • For production mode, HTML message detect is not check due to performance.
• v-t directive
  • preserve modifier deprecated, keep Element content
  • Legacy API preserveDirectiveContent option, and property deprecated
• VueI18n.version -> import { VERSION } from 'vue-i18n'
• VueI18n.availabilities -> import { availabilities } from 'vue-i18n'
• See the details here

Components

• <i18n> component
  • Rename to <i18n-t> component
  • Remove Boolean type from tag prop
  • if tag prop is not specified, return the Fragment
  • Remove the below props:
    • place prop
    • places prop
    • path prop (Rename to keypath prop)
• <i18n-n> component
  • Remove Boolean type from tag prop
  • if tag prop is not specified, return the Fragment

⚡ Improvements

• See the vue-i18n issues that are labeled with Status: Ready

🔨 Missing features

• Custom formatting
• Tooling
  • @intlify/devtools
  • vue-cli-plugin-i18n
  • @intlify/eslint-plugin-vue-i18n

💿 Installation

npm

npm install --save vue-i18n@next

yarn

yarn add vue-i18n@next

📦 About dist files

From CDN or without a Bundler

• vue-i18n.global(.prod).js:

  • For direct use via <script src="..."> in the browser. Exposes the VueI18n global.
  • Note that global builds are not UMD builds. They are built as IIFEs and are only meant for direct use via <script src="...">.
  • Contains hard-coded prod/dev branches, and the prod build is pre-minified. Use the *.prod.js files for production.

• vue-i18n.esm-browser(.prod).js:

  • For usage via native ES modules imports (in browser via <script type="module">.
  • Shares the same runtime compilation, dependency inlining and hard-coded prod/dev behavior with the global build.

With a Bundler

• vue-i18n.esm-bundler.js:
  • For use with bundlers like webpack, rollup and parcel.
  • Leaves prod/dev branches with process.env.NODE_ENV guards (must be replaced by bundler)
  • Does not ship minified builds (to be done together with the rest of the code after bundling)

Bundler Build Feature Flags

Starting with 9.0.0-beta.2, esm-bundler builds now exposes global feature flags that can be overwritten at compile time:

• __VUE_I18N_FULL_INSTALL__ (enable/disable, in addition to vue-i18n APIs, components and directives all fully support installation: true)
• __VUE_I18N_LEGACY_API__ (enable/disable vue-i18n legacy style APIs support, default: true)
• __INTLIFY_PROD_DEVTOOLS__ (enable/disable intlify-devtools and vue-devtools support in production, default: false)

The build will work without configuring these flags, however it is strongly recommended to properly configure them in order to get proper tree-shaking in the final bundle. To configure these flags:

• webpack: use DefinePlugin
• Rollup: use @rollup/plugin-replace
• Vite: configured by default, but can be overwritten using the define option

Note: the replacement value must be boolean literals and cannot be strings, otherwise the bundler/minifier will not be able to properly evaluate the conditions.

✅ TODOs

©️ License

MIT