i18n

VCalendar utilizes the well supported Internationalization API to derive month and weekday names and formatting. This helps keep the package size down, as well as supporting multiple locales in the most performant and isomorphic way.

Locales

A locale includes multiple settings that are typically assigned on a per region basis. This currently includes the following:

Setting Description
firstDayOfWeek The day the specified the first day of the week. This is a number from 1 to 7 (Sunday to Saturday, respectfully).
masks Set of masks to use for common sections of the calendar including the title, weekday labels, month labels in the navigation pane and more.
dayNames Full length identifiers for the days of the week.
dayNamesShort 3-character identifiers for the days of the week.
dayNamesShorter 2-character identifiers for the days of the week.
dayNamesNarrow 1-character identifiers for the days of the week.
monthNames Full length identifiers for the months of the year.
monthNamesShort Abbreviated identifiers for the months of the year.

There are multiple ways which you can configure the locale for a specific calendar. Locales may be configured globally via the defaults object as well as on a per-calendar basis with the locale prop.

No specified locale

<v-calendar />

With no locale specified, the locale detected by the Internationalization API is used.

No specified locale w/ override props

<v-calendar :first-day-of-week="2" :masks="{ title: 'MMM YYYY' }" />
Jan 2020
M
T
W
T
F
S
S
30
31
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
9

Uses the detected locale with customized firstDayOfWeek or masks that will override the built-in locale settings. When using a customized masks prop, the default masks will supply any masks that are missing, so you are free to provide single overrides.

String Locale

<v-calendar locale="es" />
January 2020
S
M
T
W
T
F
S
29
30
31
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8

With a string locale, the locale with the matching identifier is used. The Internationalization API is used to generate the dayNames, dayNamesShort, dayNamesShorter, dayNamesNarrow, monthNames and monthNamesShort properties. Because the API does not provide common values for the firstDayOfWeek or masks these are loaded from the plugin defaults (unless specifically provided via props).

Object Locale

<v-calendar :locale="{ id: 'da', firstDayOfWeek: 2, masks: { weekdays: 'WW' } }" />
January 2020
Mo
Tu
We
Th
Fr
Sa
Su
30
31
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
9

With an object locale, you can simply provide all the settings you need together in a single object. Note that firstDayOfWeek and masks props will override this object.

Providing default locales for all calendars

More conveniently, you may override or provide missing locale information via the locales property of the defaults object when using VCalendar. This should be an object with the locale identifier as the key and an object with the locale settings.

import Vue from 'vue'
import VCalendar from 'v-calendar'

Vue.use(VCalendar, {
  locales: {
    'pt-PT': {
      firstDayOfWeek: 1,
      masks: {
        L: 'YYYY-MM-DD',
        // ...optional `title`, `weekdays`, `navMonths`, etc
      }
    }
  }
});

Then, all you need to do is reference your locale when using the calendar component.

<v-calendar locale="pt-PT" />
January 2020
S
M
T
W
T
F
S
29
30
31
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8

Formatting & Parsing Dates

As mentioned before, the locale masks are used to properly format and/or parse dates for the following calendar sections:

Property Name Target Area Default Mask
title Calendar header title "MMMM YYYY"
weekdays Weekday headers "W"
navMonths Month labels in navigation dropdown "MMM"
dayPopover Date in day popover when user hovers selected date. "WWW, MMM D, YYYY"
input Input element text when is-inline === false. (v-date-picker only) ["L", "YYYY-MM-DD", "YYYY/MM/DD"]
data Parses attribute dates, if needed ["L", "YYYY-MM-DD", "YYYY/MM/DD"]

Parsing using multiple masks

You'll notice an array was used to specify the input mask for v-date-picker. This is because it uses the supplied masks(s) to parse, as well as display, the selected date. The first supplied mask is used to display the date selection, while all masks are used (from first to last) to parse the date string. The first successfully parsed date is used as the selected date. This provides more flexibility for the user when manually typing in dates.

By default, v-date-picker will first try and use the localized long date mask to parse the date, but will also try to parse masks that are globally unambiguous (YYYY-MM-DD and YYYY/MM/DD). Furthermore, because v-date-picker uses its own parsing logic (rather than relying on the browser's inconsistent Date.parse function), it can properly parse ISO-8601 dates to the user's local time zone instead of converting to UTC. If you plan on targeting browsers from multiple locales, it is probably best to defer to the default mask settings.

Mask Tokens

Use the following tokens to configure your custom masks:

Token Output
Month M 1, 2, ..., 12
MM 01, 02, ..., 12
MMM Jan, Feb, ..., Dec
MMMM January, February, ..., December
Day of Month D 1, 2, ..., 31
DD 01, 02, ..., 31
Do 1st, 2nd, ..., 31st
Day of Week d 1, 2, ..., 7
d 1, 2, ..., 7
dd 01, 02, ..., 07
W S, M, ..., S
WW Su, Mo, ..., Sa
WWW Sun, Mon, ..., Sat
WWWW Sunday, Monday, ..., Saturday
Year YY 70, 71, ... 69
YYYY 1970, 1971, ..., 2069
Long Date L 01/21/1983 (en-US), 21/01/1983 (en-GB), ..., 1983/01/21 (civilized)

With all of this in mind, it is probably best that you rely on the the plugin's built-in methods for detecting the user's locale. However, if you would like to force a specific locale for all users, you may supply your own default locale using the language-region format.