docs: en

docs/en/guide/24-solar-terms.md

@@ -0,0 +1,63 @@
+# Solar Terms Module
+
+China's 24 solar terms are a part of the traditional agricultural calendar, marking distinct **periods** within a year. Each solar term typically begins on a specific (start) date but represents a period lasting about 15 days until the next solar term starts.
+
+For example, the solar term **"Lesser Fullness of Grain" (小满)** begins around **May 20th** in the Gregorian calendar. However, it doesn't end on that day; instead, it lasts until the next solar term, **"Grain in Ear" (芒种)**, which starts around **June 5th**. Therefore, the "Lesser Fullness of Grain" period is roughly from May 20th to June 5th.
+
+---
+
+## Retrieve Dates of the 24 Solar Terms
+
+### Get Solar Term Dates Within a Range
+
+```js
+import { getSolarTermsInRange } from "chinese-days";
+
+// If no arguments are passed, it returns the solar term for the current day
+console.log(getSolarTermsInRange());
+// [{date: '2024-05-29', term: 'lesser_fullness_of_grain', name: '小满', index: 10}]
+// index: Represents the day count within the current solar term, starting from 1
+
+// Query a specific date if only the start date is provided
+console.log(getSolarTermsInRange('2024-05-01'));
+// [{date: '2024-05-01', term: 'grain_rain', name: '谷雨', index: 13}]
+
+// Query solar terms within a date range
+console.log(getSolarTermsInRange('2024-05-01', '2024-05-06'));
+/**
+ * =>
+ * [
+ *   {"date":"2024-05-01","term":"grain_rain","name":"谷雨","index":13},
+ *   {"date":"2024-05-02","term":"grain_rain","name":"谷雨","index":14},
+ *   {"date":"2024-05-03","term":"grain_rain","name":"谷雨","index":15},
+ *   {"date":"2024-05-04","term":"grain_rain","name":"谷雨","index":16},
+ *   {"date":"2024-05-05","term":"the_beginning_of_summer","name":"立夏","index":1},
+ *   {"date":"2024-05-06","term":"the_beginning_of_summer","name":"立夏","index":2}
+ * ]
+ */
+```
+
+---
+
+### Retrieve Only the Start Dates of Solar Terms
+
+```js
+import { getSolarTerms } from "chinese-days";
+
+/** Get the array of solar term start dates within a specified range */
+const solarTerms = getSolarTerms("2024-05-01", "2024-05-20");
+solarTerms.forEach(({ date, term, name }) => {
+  console.log(`${name}: ${date}, ${term}`);
+});
+// Output:
+// 立夏: 2024-05-05, the_beginning_of_summer
+// 小满: 2024-05-20, lesser_fullness_of_grain
+
+// If there are no solar terms within the range, return []
+console.log(getSolarTerms("2024-05-21", "2024-05-25"));
+// Output: []
+
+// Query the solar term for a specific day if no end date is provided
+console.log(getSolarTerms("2024-05-20"));
+// Output: [{date: '2024-05-20', term: 'lesser_fullness_of_grain', name: '小满'}]
+```

docs/en/guide/contributing.md

