Chinese Calendar

English | 中文

👨🏻‍💻I'm sorry, this document is generated by machine translation. 🚀😅

Refactoring based on Lofanmi/chinese-calendar-golang project source code.

This library is significantly different from the source library in terms of concepts and architecture, so it is difficult to submit a PR to the source library. It is a completely new version developed from 0. The calendar data is taken from the source library. In the future, we consider maintaining it independently or updating it by synchronizing with a third-party source library.

Documentation in go.dev: Chinese Calendar

Features

• Representation of the combined calendar dates of the Gregorian calendar and the traditional Chinese calendar, also known as the lunar calendar
• Conversion between Gregorian calendar dates and traditional Chinese calendar dates
• Basic information and calculations of the traditional Chinese calendar or dates, such as the number of days in a year, the number of days in a month, leap month information
• Date formatting
• Calculation and data of the 24 solar terms in the traditional Chinese calendar
• Dates and times in the traditional Chinese sexagenarian cycle (Tian Gan Di Zhi)
• Generation of the traditional Chinese calendar
• Simple support for determining the 12 zodiac signs of Western astrology
• Chinese zodiac animals in the traditional Chinese calendar

Time

SolarTerm

Notation

Calendar

Astrology

Terminology and Corresponding English Translations

• Use notation to represent the symbol system of traditional Chinese calendar/culture
• Ganzhi Notation, alias SexagesimalCycle, referring to a traditional timing system composed of Heavenly Stems and Earthly Branches
• Heavenly Stem Major, alias CelestialStem, representing the primary symbols in the traditional calendar/cultural symbol system, with the names of the 10 Heavenly Stems expressed in pinyin
• Earthly Branch Minor, alias TerrestrialBranch, representing the secondary symbols in the traditional calendar/cultural symbol system, with the names of the 12 Earthly Branches expressed in pinyin
• Zodiac Sign Sign, alias Symbol, ChineseZodiac, representing a characteristic/symbol/totem of traditional Chinese calendar/culture, or a mnemonic symbol
• Solar Term SolarTerm, with the English names of the solar terms derived from the official translation for the 2022 Winter Olympics, and alternative names from the Hong Kong Observatory

Modifications Compared to the Original Library

• Renaming
• Refactoring, standardizing, and simplifying program elements

Shortcomings

• Limited support for lunar dates, only covering the range of AD 1900-2100 in the solar calendar
• Solar term data is limited to the range of AD 1904-3000
• Since the Chinese lunar calendar is a lunisolar calendar that combines the movement of the sun and the moon (as well as the Earth's own movement), the complexity and diversity of astronomical movements result in inaccuracies in the calculation of the lunar calendar. The calculation results require periodic calibration.

Chinese Calendar Arrangement Rules

Refer to Section 4 of GB/T 33661-2017 "Compilation and Issuance of the Chinese Calendar"

1. Use Beijing time as the standard time (actual usage adopts the server's local time zone)
2. The new moon day is the first day of the lunar month
3. The lunar month containing the Winter Solstice is the 11th lunar month
4. If there are 13 lunar months from a given 11th lunar month to the next 11th lunar month (excluding), a leap month is set. The rule for setting leap months is: take the first lunar month that does not contain a solar term as the leap month
5. The second lunar month (excluding leap months) after the 11th lunar month is the starting month of the lunar year

About Chinese Calendar

The lunar calendar is a traditional Chinese calendar that is a lunisolar calendar calculated based on the actual positions of the sun and moon.

It uses the strict synodic month as the calendar month and adds leap months to make the average length of the calendar year close to the tropical year.

The lunar calendar takes the time of the new moon as the beginning of each month. The synodic month is about 29.5 days long, so some months have 29 days (small months), while others have 30 days (big months). A common year in the lunar calendar has 12 months and a total of about 354 days, which is about 11 days short of the tropical year. A leap month is inserted every two or three years, and a leap year has 13 months and a total of about 384 days.

The setting of leap months is determined by the 24 solar terms, which are unique to the lunar calendar and reflect the apparent position of the sun on the celestial sphere, belonging to the category of the solar calendar. The sun moves along the ecliptic in an annual apparent motion, with the vernal equinox as the zero point. Each movement of 15° of ecliptic longitude is called a solar term, and there are 24 solar terms in a year. The table below lists the names of the 24 solar terms, the corresponding solar longitude, and the approximate dates in the solar calendar. Odd-numbered solar terms are called solar terms, while even-numbered solar terms are called median terms, collectively referred to as solar terms.