vue-intl

vue-intl

Vue Plugin for FormatJS Internalization and Localization

Install

npm install vue-intl

Usage

// assuming CommonJS
var Vue = require('vue');
var VueIntl = require('vue-intl');

// use globally
Vue.use(VueIntl);

N.B. The underlying suite, FormatJS, that the VueIntl plugin relies on, requires either a browser that supports the Intl API, or has the Intl Polyfill available. As such, it is necessary for cross browser support to load the Intl polyfill (or preferably to load it if needed).

See the FormatJS Documentation for more details.

Global API Methods

setLocale

Set the current locale for the page.

Vue.setLocale('fr');

Alternatively, use a more specific locale code.

Vue.setLocale('en-GB');

registerMessages

Set an object containing messages for a particular locale.

Vue.registerMessages('fr', {
    example_message_id: "La plume de ma tante est sur le bureau de mon oncle."
});

This message will now be available when the locale is set to 'fr'.

registerFormats

Create custom formats, see FormatJS main documentation for details.

Vue.registerFormats('fr', {
    number: {
        eur: { style: 'currency', currency: 'EUR' }
    }
});

This format will now be available when the locale is set to 'fr'.

Instance Methods

These methods are for actually performing localization and translation within the context of a Vue component.

The methods are set on the Vue instance prototype, so are available locally, with access to local variables.

$formatDate

This will format dates to the locale appropriate format.

<p v-html="$formatDate(now)"></p>

Where now is a Javascript Date object or a Date coercable Number or String.

Will output the following

<p>11-05-2016</p>

(if the locale is set to 'fr').

The method can also accept a second argument of an options object - the options follow the Intl.DateTimeFormat API.

<p v-html="$formatDate(now, { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' })"></p>

Will output the following

<p>Mittwoch, 11. Mai 2016</p>

(if the locale is set to 'de-DE').

Additionally, the method accepts an optional format argument that provides some commonly used date formats. These are described in the FormatJS main documentation.

$formatTime

This will format times to the locale appropriate format.

<p v-html="$formatTime(now, {format: 'short'})"></p>

These formats are described in the FormatJS main documentation.

Where now is a Javascript Date object or a Date coercable Number or String.

Will output the following

<p>19 h 00</p>

(if the locale is set to 'fr').

The other options follow the Intl.DateTimeFormat API.

$formatRelative

This will render date-times relative to page load time or to an inserted now option to the locale appropriate format.

<p v-html="$formatRelative(two_days_ago)"></p>

These formats are described in the FormatJS main documentation.

Will output the following

<p>2 days ago</p>

(if the locale is set to 'en-US').

The other options follow the Intl.DateTimeFormat API.

$formatNumber

This will set numbers to the locale appropriate format.

<p v-html="$formatNumber(number_of_things)"></p>

These formats are described in the FormatJS main documentation.

Will output the following

<p>17</p>

(if the locale is set to 'en-US').

<p v-html="$formatNumber(pct_of_things, {style: 'percent'})"></p>

Will output the following

<p>12%</p>

(if the locale is set to 'en-US').

The other options follow the Intl.NumberFormat API.

$formatPlural

This will format according to plural rules for the locale appropriate format.

<p v-html="$formatPlural(number_of_things, {style: 'cardinal')"></p>

These formats are described in the FormatJS main documentation.

Will output the following

<p>17</p>

(if the locale is set to 'fr-FR').

<p v-html="$formatPlural(number_of_things, {style: 'ordinal')"></p>

These formats are described in the FormatJS main documentation.

Will output the following

<p>17eme</p>

(if the locale is set to 'fr-FR').

$formatMessage

This will translate messages according to the locale appropriate format, it will also apply any pluralization rules in the message.

Messages are specified using ICU message syntax.

<p v-html="$formatMessage({id: 'example_message_id', defaultMessage: 'It\'s my cat\'s {year, selectordinal,
    one {#st}
    two {#nd}
    few {#rd}
    other {#th}
} birthday!'}, {year: year})"></p>

These formats are described in the FormatJS main documentation.

Will output the following

<p>It's my cat's 7th birthday!</p>

(if the locale is set to 'en').

$formatHTMLMessage

Identical to $formatMessage, except that it will escape HTML specific strings to render HTML directly in the message.

Loading additional locale data

By default, only the en specific locale data is included in vue-intl. In order to load locale data for other locales, for example for proper pluralization, ordinals, and relative time formatting, you must load the relevant locale data. Ideally, you would do this dynamically, depending on the locale that is currently in use (as all locale data for all locales is in excess of 1MB).

To use a specific locale, load the data from the relevant file:

import esLocaleData from 'vue-intl/locale-data/es';
import { addLocaleData } from 'vue-intl';

addLocaleData(esLocaleData);