CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-dayjs

2KB immutable date time library alternative to Moment.js with the same modern API

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

localization.mddocs/

Localization

Day.js provides comprehensive internationalization (i18n) support with over 100 built-in locales and the ability to create custom locale configurations. Locales affect month names, weekday names, ordinal formatting, and other locale-specific display elements.

Capabilities

Global Locale Management

Set and retrieve the global default locale used by all new Dayjs instances.

/**
 * Set or get the global locale
 * @param preset - Locale name or locale object
 * @param object - Locale definition object
 * @param isLocal - Apply only locally (internal parameter)
 * @returns Current locale name when getting, dayjs function when setting
 */
dayjs.locale(preset?: string | ILocale, object?: Partial<ILocale>, isLocal?: boolean): string;

/**
 * Current global locale reference
 */
dayjs.Ls: { [key: string]: ILocale };

Usage Examples:

// Get current global locale
console.log(dayjs.locale()); // 'en'

// Set global locale
dayjs.locale('es'); // Spanish
dayjs.locale('zh-cn'); // Chinese Simplified
dayjs.locale('fr'); // French

// All new instances use the global locale
console.log(dayjs().format('MMMM')); // Spanish/Chinese/French month name

// Access loaded locales
console.log(dayjs.Ls); // Object containing all loaded locales

Instance Locale Management

Set locale for specific Dayjs instances without affecting the global locale.

/**
 * Get current locale for this instance
 * @returns Current locale name
 */
locale(): string;

/**
 * Set locale for this instance
 * @param preset - Locale name or locale object
 * @param object - Locale definition object
 * @returns New Dayjs instance with specified locale
 */
locale(preset: string | ILocale, object?: Partial<ILocale>): Dayjs;

Usage Examples:

// Instance-specific locales
const englishDate = dayjs('2018-04-04');
const spanishDate = englishDate.locale('es');
const chineseDate = englishDate.locale('zh-cn');

console.log(englishDate.format('MMMM')); // 'April'
console.log(spanishDate.format('MMMM')); // 'abril'
console.log(chineseDate.format('MMMM')); // '四月'

// Check instance locale
console.log(spanishDate.locale()); // 'es'

// Chaining with locale
const formatted = dayjs()
  .locale('fr')
  .format('dddd, MMMM Do YYYY');

Locale Loading

Import and use specific locales on demand to keep bundle size minimal.

// Import locale modules
import 'dayjs/locale/es'; // Spanish
import 'dayjs/locale/fr'; // French
import 'dayjs/locale/zh-cn'; // Chinese Simplified
import 'dayjs/locale/ja'; // Japanese
import 'dayjs/locale/de'; // German
import 'dayjs/locale/it'; // Italian
import 'dayjs/locale/pt'; // Portuguese
import 'dayjs/locale/ru'; // Russian
import 'dayjs/locale/ko'; // Korean
import 'dayjs/locale/ar'; // Arabic

// Use immediately after import
dayjs.locale('es');

Usage Examples:

// Load specific locales
import dayjs from 'dayjs';
import 'dayjs/locale/es'; // Load Spanish
import 'dayjs/locale/fr'; // Load French
import 'dayjs/locale/ja'; // Load Japanese

// Use loaded locales
dayjs.locale('es');
console.log(dayjs().format('dddd, MMMM Do YYYY'));
// 'miércoles, abril 4º 2018'

dayjs.locale('fr');
console.log(dayjs().format('dddd, MMMM Do YYYY'));
// 'mercredi, avril 4e 2018'

dayjs.locale('ja');
console.log(dayjs().format('dddd, MMMM Do YYYY'));
// '水曜日, 4月 4日 2018'

// Mix global and instance locales
dayjs.locale('en'); // Global English
const spanishInstance = dayjs().locale('es');
const frenchInstance = dayjs().locale('fr');

console.log(dayjs().format('MMMM')); // 'April' (global English)
console.log(spanishInstance.format('MMMM')); // 'abril' (instance Spanish)
console.log(frenchInstance.format('MMMM')); // 'avril' (instance French)

Custom Locale Definition

Create custom locale configurations for specific formatting requirements.

/**
 * Locale configuration interface
 */
interface ILocale {
  /** Locale identifier */
  name: string;
  
  /** Full weekday names array (Sunday to Saturday) */
  weekdays?: string[];
  
  /** Short weekday names array */
  weekdaysShort?: string[];
  
  /** Minimal weekday names array */
  weekdaysMin?: string[];
  
  /** Full month names array (January to December) */
  months?: string[];
  
  /** Short month names array */
  monthsShort?: string[];
  
  /** Ordinal number formatter function */
  ordinal?: (n: number) => string;
  
  /** Week start day (0 = Sunday, 1 = Monday, etc.) */
  weekStart?: number;
  
  /** Year start configuration */
  yearStart?: number;
  
  /** Localized format tokens */
  formats?: {
    L?: string;
    LL?: string;
    LLL?: string;
    LLLL?: string;
    LT?: string;
    LTS?: string;
  };
  
  /** Relative time strings (for relativeTime plugin) */
  relativeTime?: {
    future?: string;
    past?: string;
    s?: string;
    m?: string;
    mm?: string;
    h?: string;
    hh?: string;
    d?: string;
    dd?: string;
    M?: string;
    MM?: string;
    y?: string;
    yy?: string;
  };
  
  /** Meridiem function for AM/PM */
  meridiem?: (hour: number, minute: number, isLowercase: boolean) => string;
}

Usage Examples:

