date-fns 捷克语(cs)locale 完全指南:format/parse 令牌行为、复数规则与相对时间本地化

原创2026-09-18 13:55:031,663 阅读
文章标签:国际化跨平台前端

date-fns 捷克语(cs)locale 完全指南:format/parse 令牌行为、复数规则与相对时间本地化

捷克语(Czech, cs)是 date-fns 官方内置的 70+ 语言之一,其实现位于 pkgs/core/src/locale/cs/index.ts,对应的行为快照文档为 pkgs/core/src/locale/cs/snapshot.md。本文以该快照文档为核心,结合源码逐一拆解 format/parse 令牌的捷克语输出、formatDistance/formatDistanceStrict 的复杂复数与格变化、formatRelative 的星期宾格处理以及 formatDuration 的时长本地化。读完本文,你将能够精准预判每个令牌在捷克语下的格式化与解析结果,并理解如何参照此实现为其他斯拉夫语系语言构建 locale。

快速接入:如何在项目中使用 cs locale

在 date-fns 中,locale 是一个实现了 Locale 接口 的对象,包含 code、formatDistance、formatRelative、localize、formatLong、match 以及可选的 options。cs 的完整定义见 pkgs/core/src/locale/cs/index.ts:

export const cs: Locale = {
  code: "cs",
  formatDistance: formatDistance,
  formatLong: formatLong,
  formatRelative: formatRelative,
  localize: localize,
  match: match,
  options: {
    weekStartsOn: 1 /* Monday */,
    firstWeekContainsDate: 4,
  },
};

其中 options 定义了捷克语语境下的周起始规则:周一为一周的第一天(weekStartsOn: 1),包含当年 1 月 4 日的周为第一周(firstWeekContainsDate: 4),这与 ISO 8601 标准一致。

实际使用方式(以 format 和 formatRelative 为例):

import { format, formatRelative, cs } from "date-fns/locale";

format(new Date("2019-02-11T12:13:14Z"), "PPPP", { locale: cs });
// => "pondělí, 11. února 2019"

formatRelative(new Date("2000-01-01T00:00:00Z"), new Date("2000-01-01T00:00:00Z"), { locale: cs });
// => "dnes v 0:00"

cs 与其他 locale 一样,由 pkgs/core/src/locale/index.ts 统一导出,可通过 import { cs } from "date-fns/locale" 引入。

format 与 parse:令牌级捷克语行为全表

快照文档第一节(snapshot.md)完整记录了 40+ 个格式化令牌在捷克语下的输出与可解析性。下表为快照的核心结论(省略快照中的多日期重复行,保留代表性样例与全部令牌):

类别 令牌 输入日期 format 结果 parse 结果
Calendar year yo 1987-02-11 1987. 1987-01-01
Local week-numbering year Yo 1987-02-11 1987. 1986-12-29(周制年起点,跨年偏移)
Quarter (formatting) Qo 2019-04-01 2. 2019-04-01
QQQ / QQQQ 2019-04-01 2. čtvrtletí 2019-04-01
QQQQQ 2019-04-01 2 2019-04-01
Quarter (stand-alone) qo / qqq / qqqq / qqqqq 2019-04-01 同 formatting 系列 2019-04-01
Month (formatting) Mo 2019-02-11 2. 2019-02-01
MMM 2019-02-11 úno 2019-02-01
MMMM 2019-02-11 února(属格) 2019-02-01
MMMMM 2019-02-11 Ú 2019-02-01
Month (stand-alone) Lo / LLL 2019-02-11 2. / úno 2019-02-01
LLLL 2019-02-11 únor(主格) 2019-02-01
LLLLL 2019-02-11 Ú 2019-02-01
Local week of year wo 2019-01-01 1. 2018-12-31
ISO week of year Io 2019-01-01 1. 2018-12-31
Day of month do 2019-02-11 11. 2019-02-11
do MMMM 2019-02-11 11. února 2019-02-11
Day of year Do 2019-12-31 365. 2019-12-31
Day of week (formatting) E / EE / EEE 2019-02-11 pon 2019-02-11
EEEE 2019-02-11 pondělí 2019-02-11
EEEEE 2019-02-11 po Invalid Date
EEEEEE 2019-02-11 po 2019-02-11
ISO day of week (formatting) io / iii / iiii 2019-02-11 1. / pon / pondělí 2019-02-11
iiiii 2019-02-11 po Invalid Date
iiiiii 2019-02-11 po 2019-02-11
Local day of week (formatting) eo / eee / eeee / eeeee / eeeeee 同 ISO 系列 同 ISO 系列 同 ISO 系列
Local day of week (stand-alone) co / ccc / cccc / ccccc / cccccc 同 ISO 系列 同 ISO 系列 同 ISO 系列
AM, PM a / aa / aaa / aaaaa 2019-02-11T14:13 odp. 2019-02-11T12:00
aaaa 2019-02-11T14:13 odpoledne 2019-02-11T12:00
AM, PM, noon, midnight b 系列 2019-02-11T14:13 odp. / odpoledne 2019-02-11T12:00
Flexible day period B 系列 2019-02-11T19:13 večer 2019-02-11T17:00
Hour [1-12] ho 2019-02-11T23:13 11. 2019-02-11T23:00
Hour [0-23] Ho 2019-02-11T23:13 23. 2019-02-11T23:00
Hour [0-11] Ko 2019-02-11T23:13 11. 2019-02-11T23:00
Hour [1-24] ko 2019-02-11T23:13 23. 2019-02-11T23:00
Minute mo 2019-04-01T12:55 55. 2019-04-01T12:55
Second so 2019-04-01T12:13:55 55. 2019-04-01T12:13:55
Long localized date P 1987-02-11 11.02.1987 1987-02-11
PP 1987-02-11 11. 2. 1987 1987-02-11
PPP 1987-02-11 11. února 1987 1987-02-11
PPPP 1987-02-11 středa, 11. února 1987 1987-02-11
Long localized time p 1987-02-11T12:13 12:13 1987-02-11T12:13
pp 1987-02-11T12:13:14 12:13:14 1987-02-11T12:13:14
ppp / pppp 任意 12:13:14 GMT+0 / 12:13:14 GMT+00:00 Errored
Combination Pp 1987-02-11T12:13 11.02.1987, 12:13 1987-02-11T12:13
PPpp 1987-02-11T12:13:14 11. 2. 1987, 12:13:14 1987-02-11T12:13:14
PPPppp / PPPPpppp 任意 含 v 连接词与 GMT 偏移 Errored