@@ -0,0 +1,7 @@
+# Contributing Code
+
+1. **Fork + Clone** the repository to your local environment.
+2. **Holidays**: Update the [holiday definitions](https://github.com/vsme/chinese-days/blob/main/src/holidays/generate.ts).
+3. **Lunar Calendar**: Update the [lunar calendar definitions](https://github.com/vsme/chinese-days/blob/main/src/solar_lunar/constants.ts).
+4. **Other Changes**: Implement any other necessary updates or enhancements.
+5. **Submit a Pull Request (PR)**.

docs/en/guide/from-lunar.md

@@ -0,0 +1,11 @@
+# Lunar to Gregorian Calendar Conversion
+
+When dealing with leap months in the Lunar Calendar, a single Lunar date may correspond to two Gregorian dates. In such cases, the function returns an object to handle both dates.
+
+```js
+console.log(getSolarDateFromLunar('2001-03-05'));
+// {date: '2001-03-29', leapMonthDate: undefined}
+
+console.log(getSolarDateFromLunar('2001-04-05'));
+// {date: '2001-04-27', leapMonthDate: '2001-05-27'}
+```

docs/en/guide/holidays.md

@@ -0,0 +1,35 @@
+# Holidays
+
+## `isHoliday` Check if a given date is a holiday
+
+```js
+console.log(isHoliday('2023-01-01')); // true
+```
+
+## `getHolidaysInRange` Retrieve all holidays within a specified date range
+
+This function accepts a start date, an end date, and an optional parameter to decide whether to include weekends. If weekends are included, the function returns all holidays, including those that fall on weekends. If weekends are excluded, it only returns holidays on workdays.
+
+::: info Note
+Even if weekends are excluded, holidays that fall on weekends will still be included in the result.
+:::
+
+```js
+// Example usage
+const start = '2024-04-26';
+const end = '2024-05-06';
+
+// Get all holidays from 2024-04-26 to 2024-05-06, including weekends
+const holidaysIncludingWeekends = getHolidaysInRange(start, end, true);
+console.log(
+  'Holidays including weekends:',
+  holidaysIncludingWeekends.map((d) => getDayDetail(d))
+);
+
+// Get holidays from 2024-04-26 to 2024-05-06, excluding weekends
+const holidaysExcludingWeekends = getHolidaysInRange(start, end, false);
+console.log(
+  'Holidays excluding weekends:',
+  holidaysExcludingWeekends.map((d) => getDayDetail(d))
+);
+```

docs/en/guide/lieu-days.md

@@ -0,0 +1,17 @@
+# In Lieu Days
+
+## `isInLieu` Check if a given date is an in lieu day
+
+In the context of China's holiday arrangements, **in lieu days** (调休日) are adjustments to regular workdays or weekends to create longer continuous holidays or make up for days off. For example, a weekend may be shifted to a workday, or a workday may become a rest day, to facilitate an extended holiday period.
+
+### Example Usage
+
+```js
+// Check if May 2, 2024, is an in lieu day. 
+// If `true`, it indicates the date is an in lieu day.
+console.log(isInLieu('2024-05-02')); // true
+
+// Check if May 1, 2024, is an in lieu day.
+// If `false`, it indicates the date is not an in lieu day.
+console.log(isInLieu('2024-05-01')); // false
+```

docs/en/guide/thank.md

@@ -0,0 +1,4 @@
+# Acknowledgments
+
+1. Lunar calendar data is sourced from the [Bigkoo/Android-PickerView](https://github.com/Bigkoo/Android-PickerView) project.
+2. Chinese holiday data generation was inspired by the `Python` version of the [LKI/chinese-calendar](https://github.com/LKI/chinese-calendar) project.

docs/en/guide/to-lunar.md

@@ -0,0 +1,44 @@
+# Gregorian to Lunar Calendar Conversion
+
+::: info Tip
+The lunar calendar, also known as the Chinese calendar, is referred to as the "Lunar Calendar" in this project.
+:::
+
+::: info Special Notes
+1. `2057-09-28` corresponds to the Lunar Calendar date: Ding Chou (Ox) Year, Eighth Month, Thirtieth Day;
+2. `2097-08-07` corresponds to the Lunar Calendar date: Ding Si (Snake) Year, Seventh Month, First Day.
+:::
+
+## Convert Gregorian Date to Lunar Date
+
+```js
+// 2097-8-7
+console.log(getLunarDate('2097-08-07'));
+
+// 2057-9-28
+console.log(getLunarDate('2057-09-28'));
+// {
+//   date: "2057-09-28",
+//   lunarYear: 2057,
+//   lunarMon: 8,
+//   lunarDay: 30,
+//   isLeap: false,
+//   lunarDayCN: "三十",
+//   lunarMonCN: "八月",
+//   lunarYearCN: "二零五七",
+//   yearCyl: "丁丑",
+//   monCyl: "己酉",
+//   dayCyl: "戊子",
+//   zodiac: "牛"
+// }
+
+// Examples of non-leap and leap months
+console.log(getLunarDate('2001-04-27'));
+console.log(getLunarDate('2001-05-27'));
+```
+
+## Batch Retrieve Lunar Dates for a Range of Gregorian Dates
+
+```js
+console.log(getLunarDatesInRange('2001-05-21', '2001-05-26'));
+```

docs/en/guide/what-is-chinese-days.md

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-This project provides a collection of functions for querying Chinese holidays, adjusted working days, regular workdays, the 24 solar terms, and converting between the lunar and solar calendars. Additionally, it supports subscribing to holiday calendars in `iCal` format, which can be integrated with clients such as Google Calendar, Apple Calendar, and Microsoft Outlook.
+This project provides a collection of functions for querying Chinese holidays, in lieu days, working days, the 24 solar terms, and converting between the lunar and solar calendars. Additionally, it supports subscribing to holiday calendars in `iCal` format, which can be integrated with clients such as Google Calendar, Apple Calendar, and Microsoft Outlook.
 
 Data is automatically fetched daily through `GitHub Actions`. Notifications are sent via email when there are changes to holiday schedules, and information is updated based on announcements from the State Council.
 

docs/en/guide/working-days.md

@@ -0,0 +1,77 @@
+# Working Days
+
+## `isWorkday` Check if a given date is a workday
+
+```js
+console.log(isWorkday('2023-01-01')); // false
+```
+
+## `getWorkdaysInRange` Get a list of workdays within a specified date range
+
+This function takes a start date, an end date, and an optional parameter to decide whether to include weekends. If weekends are included, the function returns all days within the range. Otherwise, it returns only weekdays (Monday to Friday).
+
+```js
+// Example usage
+const start = '2024-04-26';
+const end = '2024-05-06';
+
+// Get all workdays from 2024-04-26 to 2024-05-06, including weekends
+const workdaysIncludingWeekends = getWorkdaysInRange(start, end, true);
+console.log('Workdays including weekends:', workdaysIncludingWeekends);
+
+// Get workdays from 2024-04-26 to 2024-05-06, excluding weekends
+const workdaysExcludingWeekends = getWorkdaysInRange(start, end, false);
+console.log('Workdays excluding weekends:', workdaysExcludingWeekends);
+```
+
+## `findWorkday` Find a workday
+
+Find the `{deltaDays}`-th workday starting from today.
+
+```js
+// Find the {deltaDays}-th workday from today
+// If deltaDays is 0, first check if today is a workday. If yes, return today's date.
+// If today is not a workday, find the next workday.
+const currentWorkday = findWorkday(0);
+console.log(currentWorkday);
+
+// Find the next workday
+const nextWorkday = findWorkday(1);
+console.log(nextWorkday);
+
+// Find the previous workday
+const previousWorkday = findWorkday(-1);
+console.log(previousWorkday);
+
+// Specify a starting date to find workdays relative to it
+// Find the second workday from 2024-05-18
+const secondNextWorkday = findWorkday(2, '2024-05-18');
+console.log(secondNextWorkday);
+```
+
+## `getDayDetail` Get detailed date information
+
+This function checks if a specified date is a workday and returns a boolean indicating whether it is a workday, along with details about the date.
+
+1. If the specified date is a workday, it returns `true` and the name of the weekday. If it is a rescheduled workday (due to holiday adjustments), it returns `true` and details about the holiday.
+2. If it is a holiday, it returns `false` and holiday details.
+
+```js
+// Example usage
+
+// A regular workday (Friday)
+console.log(getDayDetail('2024-02-02')); 
+// { "date": "2024-02-02", "work": true, "name": "Friday" }
+
+// A holiday (weekend)
+console.log(getDayDetail('2024-02-03')); 
+// { "date": "2024-02-03", "work": false, "name": "Saturday" }
+
+// A rescheduled workday
+console.log(getDayDetail('2024-02-04')); 
+// { "date": "2024-02-04", "work": true, "name": "Spring Festival, 春节, 3" }
+
+// A Spring Festival holiday
+console.log(getDayDetail('2024-02-17')); 
+// { "date": "2024-02-17", "work": false, "name": "Spring Festival, 春节, 3" }
+```