#4270·date-fns

zh-CN cannot parse its own formatted quarter: localize produces 季 forms but match expects 刻 forms

Author: cozuyaCreated Jul 22, 2026Updated Jul 22, 2026

Human note: this is a new issue not currently in the backlog, it seems.

Description

In the zh-CN locale, formatting a quarter with QQQ/QQQQ produces 季-based strings, but the locale's own parse patterns (matchQuarterPatterns in src/locale/zh-CN/_lib/match/index.ts) only accept the 第[一二三四]刻 / 第[一二三四]刻钟 forms. As a result, a format → parse round-trip through the same locale and token returns Invalid Date. zh-HK and zh-TW round-trip correctly.

Reproduction

javascript
import { format, parse } from "date-fns";
import { zhCN, zhHK, zhTW } from "date-fns/locale";

const date = new Date(2024, 6, 1); // Q3 2024
const ref = new Date(2024, 0, 1);

format(date, "QQQ", { locale: zhCN });           //=> "第三季"
parse("第三季", "QQQ", ref, { locale: zhCN });    //=> Invalid Date  ❌

format(date, "QQQQ", { locale: zhCN });          //=> "第三季度"
parse("第三季度", "QQQQ", ref, { locale: zhCN }); //=> Invalid Date  ❌

// zh-CN's parser only accepts the 刻 forms it never produces:
parse("第三刻", "QQQ", ref, { locale: zhCN });    //=> Mon Jul 01 2024 (unexpected)
parse("第三刻钟", "QQQQ", ref, { locale: zhCN }); //=> Mon Jul 01 2024 (unexpected)

// zh-HK and zh-TW round-trip fine:
parse(format(date, "QQQ", { locale: zhHK }), "QQQ", ref, { locale: zhHK }); //=> Mon Jul 01 2024 ✅
parse(format(date, "QQQ", { locale: zhTW }), "QQQ", ref, { locale: zhTW }); //=> Mon Jul 01 2024 ✅

Likely origin

PR #2771 (merged 2021-11-30) changed the zh-CN quarter translation in the localize file from the 刻 forms to the 季 forms, but did not update the corresponding matchQuarterPatterns in the match file, which still expects the pre-#2771 forms. Related: #2889 / #2890 propose the same 刻 → 季 correction for zh-TW (that PR updates both localize and match, so it would not reproduce this problem in zh-TW), but neither mentions the existing zh-CN format/parse mismatch.

Note on fix direction

I'm not proposing a specific fix — the resolution is a locale/maintainer decision. Options include updating matchQuarterPatterns to accept the 季 forms (possibly keeping 刻 for backward compatibility), or changing the formatter, depending on the intended zh-CN translation.

Environment

  • date-fns: reproduced against current main, and the published [email protected] on npm contains the same matchQuarterPatterns.
  • Node.js: v24.12.0