# API references
# Extension of Vue
# Vue constructor options
# i18n
- Type:
I18nOptions
Component based localization option.
- See also:
VueI18n
class constructor options
# Vue injected methods
# $t
Arguments:
{Path} key
: required{Locale} locale
: optional{Array | Object} values
: optional
Return:
TranslateResult
Localize the locale message of key
. Localize in preferentially component locale messages than global locale messages. If not specified component locale messages, localize with global locale messages. If you specified locale
, localize the locale messages of locale
. If you specified key
of list / named formatting local messages, you must specify values
too. For values
more details see Formatting.
If default pluralization does not suit your needs, see pluralization rules in constructor options and custom pluralization.
Tip
Note that you need to guarantee this context equal to component instance in lifecycle methods (e.g. in data
options, const $t = this.$t.bind(this)
).
# $tc
Arguments:
{Path} key
: required{number} choice
: optional, default 1{Locale} locale
: optional{string | Array | Object} values
: optional
Return:
TranslateResult
Localize the locale message of key
with pluralization. Localize in preferentially component locale messages than global locale messages. If not specified component locale messages, localize with global locale messages. If you specified locale
, localize the locale messages of locale
. If you will specify string value to values
, localize the locale messages of value. If you will specify Array or Object value to values
, you must specify with values
of $t.
Tip
Note that you need to guarantee this context equal to component instance in lifecycle methods (e.g. in data
options, const $tc = this.$tc.bind(this)
).
# $te
Arguments:
{Path} key
: required{Locale} locale
: optional
Return:
boolean
Check whether key exists. In Vue instance, If not specified component locale messages, check with global locale messages. If you specified locale
, check the locale messages of locale
.
Tip
Note that you need to guarantee this context equal to component instance in lifecycle methods (e.g. in data
options, const $te = this.$te.bind(this)
).
# $d
🆕 7.0+
Arguments:
{number | Date} value
: required{Path | Object} key
: optional{Locale | Object} locale
: optional
Return:
DateTimeFormatResult
Localize the datetime of value
with datetime format of key
. The datetime format of key
need to register to dateTimeFormats
option of VueI18n
class, and depend on locale
option of VueI18n
constructor. If you will specify locale
argument, it will have priority over locale
option of VueI18n
constructor.
If the datetime format of key
not exist in dateTimeFormats
option, fallback to depend on fallbackLocale
option of VueI18n
constructor.
Tip
Note that you need to guarantee this context equal to component instance in lifecycle methods (e.g. in data
options, const $d = this.$d.bind(this)
).
# $n
🆕 7.0+
Arguments:
{number} value
: required{Path | Object} format
: optional{Locale} locale
: optional
Return:
NumberFormatResult
Localize the number of value
with number format of format
. The number format of format
need to register to numberFormats
option of VueI18n
class, and depend on locale
option of VueI18n
constructor. If you will specify locale
argument, it will have priority over locale
option of VueI18n
constructor.
If the number format of format
not exist in numberFormats
option, fallback to depend on fallbackLocale
option of VueI18n
constructor.
If the second format
argument specified as an object, it should have the following properties:
key {Path}
: optional, number formatlocale {Locale}
: optional, localecompactDisplay {string}
: optional, number format optioncurrency {string}
: optional, number format optioncurrencyDisplay {string}
: optional, number format optioncurrencySign {string}
: optional, number format optionlocaleMatcher {string}
: optional, number format optionnotation {string}
: optional, number format optionnumberingSystem {string}
: optional, number format optionsignDisplay {string}
: optional, number format optionstyle {string}
: optional, number format optionunit {string}
: optional, number format optionunitDisplay {string}
: optional, number format optionuseGrouping {boolean}
: optional, number format optionminimumIntegerDigits {string}
: optional, number format optionminimumFractionDigits {string}
: optional, number format optionmaximumFractionDigits {string}
: optional, number format optionminimumSignificantDigits {string}
: optional, number format optionmaximumSignificantDigits {string}
: optional, number format option
Any specified number format options will have priority over numberFormats
of VueI18n
constructor.
Tip
Note that you need to guarantee this context equal to component instance in lifecycle methods (e.g. in data
options, const $n = this.$n.bind(this)
).
# Injected properties
# $i18n
Type:
I18n
Read only
Get a VueI18n
instance. If you are specify.
If you have specified an i18n
option at component options, you will be able to get a VueI18n
instance at the component, Otherwise, you will be able get root VueI18n
instance.
# VueI18n
class
VueI18n
class implement I18n
interface of flowtype definitions (opens new window)
# Static properties
# version
- Type:
string
vue-i18n version.
# availabilities
🆕 7.0+
- Type:
IntlAvailability
Whether the following internationalization features are available:
{boolean} dateTimeFormat
: locale sensitive datetime formatting{boolean} numberFormat
: locale sensitive number formatting
The above internationalization features are depends on the browser environments (opens new window), due to implement with ECMAScript Internationalization API (ECMA-402).
# Constructor options
You can specify the below some options of I18nOptions
constructor options of flowtype definitions (opens new window)
# locale
Type:
Locale
Default:
'en-US'
The locale of localization. If the locale contains a territory and a dialect, this locale contains an implicit fallback.
# fallbackLocale
Type:
FallbackLocale
Default:
false
The locale of fallback localization. For more complex fallback definitions see fallback.
# messages
Type:
LocaleMessages
Default:
{}
The locale messages of localization.
# dateTimeFormats
🆕 7.0+
Type:
DateTimeFormats
Default:
{}
The datetime formats of localization.
- See also:
DateTimeFormats
type of flowtype definitions (opens new window)
# numberFormats
🆕 7.0+
Type:
NumberFormats
Default:
{}
The number formats of localization.
- See also:
NumberFormats
type of flowtype definitions (opens new window)
# formatter
Type:
Formatter
Default: Built in formatter
The formatter that implemented with Formatter
interface.
# modifiers
🆕 8.15.0+
Type:
Modifiers
Default:
lower
andupper
modifiers
Modifiers functions for linked messages
# missing
Type:
MissingHandler
Default:
null
A handler for localization missing. The handler gets called with the localization target locale, localization path key, the Vue instance and values.
If missing handler is assigned, and occurred localization missing, it's not warned.
# fallbackRoot
Type:
Boolean
Default:
true
In the component localization, whether to fall back to root level (global) localization when localization fails.
If false
, it's warned, and is returned the key.
# fallbackRootWithEmptyString
🆕 8.26+
Type:
Boolean
Default:
true
In the component localization, whether to fall back to root level (global) localization when local message is an empty string.
Please note the default behavior in vue-i18n 9.x is to not falling back to root for local message that is empty string.
If
false
, the empty local message will not fall back to root and will be kept as empty string.
# sync
Type:
Boolean
Default:
true
Whether synchronize the root level locale to the component localization locale.
If false
, regardless of the root level locale, localize for each component locale.
# silentTranslationWarn
6.1+, 🆙 8.13
Type:
Boolean | RegExp
Default:
false
Whether suppress warnings outputted when localization fails.
If true
, suppress localization fail warnings.
If you use regular expression, you can suppress localization fail warnings that it match with translation key
(e.g. $t
).
# silentFallbackWarn
🆕 8.8+, 🆙 8.13
- Type:
Boolean | RegExp
- Default:
false
Whether suppress warnings when falling back to either fallbackLocale
or root
.
If true
, warnings will be generated only when no translation is available at all, and not for fallbacks.
If you use regular expression, you can suppress the fallback warnings that it match key
(e.g. $t
).
# pluralizationRules
8.5+
Type:
PluralizationRules
Default:
{}
A set of rules for word pluralization in a following format:
{
// Key - locale for the rule to be applied to.
// Value - mapping function that maps a choice index from `$tc` to the actual choice of the plural word. (See getChoiceIndex for details)
'pt': function(choice, choiceIndex) => Number/* index of the plural word */;
'ru': function(choice, choiceIndex) => Number/* index of the plural word */;
'en': function(choice, choiceIndex) => Number/* index of the plural word */;
'jp': function(choice, choiceIndex) => Number/* index of the plural word */;
}
# preserveDirectiveContent
8.7+
Type:
Boolean
Default:
false
Whether v-t
directive's element should preserve textContent
after directive is unbinded.
# warnHtmlInMessage
8.11+
Type:
WarnHtmlInMessageLevel
Default:
off
Whether to allow the use locale messages of HTML formatting. See the warnHtmlInMessage
property.
Important!!
In next major version, warnHtmlInMessage
option is warn
as default.
# sharedMessages
8.12+
Type:
LocaleMessages
Default:
undefined
The shared locale messages of localization for components. More detail see Component based localization.
# postTranslation
8.16+
Type:
PostTranslationHandler
Default:
null
A handler for post processing of translation. The handler gets after being called with the $t
, t
, $tc
, and tc
.
This handler is useful if you want to filter on translated text such as space trimming.
# componentInstanceCreatedListener
8.18+
Type:
ComponentInstanceCreatedListener
Default:
null
A handler for getting notified when component-local instance was created. The handler gets called with new and old (root) VueI18n instances.
This handler is useful when extending the root VueI18n instance and wanting to also apply those extensions to component-local instance.
# escapeParameterHtml
8.22+
Type:
Boolean
Default:
false
If escapeParameterHtml
is configured as true then interpolation parameters are escaped before the message is translated.
This is useful when translation output is used in v-html
and the translation resource contains html markup (e.g. <b>
around a user provided value). This usage pattern mostly occurs when passing precomputed text strings into UI compontents.
The escape process involves replacing the following symbols with their respective HTML character entities: <
, >
, "
, '
.
Setting escapeParameterHtml
as true should not break existing functionality but provides a safeguard against a subtle
type of XSS attack vectors.
# Properties
# locale
Type:
Locale
Read/Write
The locale of localization. If the locale contains a territory and a dialect, this locale contains an implicit fallback.
# fallbackLocale
Type:
FallbackLocale
Read/Write
The locale of fallback localization. For more complex fallback definitions see fallback.
# messages
Type:
LocaleMessages
Read only
The locale messages of localization.
# dateTimeFormats
🆕 7.0+
Type:
DateTimeFormats
Read only
The datetime formats of localization.
# numberFormats
🆕 7.0+
Type:
NumberFormats
Read only
The number formats of localization.
# availableLocales
🆕 8.9.0+
Type:
Locale[]
Read only
The list of available locales in messages
in lexical order.
# missing
Type:
MissingHandler
Read/Write
A handler for localization missing.
# formatter
Type:
Formatter
Read/Write
The formatter that implemented with Formatter
interface.
# silentTranslationWarn
6.1+, 🆙 8.13
Type:
Boolean | RegExp
Read/Write
Whether suppress warnings outputted when localization fails.
# silentFallbackWarn
🆕 8.8+, 🆙 8.13
Type:
Boolean | RegExp
Read/Write
Whether suppress fallback warnings when localization fails.
# pluralizationRules
8.5+
Type:
PluralizationRules
Read/Write
A set of locale-dependent rules for word pluralization.
# preserveDirectiveContent
8.7+
Type:
Boolean
Read/Write
Whether v-t
directive's element should preserve textContent
after directive is unbinded.
# warnHtmlInMessage
8.11+
Type:
WarnHtmlInMessageLevel
Read/Write
Whether to allow the use locale messages of HTML formatting.
If you set warn
orerror
, will check the locale messages on the VueI18n instance.
If you are specified warn
, a warning will be output at console.
If you are specified error
will occurred an Error.
In VueI18n instance, set the off
as default.
# postTranslation
8.16+
Type:
PostTranslationHandler
Read/Write
A handler for post processing of translation.
# Methods
# getChoiceIndex
Arguments:
{number} choice
{number} choicesLength
Return:
finalChoice {number}
Get pluralization index for current pluralizing number and a given amount of choices. Can be overridden through prototype mutation:
VueI18n.prototype.getChoiceIndex = /* custom implementation */
However, for most usages pluralizationRules constructor option should be enough.
# getLocaleMessage( locale )
Arguments:
{Locale} locale
Return:
LocaleMessageObject
Get the locale message of locale.
# setLocaleMessage( locale, message )
Arguments:
{Locale} locale
{LocaleMessageObject} message
Set the locale message of locale.
NOTE
8.11+
If you set warn
orerror
in the warnHtmlInMessage
property, when this method is executed, it will check if HTML formatting is used for locale message.
# mergeLocaleMessage( locale, message )
6.1+
Arguments:
{Locale} locale
{LocaleMessageObject} message
Merge the registered locale messages with the locale message of locale.
NOTE
8.11+
If you set warn
orerror
in the warnHtmlInMessage
property, when this method is executed, it will check if HTML formatting is used for locale message.
# t( key, [locale], [values] )
Arguments:
{Path} key
: required{Locale} locale
: optional{Array | Object} values
: optional
Return: :
TranslateResult
This is the same as the Function
returned with $t
method. More detail see $t.
# tc( key, [choice], [values] )
Arguments:
{Path} key
: required{number} choice
: optional, default1
{string | Array | Object} values
: optional
Return:
TranslateResult
This is the same as the Function
returned $tc
method. More detail see $tc.
# te( key, [locale] )
Arguments:
{string} key
: required{Locale} locale
: optional
Return:
boolean
Check whether key path exists in global locale message. If you specified locale
, check the locale message of locale
.
# getDateTimeFormat ( locale )
🆕 7.0+
Arguments:
{Locale} locale
Return:
DateTimeFormat
Get the datetime format of locale.
# setDateTimeFormat ( locale, format )
🆕 7.0+
Arguments:
{Locale} locale
{DateTimeFormat} format
Set the datetime format of locale.
# mergeDateTimeFormat ( locale, format )
🆕 7.0+
Arguments:
{Locale} locale
{DateTimeFormat} format
Merge the registered datetime formats with the datetime format of locale.
# d( value, [key], [locale] )
🆕 7.0+
Arguments:
{number | Date} value
: required{Path | Object} key
: optional{Locale | Object} locale
: optional
Return:
DateTimeFormatResult
This is the same as $d
method of Vue instance method. More detail see $d.
# getNumberFormat ( locale )
🆕 7.0+
Arguments:
{Locale} locale
Return:
NumberFormat
Get the number format of locale.
# setNumberFormat ( locale, format )
🆕 7.0+
Arguments:
{Locale} locale
{NumberFormat} format
Set the number format of locale.
# mergeNumberFormat ( locale, format )
🆕 7.0+
Arguments:
{Locale} locale
{NumberFormat} format
Merge the registered number formats with the number format of locale.
# n( value, [format], [locale] )
🆕 7.0+
Arguments:
{number} value
: required{Path | Object} format
: optional{Locale} locale
: optional
Return:
NumberFormatResult
This is the same as $n
method of Vue instance method. More detail see $n.
# Directives
🆕 7.3+
# v-t
Expects:
string | Object
Modifiers:
.preserve
: (8.7.0+) preserves elementtextContent
when directive is unbinded.
Details:
Update the element textContent
that localized with locale messages. You can use string syntax or object syntax. string syntax can be specified as a keypath of locale messages. If you can be used object syntax, you need to specify as the object key the following params:
path
: required, key of locale messageslocale
: optional, localeargs
: optional, for list or named formatting
NOTE
The element textContent
will be cleared by default when v-t
directive is unbinded. This might be undesirable situation when used inside transitions (opens new window). To preserve textContent
data after directive unbind use .preserve
modifier or global preserveDirectiveContent
option.
- Examples:
<!-- string syntax: literal -->
<p v-t="'foo.bar'"></p>
<!-- string syntax: binding via data or computed props -->
<p v-t="msg"></p>
<!-- object syntax: literal -->
<p v-t="{ path: 'hi', locale: 'ja', args: { name: 'kazupon' } }"></p>
<!-- object syntax: binding via data or computed props -->
<p v-t="{ path: greeting, args: { name: fullName } }"></p>
<!-- with preserve modifier -->
<p v-t.preserve="'foo.bar'"></p>
- See also: Custom directive localization
# Components
# i18n functional component
🆕 7.0+
# Props:
path {Path}
: required, keypath of locale messageslocale {Locale}
: optional, localetag {string | boolean | Object}
: optional, default'span'
places {Array | Object}
: optional (7.2+)
Important!!
In next major version, places
prop is deprecated. Please switch to slots syntax.
# Usage:
<div id="app">
<!-- ... -->
<i18n path="term" tag="label" for="tos">
<a :href="url" target="_blank">{{ $t('tos') }}</a>
</i18n>
<!-- ... -->
</div>
const messages = {
en: {
tos: 'Term of Service',
term: 'I accept xxx {0}.'
},
ja: {
tos: '利用規約',
term: '私は xxx の{0}に同意します。'
}
}
const i18n = new VueI18n({
locale: 'en',
messages
})
new Vue({
i18n,
data: {
url: '/term'
}
}).$mount('#app')
# See also:
# i18n-n functional component
🆕 8.10+
# Props:
value {number}
: required, number to formatformat {string | NumberFormatOptions}
: optional, number format name or object with explicit format optionslocale {Locale}
: optional, localetag {string | boolean | Object}
: optional, default'span'
# Usage:
<div id="app">
<!-- ... -->
<i18n-n :value="money" format="currency" tag="label">
<span v-slot:currency="slotProps" class="font-weight: bold">{{ slotProps.currency }}<span>
</i18n-n>
<!-- ... -->
</div>
var numberFormats = {
'en-US': {
currency: {
style: 'currency', currency: 'USD'
}
},
'ja-JP': {
currency: {
style: 'currency', currency: 'JPY'
}
}
}
const i18n = new VueI18n({
locale: 'en-US',
numberFormats
})
new Vue({
i18n,
data: {
money: 10234,
}
}).$mount('#app')
# Scoped slots
<i18n-n>
functional component can accept a number of named scoped slots. List of supported slot names is based on Intl.NumberFormat.formatToParts()
output types (opens new window):
currency
decimal
fraction
group
infinity
integer
literal
minusSign
nan
plusSign
percentSign
Each of these named scoped slots will accept three scope parameters:
[slotName] {FormattedNumberPartType}
: parameter of the same name as actual slot name (likeinteger
)index {Number}
: index of the specific part in the array of number partsparts {Array}
: array of all formatted number parts
# See also:
# Special Attributes
# place
🆕 7.2+
# Expects: {number | string}
Used on component interpolation to indicate which index of list formatting or key of named formatting.
For detailed usage, see the guide section linked below.