Доступные локали

Локаль определяет формат отображения даты и времени в зависимости от языка и региональных стандартов. Через локали управляются:

  • названия месяцев;
  • названия дней недели;
  • формат дат;
  • сокращения;
  • правила отображения относительного времени;
  • локализованные шаблоны форматирования.

Библиотека Day.js поставляется с большим количеством встроенных локалей, которые подключаются отдельно для уменьшения итогового размера бандла.

Подключение локали

По умолчанию Day.js использует английскую локаль (en).

Для подключения другой локали необходимо импортировать соответствующий модуль.

Node.js

const dayjs = require('dayjs')

require('dayjs/locale/ru')

dayjs.locale('ru')

console.log(dayjs().format('MMMM'))

ES Modules

import dayjs from 'dayjs'
import 'dayjs/locale/ru'

dayjs.locale('ru')

console.log(dayjs().format('MMMM'))

После установки локали все новые экземпляры Day.js начинают использовать выбранный язык.

Использование локали

Глобальная локаль

Метод dayjs.locale() изменяет локаль глобально.

import dayjs from 'dayjs'
import 'dayjs/locale/de'

dayjs.locale('de')

console.log(dayjs().format('dddd'))

Результат:

Sonntag

Локаль только для конкретного экземпляра

Локаль можно назначить отдельному объекту даты без изменения глобальных настроек.

import dayjs from 'dayjs'
import 'dayjs/locale/fr'

const date = dayjs().locale('fr')

console.log(date.format('MMMM'))

Результат:

janvier

При этом глобальная локаль останется неизменной.

Получение текущей локали

Глобальная локаль

console.log(dayjs.locale())

Локаль экземпляра

const date = dayjs()

console.log(date.locale())

Список популярных локалей

Day.js поддерживает десятки языков и регионов.

Русский

import 'dayjs/locale/ru'

Английский

import 'dayjs/locale/en'

Немецкий

import 'dayjs/locale/de'

Французский

import 'dayjs/locale/fr'

Испанский

import 'dayjs/locale/es'

Китайский

import 'dayjs/locale/zh-cn'

Японский

import 'dayjs/locale/ja'

Итальянский

import 'dayjs/locale/it'

Португальский

import 'dayjs/locale/pt'

Украинский

import 'dayjs/locale/uk'

Форматирование с учётом локали

После подключения локали методы форматирования начинают возвращать локализованные значения.

import dayjs from 'dayjs'
import 'dayjs/locale/ru'

dayjs.locale('ru')

console.log(dayjs('2025-03-12').format('D MMMM YYYY'))

Результат:

12 марта 2025

Локализованные названия месяцев

Полное название месяца

dayjs().format('MMMM')

Пример для русской локали:

май

Краткое название месяца

dayjs().format('MMM')

Пример:

мая

Локализованные дни недели

Полное название дня

dayjs().format('dddd')

Краткое название дня

dayjs().format('ddd')

Минимальное сокращение

dayjs().format('dd')

Локализованные форматы даты

Для работы с локализованными шаблонами используется плагин LocalizedFormat.

Подключение плагина

import dayjs from 'dayjs'
import localizedFormat from 'dayjs/plugin/localizedFormat'

dayjs.extend(localizedFormat)

Использование локализованных шаблонов

console.log(dayjs().format('L'))
console.log(dayjs().format('LL'))
console.log(dayjs().format('LLL'))
console.log(dayjs().format('LLLL'))

Значения локализованных шаблонов

Форматы зависят от текущей локали.

Для английской локали

08/16/2025
August 16, 2025
August 16, 2025 1:30 PM
Saturday, August 16, 2025 1:30 PM

Для русской локали

16.08.2025
16 августа 2025 г.
16 августа 2025 г., 13:30
суббота, 16 августа 2025 г., 13:30

Относительное время и локали

Для локализованного отображения относительного времени используется плагин RelativeTime.

Подключение

import dayjs from 'dayjs'
import relativeTime from 'dayjs/plugin/relativeTime'

dayjs.extend(relativeTime)

Пример использования

import 'dayjs/locale/ru'

dayjs.locale('ru')

console.log(dayjs().from(dayjs().subtract(3, 'day')))

Результат:

3 дня назад

Отображение времени в будущем

console.log(dayjs().to(dayjs().add(2, 'hour')))

Результат:

через 2 часа

Изменение локали во время выполнения

Локаль можно переключать динамически.

import dayjs from 'dayjs'

import 'dayjs/locale/ru'
import 'dayjs/locale/en'

dayjs.locale('ru')

console.log(dayjs().format('MMMM'))

dayjs.locale('en')

console.log(dayjs().format('MMMM'))

Результат:

май
May

Работа с несколькими локалями одновременно

Разные экземпляры могут использовать разные локали.

import dayjs from 'dayjs'

import 'dayjs/locale/ru'
import 'dayjs/locale/fr'
import 'dayjs/locale/de'

const ruDate = dayjs().locale('ru')
const frDate = dayjs().locale('fr')
const deDate = dayjs().locale('de')

console.log(ruDate.format('MMMM'))
console.log(frDate.format('MMMM'))
console.log(deDate.format('MMMM'))

Загрузка локалей только при необходимости

В крупных приложениях часто используется динамический импорт.

async function setLocale(locale) {
    await import(`dayjs/locale/${locale}.js`)

    dayjs.locale(locale)
}

await setLocale('ru')

Такой подход уменьшает размер первоначального JavaScript-бандла.

Локали и браузер пользователя