// Define custom locale
const customLocale = {
  name: 'custom-en',
  weekdays: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
  weekdaysShort: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
  weekdaysMin: ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'],
  months: ['January', 'February', 'March', 'April', 'May', 'June',
           'July', 'August', 'September', 'October', 'November', 'December'],
  monthsShort: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
                'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
  ordinal: (n) => {
    const s = ['th', 'st', 'nd', 'rd'];
    const v = n % 100;
    return `[${n}${(s[(v - 20) % 10] || s[v] || s[0])}]`;
  },
  weekStart: 1, // Monday
  formats: {
    L: 'DD/MM/YYYY',
    LL: 'D MMMM YYYY',
    LLL: 'D MMMM YYYY HH:mm',
    LLLL: 'dddd, D MMMM YYYY HH:mm'
  }
};

// Register custom locale
dayjs.locale(customLocale);

// Use custom locale
dayjs.locale('custom-en');
console.log(dayjs().format('L')); // Uses custom DD/MM/YYYY format
console.log(dayjs().format('Do')); // Uses custom ordinal function

Locale-Specific Formatting

Different locales provide different formatting behaviors and date representations.

// Locale-specific format behavior examples:

// Date formats vary by locale
// English: MM/DD/YYYY (month first)
// European: DD/MM/YYYY (day first)  
// ISO: YYYY-MM-DD (year first)

// Ordinal numbers differ
// English: 1st, 2nd, 3rd, 4th
// Spanish: 1º, 2º, 3º, 4º
// French: 1er, 2e, 3e, 4e

// Week start varies
// Sunday start: US, Canada, Japan
// Monday start: Most of Europe, Asia

Usage Examples:

import 'dayjs/locale/es';
import 'dayjs/locale/fr';
import 'dayjs/locale/ar';
import 'dayjs/locale/ja';

const date = dayjs('2018-04-04');

// English (default)
console.log(date.format('dddd, MMMM Do YYYY'));
// 'Wednesday, April 4th 2018'

// Spanish
console.log(date.locale('es').format('dddd, MMMM Do YYYY'));
// 'miércoles, abril 4º 2018'

// French
console.log(date.locale('fr').format('dddd, MMMM Do YYYY'));
// 'mercredi, avril 4e 2018'

// Arabic (RTL language)
console.log(date.locale('ar').format('dddd، MMMM Do YYYY'));
// 'الأربعاء، أبريل 4 2018'

// Japanese
console.log(date.locale('ja').format('dddd、MMMM Do YYYY'));
// '水曜日、4月 4日 2018'

// Different week starts affect week-related operations
dayjs.locale('en'); // Sunday start
console.log(dayjs('2018-04-02').day()); // 1 (Monday)

import 'dayjs/locale/de';
dayjs.locale('de'); // Monday start
console.log(dayjs('2018-04-02').startOf('week').format('dddd'));
// Different week start behavior

Available Locales

Day.js includes over 100 locales covering major languages and regional variants:

Major Languages

  • English: en (default), en-au, en-ca, en-gb, en-ie, en-in, en-sg, en-tt
  • Spanish: es, es-do, es-mx
  • French: fr, fr-ca, fr-ch
  • German: de, de-at, de-ch
  • Italian: it, it-ch
  • Portuguese: pt, pt-br
  • Chinese: zh, zh-cn, zh-hk, zh-tw
  • Japanese: ja
  • Korean: ko
  • Russian: ru
  • Arabic: ar, ar-dz, ar-kw, ar-ly, ar-ma, ar-sa, ar-tn

European Languages

  • Dutch: nl, nl-be
  • Polish: pl
  • Swedish: sv
  • Norwegian: nb, nn
  • Danish: da
  • Finnish: fi
  • Czech: cs
  • Slovak: sk
  • Hungarian: hu
  • Romanian: ro
  • Bulgarian: bg
  • Croatian: hr
  • Serbian: sr, sr-cyrl
  • Ukrainian: uk
  • Greek: el

Asian Languages

  • Hindi: hi
  • Bengali: bn, bn-bd
  • Thai: th
  • Vietnamese: vi
  • Indonesian: id
  • Malay: ms, ms-my
  • Tagalog: tl-ph
  • Nepali: ne
  • Sinhala: si

Other Languages

  • Hebrew: he
  • Turkish: tr
  • Persian: fa
  • Urdu: ur
  • Armenian: hy-am
  • Georgian: ka
  • Kazakh: kk
  • Mongolian: mn
  • Swahili: sw
  • Amharic: am

Locale Usage Patterns

Bundle Size Optimization

Only import the locales you need to minimize bundle size:

// ✅ Good - Only load needed locales
import dayjs from 'dayjs';
import 'dayjs/locale/es'; // Spanish
import 'dayjs/locale/fr'; // French

// ❌ Avoid - Loading all locales unnecessarily
import 'dayjs/locale/*'; // Don't do this

Dynamic Locale Loading

Load locales dynamically based on user preferences:

// Dynamic locale loading
async function setUserLocale(localeCode) {
  try {
    await import(`dayjs/locale/${localeCode}`);
    dayjs.locale(localeCode);
    return true;
  } catch (error) {
    console.warn(`Locale ${localeCode} not available`);
    return false;
  }
}

// Usage
setUserLocale('es').then(success => {
  if (success) {
    console.log(dayjs().format('LLLL'));
  }
});

Locale Persistence

Maintain locale settings across application sessions:

// Save locale preference
function setAndSaveLocale(locale) {
  dayjs.locale(locale);
  localStorage.setItem('preferred-locale', locale);
}

// Restore locale preference
function restoreLocale() {
  const saved = localStorage.getItem('preferred-locale');
  if (saved) {
    dayjs.locale(saved);
  }
}

// Initialize on app start
restoreLocale();

docs

core-api.md

index.md

localization.md

plugins.md

tile.json