I18n.md

Internationalization

Day.js has great support for internationalization.

But none of them will be included in your build unless you use that.

By default, Day.js comes with English (United States) locale.

You can load multiple locales and switch between them easily.

List of supported locales

You are super welcome to add a locale by opening a pull request 👍

API

Changing locale globally

• Returns locale string

import 'dayjs/locale/es'
import de from 'dayjs/locale/de'
dayjs.locale('es') // use loaded locale globally
dayjs.locale('de-german', de) // use locale and update default name string
const customizedLocaleObject = { ... } // More details can be found in Customize section below.
dayjs.locale(customizedLocaleObject) // use customize locale
dayjs.locale('en') // switch back to default English locale globally

• Changing the global locale doesn't affect existing instances.

Changing locales locally

• Returns a new Dayjs object by switching to new locale.

Exactly the same as dayjs#locale, but only use locale in a specific instance.

import 'dayjs/locale/es'
dayjs()
  .locale('es')
  .format() // use loaded locale locally
dayjs('2018-4-28', { locale: 'es' }) // through constructor

Installation

• Via NPM:

import 'dayjs/locale/es' // load on demand
// require('dayjs/locale/es') // CommonJS
// import locale_es from 'dayjs/locale/es' -> load and get locale_es locale object

dayjs.locale('es') // use locale globally
dayjs()
  .locale('es')
  .format() // use locale in a specific instance

• Via CDN:

<script src="https://unpkg.com/dayjs"></script>
<!-- Load locale as window.dayjs_locale_NAME -->
<script src="https://unpkg.com/dayjs/locale/zh-cn"></script>
<script>
  dayjs.locale('zh-cn')
  dayjs()
    .locale('zh-cn')
    .format()
  // get locale object
  var customLocale = window.dayjs_locale_zh_cn // zh-cn -> zh_cn
</script>

Customize

You could create your own locale.

Feel free to open a pull request to share your locale.

Template of a Day.js locale Object.

const localeObject = {
  name: 'es', // name String
  weekdays: 'Domingo_Lunes ...'.split('_'), // weekdays Array
  weekdaysShort: 'Sun_M'.split('_'), // OPTIONAL, short weekdays Array, use first three letters if not provided
  weekdaysMin: 'Su_Mo'.split('_'), // OPTIONAL, min weekdays Array, use first two letters if not provided
  weekStart: 1, // OPTIONAL, set the start of a week. If the value is 1, Monday will be the start of week instead of Sunday。
  months: 'Enero_Febrero ... '.split('_'), // months Array
  monthsShort: 'Jan_F'.split('_'), // OPTIONAL, short months Array, use first three letters if not provided
  ordinal: n => `${n}º`, // ordinal Function (number) => return number + output
  formats: {
    // abbreviated format options allowing localization
    LTS: 'h:mm:ss A',
    LT: 'h:mm A',
    L: 'MM/DD/YYYY',
    LL: 'MMMM D, YYYY',
    LLL: 'MMMM D, YYYY h:mm A',
    LLLL: 'dddd, MMMM D, YYYY h:mm A',
    // lowercase/short, optional formats for localization
    l: 'D/M/YYYY',
    ll: 'D MMM, YYYY',
    lll: 'D MMM, YYYY h:mm A',
    llll: 'ddd, MMM D, YYYY h:mm A'
  },
  relativeTime: {
    // relative time format strings, keep %s %d as the same
    future: 'in %s', // e.g. in 2 hours, %s been replaced with 2hours
    past: '%s ago',
    s: 'a few seconds',
    m: 'a minute',
    mm: '%d minutes',
    h: 'an hour',
    hh: '%d hours', // e.g. 2 hours, %d been replaced with 2
    d: 'a day',
    dd: '%d days',
    M: 'a month',
    MM: '%d months',
    y: 'a year',
    yy: '%d years'
  }
}

Template of a Day.js locale file.

import dayjs from 'dayjs'

const locale = { ... } // Your Day.js locale Object.

dayjs.locale(locale, null, true) // load locale for later use

export default locale