Logo

TEA Calendar

Pragmatically convert Gregorian calendar date of the period 1583-2100 to Chinese Calendar date

Demo

Table Of Contents

About the Project

This pure JavaScript program converts any Gregorian calendar date of the period 1583-2100 to its corresponding Chinese calendar date. It is designed to be an alternative to the conversion via the JavaScript's Standard built-in objects, which is not always reliable for the real-world usage (cf. the code example below or this codepen) and rather difficult to be adjusted to the existing Chinese calendar without loss of efficiency. 

//conversion wiht the JavaScript's Standard built-in objects
const date = new Date('2018-11-08T12:00:00.000');
const options = {year: 'numeric', month: 'numeric', day: 'numeric' };
const dateFormat = new Intl.DateTimeFormat('fr-CA-u-ca-chinese', options);
let output = dateFormat.format(date);
//output in Chrome as well as in Firefox: "2/10/35".
//In reality, the corresponding date is "1/10/35".

Note About the correct conversion of the date above, cf., for example, the conversion table 2011-2020 published by the Taipei Astronomical Museum or the Gregorian-Lunar Calendar Conversion Table 2018 of Hong Kong Observatory.

An NPM version with identical core codes is also published in GitHub.

Usage

Basic conversion

1. import the core module:

  • local import:
import {Teac} from '/PATH/TO/teac.min.js'
  • remote import from deno.land:
 import {Teac} from 'https://deno.land/x/tea_calendar/teac.min.js'

2. input a Gregorian Calendar date string in "YYYY-MM-DD" format to get an array of four elements:

  • number of the year in the sexagenary cycle,

  • lunar month number,

  • day number,

  • Boolean value for leap month (true: leap month)

const date = new Teac('2025-07-28').num();
// Expected output: [42, 6, 4, true]

Note In order to avoid the impact of time zone setting of the device (or the network), this program uses the UTC and the 12:00:00 GMT+00:00 for each input date. For example, the string '2023-04-04' is converted to "2023-04-04T12:00:00.000Z" before the construction of the corresponding JavaScript Date object.

i18n

import {Teac, Lang} from './Teac.js'

2a. output the sexagenary years in string format:

  • in Chinese:
const d = new Teac('2025-07-28').yearIn('zh');
// Expected output: ['乙巳', 6, 4, true]
  • in Korean:
const d = new Teac('2025-07-28').yearIn('ko');
// Expected output: ['을사', 6, 4, true]
  • in Pinyin:
const d = new Teac('2025-07-28').yearIn('en');
// Expected output: ['yi-si', 6, 4, true]

Note Any ISO 639-1 codes other than ko and zh could replace the en here. In other words, de, fr, nl are valid and all produce the same output.

2b. or, output entirely in text format

  • in traditional Chinese:
const d = new Teac('2025-07-28').sino(0)
// Expected output: ['乙巳年', '閏六月', '初四']
  • in simplified Chinese:
const d = new Teac('2025-07-28').sino(1)
// Expected output: ['乙巳年', "闰六月', '初四']
  • without literal characters:
const d = new Teac('2025-07-28').sino(0, false);
// Expected output: ['乙巳', "閏六', '初四']

License

Distributed under the MIT License. See LICENSE for more information.

Author

Acknowledgements