Japanese public holidays your app gets wrong
If your app counts business days, books shifts or shows a calendar, Japanese users expect it to know their holidays. Japan's holiday law adds two kinds of days off beyond the named holidays: when a holiday falls on a Sunday, the next day that isn't a holiday is off, and a day between two holidays is off. Holiday libraries have missed both. The Cabinet Office publishes the full list as a CSV:
const CSV = "https://www8.cao.go.jp" +
"/chosei/shukujitsu/syukujitsu.csv";
const buf = await fetch(CSV)
.then((r) => r.arrayBuffer());
const text = new TextDecoder(
"shift_jis").decode(buf);
const pad = (n) => n.padStart(2, "0");
const holidays = new Map();
for (const row of text.trim()
.split(/\r?\n/).slice(1)) {
const [ymd, name] = row.split(",");
const [y, m, d] = ymd.split("/");
holidays.set(
`${y}-${pad(m)}-${pad(d)}`, name);
}
The file is in Shift_JIS, not UTF-8, and writes dates as 2026/5/6, so the code pads them to 2026-05-06. The two extra kinds of day off are named just 休日 (“day off”):
| Day off | Why |
|---|---|
| 2026-05-06 | May 3 was a Sunday |
| 2026-09-22 | Between two holidays |
| 2027-03-22 | March 21 is a Sunday |
We ran the code above in Node.js 24 on the file as published on February 2, 2026: 1,067 rows, from January 1, 1955 to November 23, 2027. Applying the law's two rules to the named holidays gave exactly the 44 days marked 休日 from 2007 to 2027. The server sends no CORS header, so a page in the browser can't fetch it; load it on your server.
Refresh it every February
The Vernal and Autumnal Equinox Days aren't fixed dates: the law names the equinox, and the National Astronomical Observatory announces the next year's dates in the official gazette every February. So the list ends with next year, and for a later date it can't tell you whether it's a holiday. Save a copy, fetch it again weekly or each February, and keep the old copy if the fetch fails. Then check a day like this:
function isDayOff(iso) {
const wd = new Date(iso).getUTCDay();
return wd === 0 || wd === 6 ||
holidays.has(iso);
}
isDayOff("2026-05-06"); // true
Past the last row, it can only say no: isDayOff("2028-01-10") returned false, though Coming of Age Day falls on that day, the second Monday of January. Compare the date with the last row, and tell the user when it's past it. Days that many offices close, such as January 2 and 3, aren't public holidays and aren't in the list. Let users add their own days off rather than adding them to Japan's.
What went wrong in real apps
- redmine_non_working_days #3: the Redmine plugin imported Japanese holidays from Nager.Date, and the substitute and citizens' holidays were missing.
- thunderbird-website #1211: the Japanese holiday calendar Thunderbird distributes listed January 2 and 3 and December 31 as holidays, gave several holidays the wrong name, and listed 2028 before Japan had set it.
- chronograma #323: the calendar showed no Japanese holidays at all, so a student planning around days off couldn't see them.
- Nager.Date #943: the API's 2026 list for Japan left out May 6 and September 22.
- jollyday #1513: compared with the Cabinet Office CSV for 1955–2027, the Java library missed 263 holidays, including both equinox days every year and 84 of 96 substitute holidays.
The rest of a Japanese check
A delivery date that lands on a holiday is a promise you can't keep. The same pass catches Enter while typing Japanese (the fix), yen charged 100 times over (the fix), kanji drawn in their Chinese shapes (the fix), headings that break in the middle of a word (the fix), postal codes rejected when typed in Japanese (the fix), dates saved one day early in Japan (the fix), address forms in the American order (the fix), phone numbers sent to +81 with the 0 still in (the fix), PDFs with the Japanese missing (the fix), search that finds nothing in Japanese (the fix), previews cut down to “...” in Japanese (the fix), lists sorted in the wrong order (the fix), email subjects that arrive garbled (the fix), CSV files that open garbled in Excel (the fix), Japanese titles that give an empty URL slug (the fix), file names garbled on upload and download (the fix), dates in the Japanese era that come out wrong (the fix), full-width spaces that get past your checks (the fix), and vertical text that comes out sideways or upside down (the fix).
Lesstep translates web apps into Japanese and delivers them as one pull request. In Complete (US$249), we check every screen in Japanese, and check business days and calendars against Japan's holidays, including the days off named just 休日. The first step is a free sample.
Node.js is a trademark of the OpenJS Foundation; Java is a registered trademark of Oracle and/or its affiliates; Thunderbird is a trademark of the Mozilla Foundation. This page is not affiliated with or endorsed by any of them.
More: Enter sends the message while typing Japanese · Stripe charges 100 times too much in yen · Kanji in their Chinese shapes · Japanese headings that break in the middle of a word · Forms that reject numbers typed in Japanese · Dates that come out wrong for Japanese users · Address forms in the Japanese order · Japanese phone numbers in forms · Japanese text missing from your PDFs · Search that finds nothing in Japanese · Length limits that break in Japanese · Japanese lists sorted in the wrong order · Japanese email subjects that arrive garbled · Japanese CSV files that open garbled in Excel · Japanese titles that give an empty URL slug · Japanese file names garbled on upload and download · Japanese era dates that come out wrong · Full-width spaces that get past your checks · Japanese vertical text that comes out sideways or upside down · Japanese localization checklist · Japanese localization for your web app