How Our Calendar Tools Calculate

Method note 01

A calendar engine, not a generated answer

Our date-based tools use lunar-javascript, currently locked to version 1.7.7 in this build. Gregorian dates enter through Solar.fromYmd; Chinese lunar dates use Lunar.fromYmd. The application validates inputs, selects the relevant calendar fields and explains the result in English.

The calculators do not use machine learning to choose their results. The separate daily almanac reading may request AI-assisted explanatory text after you begin; that text does not calculate the underlying calendar date. Neither system produces a personalized prediction.

The linked Hong Kong Observatory material explains and independently documents the calendar system. It is a reference, not a live data feed, endorsement or claim that every displayed result has been individually checked against an official table.

Method note 02

Use the range of the particular tool

The date converter accepts Chinese lunar years 1900–2100 inclusive. That corresponds to Gregorian dates January 31, 1900 through January 28, 2101. A lunar year can extend into the following Gregorian year; “through 2100” alone would be ambiguous.

The solar-term and festival calendars accept whole Gregorian years 1900–2100. Birth-date selectors in the zodiac and age tools start at 1900 and end today. Age calculations also require the comparison date to be on or after the birth date, and not in the future.

A date being accepted by an underlying library is not evidence that every historical jurisdiction used the same calendar. These are educational tools, not a historical date-certification service.

Method note 03

A civil date is not an instant

Your device supplies “today” and the latest selectable birth date using its local year, month and day. We do not take a UTC timestamp and cut off the time: near midnight, that can give the wrong local date.

A birth date or date-conversion input is a date-only value. We pass those calendar numbers to the engine without converting them from your location to another time zone. There is no birth-time or birthplace field, and we cannot resolve a boundary that depends on an unknown time.

Solar-term event times are explicitly presented in China Standard Time, UTC+8, not your device’s local time. They have an offset in their machine-readable value and are displayed to the minute. To compare with your location, convert the instant, allowing the calendar date to change; do not merely relabel the hour.

Method note 04

Zodiac years turn at Lunar New Year here

The finder uses the lunar year containing the selected birth date, then maps that year to its animal, heavenly-stem element and yin–yang polarity. It does not assign everyone born in a Gregorian year the same sign.

February 9, 2024 belongs to lunar year 2023, the Rabbit year. February 10, 2024 begins lunar year 2024, the Dragon year. Our boundary is Lunar New Year, not January 1 and not Beginning of Spring. Some specialist systems use that solar-term boundary; they answer a different question.

The compatibility tool is separate: it compares an authored set of four traditional trines and six opposing pairs, with a same-sign explanation. The lookup is symmetric, has no percentage score and does not assess two people or determine whether a relationship will work.

Method note 05

Two age counts, two different clocks

Birthday-based age is the comparison Gregorian year minus the birth year, subtracting one if the month and day of the birthday have not yet been reached. Traditional nominal age is the comparison lunar year minus the birth lunar year plus one.

For a June 15, 2000 birth date, February 9, 2024 gives birthday-based age 23 and nominal age 24. On February 10, 2024, birthday-based age stays 23 while nominal age becomes 25: the lunar year changed, not the birthday.

For a February 1, 2023 birth date, both counts are 1 on February 1, 2024. A nominal count need not always be two years higher. February 29 birthdays follow the month/day comparison in the first formula; in a non-leap year the increase occurs March 1. This is an explicit calculation convention, not a legal rule or a universal family practice.

Method note 06

Leap months are distinct inputs

For Gregorian-to-lunar conversion we validate the real Gregorian date and read the lunar year, month and day from the engine. For the reverse direction we first list the actual months in that lunar year, including any leap month, and the valid day count of each month.

A regular second month and a leap second month are not interchangeable. In 2023, regular month 2, day 1 is February 20; leap month 2, day 1 is March 22. In the library the leap month has a negative month number; the interface displays a readable leap label rather than asking you to enter that convention.

A lunar month has 29 or 30 days. The converter rejects a day beyond the selected month’s actual length and does not silently roll it into the next month. A Gregorian leap day and a Chinese lunar leap month solve different calendar problems.

Method note 07

Seasonal instants, displayed to the minute

The twenty-four terms divide the Sun’s apparent annual path into 15-degree steps. We obtain their event dates and times from the library’s JieQi table, selecting the entries that belong to the requested year, including that year’s winter solstice.

The interface truncates the seconds field when displaying hours and minutes. Minute-level display is a formatting choice, not a guarantee of astronomical accuracy to one minute. Computational models and rounding can differ from published almanacs, particularly near a date boundary; consult the Observatory’s year-specific tables for a consequential use.

A term marks an astronomical position, not a promise about weather at your location. Its seasonal vocabulary arose in particular Northern Hemisphere contexts; the same instant does not create the same season worldwide.

Method note 08

Festival dates are not holiday entitlements

The festival calendar converts defined lunar month/day pairs: New Year 1/1, Lantern Festival 1/15, Dragon Boat 5/5, Qixi 7/7, Mid-Autumn 8/15 and Double Ninth 9/9. These refer to regular months, not an automatic second celebration in a leap month.

Qingming and Dongzhi instead follow the corresponding solar-term dates from the engine. They are not fixed lunar month/day pairs. We sort all entries by their resulting Gregorian date for the selected year.

This is a selected cultural calendar, not a complete list of observances or a government work-and-school holiday schedule. Travel closures, substitute holidays, local celebrations and family practice must be checked separately with the relevant organizer or jurisdiction.

Method note 09

What to check before relying on a result

First check the input date, the intended calendar, the leap-month label and the time-zone caption. A one-day discrepancy may be a date-boundary issue rather than an arithmetic error. For age, also check which age convention the question actually requires.

Do not use these tools to decide medical care, legal age, immigration requirements, official record amendments or other high-stakes matters. Use the authority responsible for the decision and its required evidence.

Our regression checks cover year boundaries, invalid dates, leap months, age transitions and the declared endpoints. They do not prove every historical date or every external table agrees. Library or rule changes should be accompanied by rerunning those checks and revisiting this explanation.

If something disagrees, send the input, the result, the expected result, your time zone where relevant, and a link to the comparison source. That makes a discrepancy reproducible without requiring you to share a full birth record.