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-ext/locale/es'
import de from 'dayjs-ext/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

• 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-ext/locale/es'
dayjs().locale('es').format() // use loaded locale locally
dayjs('2018-4-28', { locale: es }) // through constructor

Installation

• Via NPM:

import 'dayjs-ext/locale/es' // load on demand
// require('dayjs-ext/locale/es') // CommonJS
// import locale_es from 'dayjs-ext/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-ext"></script>
<!-- Load locale as window.dayjs_locale_NAME -->
<script src="https://unpkg.com/dayjs-ext/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
  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'
  },
  relativeTime: {
    // see below
  }
}

Old template of the part of a Day.js locale Object for the RelativeTime plugin. It works well for languages which do not decline nouns and which have only one form of plural. English, for example.

  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'
  }

New template of the part of a Day.js locale Object for the RelativeTime plugin. It works well for fusional languages which decline nouns and which have multiple plural forms. Slavic languages like Czech language, for example. The duration expressions will be used if the withoutSuffix parameter is set to true in the method calls.

  relativeTime: { // relative time format strings, keep %d as the same
    // Using 3 plural forms in Slavic languages
    duration: {
      // Static message, just one singular/plural form needed
      s: 'několik sekund',
      // Static message for a single minute without any number
      m: 'minuta',
      // Plural forms for 1, 2 to 4, and 5 and more minutes
      mm: ['%d minuta', '%d minuty', '%d minut'],
      h: 'hodina',
      hh: ['%d hodina', '%d hodiny', '%d hodin'],
      d: 'den',
      dd: ['%d den', '%d dny', '%d dní'],
      M: 'měsíc',
      MM: ['%d měsíc', '%d měsíce', '%d měsícú'],
      y: 'rok',
      yy: ['%d rok', '%d roky', '%d let']
    },
    future: {
      s: 'za několik sekund',
      m: 'za minutu',
      mm: ['za %d minutu', 'za %d minuty', 'za %d minut'],
      h: 'za hodinu',
      hh: ['za %d hodinu', 'za %d hodiny', 'za %d hodin'],
      d: 'zítra',
      dd: ['za %d den', 'za %d dny', 'za %d dní'],
      M: 'za měsíc',
      MM: ['za %d měsíc', 'za %d měsíce', 'za %d měsícú'],
      y: 'za rok',
      yy: ['za %d rok', 'za %d roky', 'za %d let']
    },
    past: {
      s: 'před několika sekundami',
      m: 'před minutou',
      mm: ['před %d minutou', 'před %d minutami', 'před %d minutami'],
      h: 'před hodinou',
      hh: ['před %d hodinou', 'před %d hodinami', 'před %d hodinami'],
      d: 'včera',
      dd: ['před %d dnem', 'před %d dny', 'před %d dny'],
      M: 'před měsícem',
      MM: ['před %d měsícem', 'před %d měsíci', 'před %d měsíci'],
      y: 'vloni',
      yy: ['před %d rokem', 'před %d roky', 'před %d lety']
    }
  }

The keys with single-letter time units point to a string shown for a single value, usually without any number. The keys with two-letter time units point to arrays with plural forms. Before you work on a new localization, make yourself familiar with plural rules and plural forms for the target language. You will find more information about plural rules and plural forms in the design of the library fast-plural-rules used for the grammatically correct localization of expressions with cardinal numbers.

Template of a Day.js locale file.

import dayjs from 'dayjs-ext'

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

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

export default locale