date-fns 捷克语(cs)locale 完全指南:format/parse 令牌行为、复数规则与相对时间本地化
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 |
三个关键结论(快照中的隐藏信息)
- 序数词一律加句点:捷克语的序数形式通过
数字 + "."表达(1987.、1.、11.、365.)。其实现位于 localize/index.ts:
const ordinalNumber: LocalizeFn<number> = (dirtyNumber, _options) => {
const number = Number(dirtyNumber);
return number + ".";
};
-
5 字符窄宽度(
EEEEE/iiiii/eeeee/ccccc)不可被 parse:快照中这些令牌的parse结果均为Invalid Date。这是因为窄宽度只保留了首字母缩写(如po、pá),而 match/index.ts 的解析模式仅覆盖narrow与any两种宽度,窄宽度映射的abbreviated解析模式无法唯一确定星期。 -
含时区偏移的令牌(
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 hodin2000-01-02(1 天前)→24 hodin2000-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 数据表的修改都会在快照中反映出来。因此它是排查捷克语格式化问题时的第一参考:
- 若某个令牌输出与预期不符,先在 snapshot.md 查该令牌的基准值;
- 若需追溯输出来源,沿 localize/index.ts(数据表)→ formatLong/index.ts(长格式模板)→ formatDistance/index.ts(复数/时态)→ formatRelative/index.ts(相对时间)→ match/index.ts(解析正则)逐层核对;
- 遇到 parse 失败时,优先检查
match模块中对应单位的正则是否覆盖了该宽度与词形。
以快照表为准、以五个 _lib 模块为实现依据,你就能完整掌握 date-fns 捷克语 locale 的格式化、解析与相对时间语义,并为其他具有复数与格变化的语言(如波兰语、斯洛伐克语)编写 locale 提供可直接对照的范本。