View on GitHub

v-localize

Simple localization plugin for the amazing Vue.js.

V-Localize

About

V-Localize is a very simple localization plugin for Vue.js. Your localizations will be available anywhere in your web application wrapped in a Vue instance.

Support

Chome	Edge	Firefox	Opera	Safari
4.0+ ✔	✔	3.5+ ✔	10.50+ ✔	4.0+ ✔

V-Localize was developed using Vue.js 2.x, support for previous versions is not available.

Usage

To install via Bower, simply do the following:

bower install v-localize

To install via NPM:

npm install v-localize

For a quick start using jsdelivr:

<script src="https://cdn.jsdelivr.net/npm/v-localize/dist/v-localize.js"></script>

Installing the plugin is then as simple as:

import Localize from 'v-localize';

Vue.use(Localize);

let localize = Localize.config({
  default: 'en-US',
  available: ['en-US', 'es-SP', {
    locale: 'ar-MS',
    orientation: 'rtl',
    font: {
      size: 'smaller'
    }
  }],
  fallback: '?',
  localizations: {
    "en-US": {
      header: {
        title: 'English'
      }
    },
    "es-SP": {
      header: {
        title: 'Spanish'
      }
    },
    "ar-MS": {
      header: {
        title: 'Arabic'
      }
    }
  }
});

new Vue({
  el: '#app',
  localize
});

Once your Vue app has been instantiated, the language can be changed by calling $locale(args*) from your Vue instance or virtual node.

<button v-on:click="$locale({l: 'en-US'})">English</button>
<button v-on:click="$locale({l: 'es-SP'})">Spanish</button>

You can specify your localizations like so:

<!-- add a localized title to this element targeting en-US -->
<h1 v-localize="{i: 'header.title', t: 'en-US', attr: 'title'}">Hello World</h1>
<!-- replace this element's text with localized item -->
<h2 v-localize="{i: 'header.title'}"></h2>

Alternatively, you can get your current localization by calling $locale() without specifying a language.

<!-- fetch current locale -->
<h1>Locale: </h1>

For fetching a specific locale item programatically within a component method:

export default {
  name: 'some-component',
  methods: {
    getTitle() {
      window.alert(this.$locale({i: 'title'}))
    },
    getSpanishTitle() {
      window.alert(this.$locale({i: 'title', t: 'sp-ES'}))
    }
  }
}

Configuration

The plugin takes 5 options,

debug: If enabled, will spit warnings and errors to console.

default: Default language key to target if not set already.

available: List of available localizations, can optionally specify locale options. ex;
  ['en-US', 'es-SP', 'pr-BR', {
    locale: 'ar-MS',
    orientation: 'rtl'
  }]

fallbackContent: Use the existing node’s text content if enabled and requested localization is not found.

fallback: Default text to show if localization for current language not found. If not specified, will default to 'N/A'.

webStore: If the Vue instance is accessed within a web context and option webStore is enabled, plugin will store the locale in local storage for the next visit.

localizations: JSON object for localizations.

  {
    "en-US": { // language branch
      "header": "Hello World!", // localization
      "nav": {
        "home": "Home" // nested localization
      }
    }
  }

Locale Options

Locale configuration currently supports the following options,

orientation: Text direction of target element, useful for orientation of script languages.

font.family: Font family to change to. Re: https://www.w3schools.com/jsref/prop_style_fontfamily.asp

font.size: Font size to scale to. Re: https://www.w3schools.com/jsref/prop_style_fontsize.asp

Contributors

John Nolette (john@neetgroup.net)

Contributing guidelines are as follows,

Any new features must include either a unit test, e2e test, or both.
- Branches for bugs and features should be structured like so, issue-x-username.
Before putting in a pull request, be sure to verify you’ve built all your changes.

Travis will build your changes before testing and publishing, but bower pulls from this repository directly.
Include your name and email in the contributors list.