三个关键结论(快照中的隐藏信息)

  1. 序数词一律加句点:捷克语的序数形式通过 数字 + "." 表达(1987.、1.、11.、365.)。其实现位于 localize/index.ts:
const ordinalNumber: LocalizeFn<number> = (dirtyNumber, _options) => {
  const number = Number(dirtyNumber);
  return number + ".";
};
  1. 5 字符窄宽度(EEEEE/iiiii/eeeee/ccccc)不可被 parse:快照中这些令牌的 parse 结果均为 Invalid Date。这是因为窄宽度只保留了首字母缩写(如 po、pá),而 match/index.ts 的解析模式仅覆盖 narrow 与 any 两种宽度,窄宽度映射的 abbreviated 解析模式无法唯一确定星期。

  2. 含时区偏移的令牌(ppp、pppp、PPPppp、PPPPpppp)format 可用但 parse 会 Errored:快照明确标注这些行 parse 结果为 Errored,说明捷克语 locale 的 match 不支持反向解析含 GMT 偏移的时间格式,格式化输出则正常(12:13:14 GMT+0、12:13:14 GMT+00:00)。

源码级印证:本地化数据从何而来

快照表中的所有输出都直接来自 localize/index.ts 中的数据表:

  • 月份双表制:捷克语格式化语境下的月份使用属格(ledna、února、března…),而独立语境使用主格(leden、únor、březen…)。这正是快照中 MMMM(formatting,输出 února)与 LLLL(stand-alone,输出 únor)结果不同的原因。month 通过 buildLocalizeFn 的 formattingValues 参数接入双表(见 localize/index.ts)。
  • 窄宽度月份首字母:MMMMM/LLLLL 输出 L Ú B D K Č Č S Z Ř L P(注意 6 月 červen 与 7 月 červenec 窄宽度均为 Č),parse 时依靠 match/index.ts 的窄宽度正则(/^[čc]/i)区分。
  • 星期缩写:EEEE 输出完整星期(pondělí),EEE 输出三字母缩写(pon),EEEEEE 输出两字母缩写(po),数据见 localize/index.ts 的 dayValues。

formatDistance:捷克语的三类复数与三时态系统

快照第二节(snapshot.md)以“2000 年 1 月 1 日 00:00 为 now”为基准,验证了 formatDistance 的输出。捷克语复数系统与英语不同,分为 one / few / many 三类,且过去、未来、常规三种时态各有独立的词形变化,全部实现在 formatDistance/index.ts:

export const formatDistance: FormatDistanceFn = (token, count, options) => {
  let pluralResult;
  const tokenValue = formatDistanceLocale[token];

  // cs pluralization
  if (tokenValue.type === "other") {
    pluralResult = tokenValue.other;
  } else if (count === 1) {
    pluralResult = tokenValue.one;
  } else if (count > 1 && count < 5) {
    pluralResult = tokenValue.few;
  } else {
    pluralResult = tokenValue.many;
  }

  // times
  const suffixExist = options?.addSuffix === true;
  const comparison = options?.comparison;
  let timeResult;
  if (suffixExist && comparison === -1) {
    timeResult = pluralResult.past;
  } else if (suffixExist && comparison === 1) {
    timeResult = pluralResult.future;
  } else {
    timeResult = pluralResult.regular;
  }
  return timeResult.replace("{{count}}", String(count));
};