Язык браузера можно использовать автоматически.

const locale = navigator.language

console.log(locale)

Применение локали браузера

import dayjs from 'dayjs'

const locale = navigator.language.toLowerCase()

await import(`dayjs/locale/${locale}.js`)

dayjs.locale(locale)

Fallback-локаль

Не все языки могут быть доступны. Часто применяется резервная локаль.

async function loadLocale(locale) {
    try {
        await import(`dayjs/locale/${locale}.js`)
        dayjs.locale(locale)
    } catch {
        dayjs.locale('en')
    }
}

Просмотр данных локали

Метод localeData() предоставляет доступ к внутренним данным локали.

Для этого используется плагин LocaleData.

Подключение

import localeData from 'dayjs/plugin/localeData'

dayjs.extend(localeData)

Получение месяцев

console.log(dayjs.months())

Результат:

[
  'January',
  'February',
  'March'
]

Получение сокращённых месяцев

console.log(dayjs.monthsShort())

Получение дней недели

console.log(dayjs.weekdays())

Получение коротких дней недели

console.log(dayjs.weekdaysShort())

Минимальные названия дней

console.log(dayjs.weekdaysMin())

Первый день недели

console.log(dayjs.localeData().firstDayOfWeek())

Для разных локалей значение отличается:

  • США — воскресенье;
  • Россия — понедельник;
  • Германия — понедельник.

Обновление существующей локали

Для изменения локали используется плагин UpdateLocale.

Подключение

import updateLocale from 'dayjs/plugin/updateLocale'

dayjs.extend(updateLocale)

Изменение названий месяцев

dayjs.updateLocale('en', {
    months: [
        'Jan_Custom',
        'Feb_Custom',
        'Mar_Custom',
        'Apr_Custom',
        'May_Custom',
        'Jun_Custom',
        'Jul_Custom',
        'Aug_Custom',
        'Sep_Custom',
        'Oct_Custom',
        'Nov_Custom',
        'Dec_Custom'
    ]
})

Изменение первого дня недели

dayjs.updateLocale('ru', {
    weekStart: 1
})

Настройка относительного времени

dayjs.updateLocale('ru', {
    relativeTime: {
        future: 'через %s',
        past: '%s назад',
        s: 'несколько секунд',
        m: 'минута',
        mm: '%d минут',
        h: 'час',
        hh: '%d часов'
    }
})

Создание собственной локали

Локаль можно определить вручную.

dayjs.locale({
    name: 'custom',
    weekdays: [
        'Day1',
        'Day2',
        'Day3',
        'Day4',
        'Day5',
        'Day6',
        'Day7'
    ],
    months: [
        'Month1',
        'Month2',
        'Month3',
        'Month4',
        'Month5',
        'Month6',
        'Month7',
        'Month8',
        'Month9',
        'Month10',
        'Month11',
        'Month12'
    ]
})

Использование собственной локали

dayjs.locale('custom')

console.log(dayjs().format('MMMM'))

Региональные различия

Некоторые языки имеют несколько региональных вариантов.

Примеры

'en'
'en-gb'
'pt'
'pt-br'
'zh-cn'
'zh-tw'

Разница между en и en-gb

dayjs.locale('en')
console.log(dayjs('2025-01-15').format('L'))

Результат:

01/15/2025
dayjs.locale('en-gb')
console.log(dayjs('2025-01-15').format('L'))

Результат:

15/01/2025

Проверка доступности локали

if (dayjs.Ls['ru']) {
    console.log('Локаль доступна')
}

Список загруженных локалей

console.log(dayjs.Ls)

Объект содержит все локали, загруженные в текущее приложение.

Локали и TypeScript

Подключение локали

import dayjs from 'dayjs'
import 'dayjs/locale/ru'

dayjs.locale('ru')

Типизация пользовательской локали

import { Locale } from 'dayjs'

const customLocale: Partial<Locale> = {
    name: 'custom'
}

Особенности локалей в Day.js

Локали не подключаются автоматически

Каждая локаль импортируется отдельно:

import 'dayjs/locale/ru'

Глобальная локаль не влияет на уже созданные объекты

const date = dayjs()

dayjs.locale('ru')

console.log(date.format('MMMM'))

Экземпляр сохранит локаль, которая была активна во время его создания.

Локаль экземпляра имеет приоритет

const date = dayjs().locale('fr')

dayjs.locale('ru')

console.log(date.format('MMMM'))

Результат будет на французском языке.

Практический пример мультиязычного интерфейса

import dayjs from 'dayjs'

import 'dayjs/locale/en'
import 'dayjs/locale/ru'
import 'dayjs/locale/de'

function formatDate(date, lang) {
    return dayjs(date)
        .locale(lang)
        .format('LL')
}

console.log(formatDate(new Date(), 'ru'))
console.log(formatDate(new Date(), 'en'))
console.log(formatDate(new Date(), 'de'))

Практический пример переключателя языка

const locales = ['en', 'ru', 'de']

async function switchLocale(locale) {
    if (!locales.includes(locale)) {
        locale = 'en'
    }

    await import(`dayjs/locale/${locale}.js`)

    dayjs.locale(locale)

    render()
}

Практический пример отображения относительного времени

import dayjs from 'dayjs'

import relativeTime from 'dayjs/plugin/relativeTime'

import 'dayjs/locale/ru'

dayjs.extend(relativeTime)

dayjs.locale('ru')

const createdAt = dayjs().subtract(5, 'minute')

console.log(createdAt.fromNow())

Результат:

5 минут назад
Оглавление