Heavy Industries vue-bi18n
What it is
Dead-simple internationalization for Vue applications. Yes, bi18n is a pun on bilingual i18n. The plugin handles any number of languages, but practically speaking, the intended use case is for sites supporting at most two or three languages. Depends on Vuex. A working example can be found on the Heavy Industries vue-bi18n GitHub Pages site.
Installation
Via npm:
$ npm install --save @heavyind/vue-bi18n
Via yarn:
$ yarn add @heavyind/vue-bi18n
Via unpkg (exposed as VueBi18n
):
<script src="https://unpkg.com/@heavyind/vue-bi18n"></script>
Usage
Note: Component tag name, store name, and scope name are configurable. For the sake of examples throughout this document we will use the default, which is bi18n
for all three. More information can be found under the Configuration heading below.
Getting started
Install the plugin and pass in a configuration object including your store and the list of languages you intend to support.
import VueBi18nfrom "@heavyind/vue-bi18n";
Vue.use(VueBi18n, cfg);
For this example, assume we want to support English and French via a languages: ['en', 'fr']
property on our configuration object. Usage is as follows:
<bi18n>
<template v-slot:en>Hello, world.</template>
<template v-slot:fr>Bonjour, le monde.</template>
</bi18n>
The appropriate greeting will be output based on which language you have currently set. It defaults to languages[0]
, which is, in this case, 'en'
. Changing the current language is supported via calling this.bi18n.set
on any Vue component: this.bi18n.set('fr')
. To get the current language, access this.bi18n.language
. More methods and accessors are described under the API heading below.
Using custom tags
If you would like the content you pass into the <bi18n>
component to render inside a particular tag, just pass its name in as a prop:
<bi18n tag="h1">
<template v-slot:en>On the Internet, nobody knows you're a dog.</template>
<template v-slot:fr>Sur Internet, personne ne sait que tu es un chien.</template>
</bi18n>
If you don't provide a custom tag, <bi18n>
renders as a text node.
Configuration
The default configuration object looks like this:
{ store: null
languages: [],
mixinNamespace: "$bi18n",
storeNamespace: "bi18n",
componentName: "bi18n"
}
Both store
and languages
are mandatory for you to reset. The languages
property is recommended to be an array of common language shortcodes, like ['en', 'es', 'fr']
.
Configuration settings in-depth
store
Allows vue-bi18n to hook into your Vuex store.
languages
Lets the store know which languages you want to support.
storeNamespace
Sets the namespace of the store module.
mixinNamespace
Sets the name bound to this
under which you can access API properties and methods. If you were to set this to foo
, the API would be available under this.foo
rather than this.$bi18n
.
componentName
Sets the name of the component. If you were to change this to bar
, the component would be written <bar>
rather than <bi18n>
.
API
this.$bi18n.language
String
The currently-set language
this.$bi18n.languageIdx
Number
The index of the currently-set language in the original languages
array passed into your configuration object
this.$bi18n.languages
Array
The list of available languages, as passed into your original configuration object
this.$bi18n.set
(lang: String)
Set the current language via a string
this.$bi18n.setByIdx
(index: Number)
Set the current language by index of the original languages
array passed into your configuration object
Note: the namespace of the API on Vue components can be set within the configuration object by passing a value for mixinNamespace
.
License
MIT