复数选择规则(快照验证)

计数范围 类别 快照示例
count === 1 one 1 rok、1 den、1 hodina、1 minuta
2 <= count <= 4 few 2 roky、2 měsíce、3 roky、4 roky
count >= 5 或 count === 0 many 5 měsíců、6 roků、17 dní、0 sekund

时态与格变化(addSuffix: true 时生效)

未来时用介词 za + 宾格/主格(za 5 měsíců、za 1 den),过去时用 před + 工具格(před 15 minutami、před 2 dny、před 1 hodinou),其中大量词形变化(如 minuta → minutu → minutou → minutami)由 formatDistance/index.ts 中 xMinutes 令牌的 one/few/many × regular/past/future 九元组定义。

特殊令牌

  • halfAMinute 是独立类型(type: "other"),三时态分别为 půl minuty / před půl minutou / za půl minuty,见 formatDistance/index.ts。
  • includeSeconds: true 时,xSeconds 系列会被细分为“少于 5/10/20 秒、半分钟”等粒度,快照中 2000-01-01T00:00:25 输出 půl minuty 即属此类。

快照中的代表性完整输出

相对 now 的日期 常规结果 addSuffix: true
2001-06-01(过去 6 个月) více než 1 rok za více než 1 rok
2000-03-01(过去 2 个月) 2 měsíce za 2 měsíce
2000-01-02(过去 1 天) 1 den za 1 den
2000-01-01T00:30(过去 30 分钟) 30 minut za 30 minut
1999-12-31T23:45 15 minut před 15 minutami
1999-12-15(过去 17 天) 17 dní před 17 dny
1994-01-01 přibližně 6 roků přibližně před 6 roky

注意 addSuffix: true 对未来时间使用 za 前缀(za 6 roků),对过去时间使用 před 前缀(před 6 roky),且后缀短语在词形上彼此独立。

formatDistanceStrict:精确到单位,无“大约”修饰

快照第三节(snapshot.md)验证了 formatDistanceStrict:它不做“约/多于/少于”的模糊处理,直接输出精确数值,且支持通过 unit 选项强制指定单位。快照第三列展示了强制 hour 单位时的结果:

  • 2000-01-15(14 天前)→ 336 hodin
  • 2000-01-02(1 天前)→ 24 hodin
  • 2000-01-01T00:45(45 分钟前)→ 1 hodina(45 分钟按小时取整)
  • 2000-01-01T00:15(15 分钟前)→ 0 hodin(不足 1 小时向下取整)
  • 1998-06-01 → 13896 hodin

由于 formatDistanceStrict 复用同一套 formatDistance/index.ts 的 token 表,复数与时态规则完全一致:0 hodin、1 hodina、2 hodiny、5 hodin、6 roků 等同样遵循 one/few/many 规则,过去时同样使用 před + 工具格(před 45 minutami)。

formatRelative:星期的宾格(accusative)处理

快照第四节(snapshot.md)验证了 formatRelative 的五种相对时间输出。实现见 formatRelative/index.ts:

const formatRelativeLocale = {
  lastWeek: "'poslední' eeee 've' p",
  yesterday: "'včera v' p",
  today: "'dnes v' p",
  tomorrow: "'zítra v' p",
  nextWeek: (date: Date) => {
    const day = date.getDay() as Day;
    return "'v " + accusativeWeekdays[day] + " o' p";
  },
  other: "P",
};

快照中的完整结果(now = 2000-01-01):

日期 formatRelative 结果
2000-01-10 10.01.2000(other → P 短日期)
2000-01-05 v středu o 0:00(下周 → 宾格 středu)
2000-01-02 zítra v 0:00
2000-01-01 dnes v 0:00
1999-12-31 včera v 0:00
1999-12-27 poslední pondělí ve 0:00(上周)
1999-12-21 21.12.1999(other)

为什么 nextWeek 是函数

捷克语中“在下周 X”需要将星期名词变为宾格(第四格):pondělí → pondělí(不变)、středa → středu、sobota → sobotu、neděle → neděli。由于无法用一个静态模板覆盖全部 7 个星期的宾格形式,nextWeek 被实现为接收日期并返回动态模板的函数,宾格表 accusativeWeekdays 定义于 formatRelative/index.ts。同时注意介词搭配的差异:今天/明天/昨天用 v(dnes v 0:00),下周用 v ... o(v středu o 0:00),上周用 ve(poslední pondělí ve 0:00),这些介词的选择也体现在模板字符串中。

formatDuration:时长组件的单数与复数

快照第五节(snapshot.md)验证了 formatDuration 对 Duration 对象各字段的本地化:

Duration 结果 Duration 结果
{"years":0} 0 roků {"days":0} 0 dní
{"years":1} 1 rok {"days":1} 1 den
{"years":2} 2 roky {"days":2} 2 dny
{"months":0} 0 měsíců {"hours":0} 0 hodin
{"months":1} 1 měsíc {"hours":1} 1 hodina
{"months":2} 2 měsíce {"hours":2} 2 hodiny
{"weeks":0} 0 týdnů {"minutes":0} 0 minut
{"weeks":1} 1 týden {"minutes":1} 1 minuta
{"weeks":2} 2 týdny {"minutes":2} 2 minuty
{"seconds":0} 0 sekund
{"seconds":1} 1 sekunda
{"seconds":2} 2 sekundy

这里同样体现了完整的复数三态:0 与 ≥5 用 many(0 roků、0 dní、0 hodin),1 用 one(1 rok、1 den、1 hodina),2-4 用 few(2 roky、2 dny、2 hodiny)。formatDuration 底层复用 formatDistance 的 token 表(xYears、xMonths、xWeeks、xDays、xHours、xMinutes、xSeconds),因此这些输出与 formatDistance/formatDistanceStrict 的常规时态完全一致。

支撑 parse 的匹配层:match 模块

parse 能够反向解析快照表中的绝大多数输出,依赖 match/index.ts 中为每个单位定义的正则匹配模式。其设计要点:

  • 序数:matchOrdinalNumberPattern = /^(\d+)\.?/i,允许可选尾随句点,parseOrdinalNumberPattern = /\d+/i 提取数字(match/index.ts)。
  • 纪元:支持 př. n. l.(公元前)、n. l.(公元)、před Kristem(基督之前)、po Kristu 等宽窄变体(match/index.ts)。
  • 月份:wide 模式同时覆盖主格与属格两种词形(leden|ledna、února?、červen(ec|ce)?|června),这正是 parse 能同时解析 MMMM(属格)与 LLLL(主格)输出的原因;any 解析模式用 /^<a href="https://link.gitcode.com/i/3aa32477b60286c0c1884e4ea9106048" target="_blank">čc]vn|[čc]erven(?!\w)|[čc]ervna/i 区分 čvn(6 月)与 čvc(7 月)([match/index.ts)。
  • 时段:matchDayPeriodPatterns 统一匹配 dopoledne|dop.?、odpoledne|odp.?、půlnoc、poledne、ráno、večer、noc(match/index.ts)。

长格式模板:formatLong 的四种宽度

P/PP/PPP/PPPP 与 p/pp/ppp/pppp 的模板定义于 formatLong/index.ts:

const dateFormats = {
  full: "EEEE, d. MMMM yyyy",
  long: "d. MMMM yyyy",
  medium: "d. M. yyyy",
  short: "dd.MM.yyyy",
};
const timeFormats = {
  full: "H:mm:ss zzzz",
  long: "H:mm:ss z",
  medium: "H:mm:ss",
  short: "H:mm",
};
const dateTimeFormats = {
  full: "{{date}} 'v' {{time}}",
  long: "{{date}} 'v' {{time}}",
  medium: "{{date}}, {{time}}",
  short: "{{date}}, {{time}}",
};

将快照结果与模板对照即可完全验证:

  • P → short 模板 dd.MM.yyyy → 11.02.1987;
  • PP → medium 模板 d. M. yyyy → 11. 2. 1987(注意 M 为窄数字月);
  • PPP → long 模板 d. MMMM yyyy → 11. února 1987(MMMM 属格);
  • PPPP → full 模板 EEEE, d. MMMM yyyy → středa, 11. února 1987;
  • 组合令牌中 full/long 用 v 连接(11. ledna 1987 v 12:13:14 GMT+0),medium/short 用逗号连接(11.02.1987, 12:13)。

快照文档的定位:locale 的正确性基准

snapshot.md 并非普通说明文档,而是 date-fns 每个 locale 自动生成的行为基准表:它通过固定输入日期与固定“now”时间,穷举记录每个令牌的 format 输出与 parse 回读结果,任何对 localize、match、formatLong、formatDistance、formatRelative 数据表的修改都会在快照中反映出来。因此它是排查捷克语格式化问题时的第一参考:

以快照表为准、以五个 _lib 模块为实现依据,你就能完整掌握 date-fns 捷克语 locale 的格式化、解析与相对时间语义,并为其他具有复数与格变化的语言(如波兰语、斯洛伐克语)编写 locale 提供可直接对照的范本。

登录后查看全文
date-fns