date-fns 克罗地亚语(hr)locale 完整指南:format、parse 与 formatDistance 的本地化行为速查

原创2026-09-18 17:12:582,280 阅读
文章标签:国际化跨平台前端

date-fns 克罗地亚语(hr)locale 完整指南:format、parse 与 formatDistance 的本地化行为速查

date-fns 为每种语言维护一份完整的 locale 快照文档,本文以 hr locale 快照 为骨架,结合 克罗地亚语 locale 源码 与 _lib 下的各实现模块,逐表解读克罗地亚语的 format/parse token 行为、formatDistance/formatDistanceStrict/formatRelative/formatDuration 输出,并深入讲解克罗地亚语复数规则、月份主格/属格形式、序数词与星期词尾变化等语言特性在源码中的落地方式。读完本文,你将能正确使用并校验 date-fns 的克罗地亚语本地化输出,也能理解快照测试在保证多语言一致性中的价值。

一、hr locale 的构成与全局选项

克罗地亚语 locale 定义在 pkgs/core/src/locale/hr/index.ts,它是一个符合 Locale 接口(见 pkgs/core/src/locale/types.ts)的对象,由五个核心函数/对象加上一组语言选项组成:

字段 作用 对应源码文件
code 语言代码 "hr" index.ts
formatDistance 距离措辞("3 dana"、"za 5 mjeseci") _lib/formatDistance/index.ts
formatLong 长格式模板(P/p 系列) _lib/formatLong/index.ts
formatRelative 相对时间("danas u"、"jučer u") _lib/formatRelative/index.ts
localize 年/季/月/日/时段文本与序数词 _lib/localize/index.ts
match 反向解析这些文本的正则 _lib/match/index.ts
options weekStartsOn: 1(周一),firstWeekContainsDate: 1 index.ts

其中两个全局选项直接影响所有周相关计算:weekStartsOn: 1 表示一周从星期一开始,firstWeekContainsDate: 1 表示一年中包含 1 月 1 日的那一周是第一周——克罗地亚采用与 ISO 8601 一致的周规则。快照中 Yo(本地周年份)对 1987-02-11 输出 1987. 而 parse 得到 1986-12-29(该周起始的周一),正是这套选项的体现。

使用时通过 format(date, "PPPP", { locale: hr }) 传入即可,例如:

import { format, formatDistance, hr } from "date-fns/locale";

format(new Date("1987-02-11T12:13:14"), "PPPP", { locale: hr });
// => "srijeda, 11. veljače 1987."

二、format 与 parse 全 token 速查表

快照文档的主体是一个覆盖全部 token 的 format/parse 对照表:format 列给出在给定 UTC 时间下 token 的输出,parse 列给出把该输出反解析后得到的本地时区日期。以下按类别拆分呈现,所有行为均来自 snapshot.md。

2.1 年份与季度

Title Token Date format result parse result
Calendar year yo 1987-02-11T12:13:14.015Z 1987. 1987-01-01T00:00:00.000Z
0005-01-01T12:13:14.015Z 5. 0005-01-01T00:00:00.000Z
Local week-numbering year Yo 1987-02-11T12:13:14.015Z 1987. 1986-12-29T00:00:00.000Z
0005-01-01T12:13:14.015Z 5. 0004-12-27T00:00:00.000Z
Quarter (formatting) Qo 2019-01-01T12:13:14.015Z 1. 2019-01-01T00:00:00.000Z
2019-04-01T12:13:14.015Z 2. 2019-04-01T00:00:00.000Z
QQQ 2019-01-01T12:13:14.015Z 1. kv. 2019-01-01T00:00:00.000Z
2019-04-01T12:13:14.015Z 2. kv. 2019-04-01T00:00:00.000Z
QQQQ 2019-01-01T12:13:14.015Z 1. kvartal 2019-01-01T00:00:00.000Z
2019-04-01T12:13:14.015Z 2. kvartal 2019-04-01T00:00:00.000Z
QQQQQ 2019-01-01T12:13:14.015Z 1. Invalid Date
2019-04-01T12:13:14.015Z 2. Invalid Date
Quarter (stand-alone) qo 2019-01-01T12:13:14.015Z 1. 2019-01-01T00:00:00.000Z
2019-04-01T12:13:14.015Z 2. 2019-04-01T00:00:00.000Z
qqq 2019-01-01T12:13:14.015Z 1. kv. 2019-01-01T00:00:00.000Z
2019-04-01T12:13:14.015Z 2. kv. 2019-04-01T00:00:00.000Z
qqqq 2019-01-01T12:13:14.015Z 1. kvartal 2019-01-01T00:00:00.000Z
2019-04-01T12:13:14.015Z 2. kvartal 2019-04-01T00:00:00.000Z

克罗地亚语序数词规则非常简单:数字后直接加句点。这一规则实现在 localize/index.ts 的 ordinalNumber 中:

const ordinalNumber: LocalizeFn<number> = (dirtyNumber, _options) => {
  const number = Number(dirtyNumber);
  return number + ".";
};

季度数据(quarterValues)在 localize/index.ts:narrow 为 1.–4.,abbreviated 为 1. kv.,wide 为 1. kvartal。注意快照显示 QQQQQ(窄格式季度)的 parse 返回 Invalid Date——窄格式 1. 与月份窄格式、序数词形式冲突,match 侧无法可靠反解析,这是快照记录的实际行为。

2.2 月份(formatting 与 stand-alone)

Title Token Date format result parse result
Month (formatting) Mo 2019-01-11 1. 2019-01-01
2019-02-11 2. 2019-02-01
2019-03-11 3. 2019-03-01
2019-04-10 4. 2019-04-01
2019-05-10 5. 2019-05-01
2019-06-10 6. 2019-06-01
2019-07-10 7. 2019-07-01
2019-08-10 8. 2019-08-01
2019-09-10 9. 2019-09-01
2019-10-10 10. 2019-10-01
2019-11-10 11. 2019-11-01
2019-12-10 12. 2019-12-01
MMM 2019-01-11 sij 2019-01-01
2019-02-11 velj 2019-02-01
2019-03-11 ožu 2019-03-01
2019-04-10 tra 2019-04-01
2019-05-10 svi 2019-05-01
2019-06-10 lip 2019-06-01
2019-07-10 srp 2019-07-01
2019-08-10 kol 2019-08-01
2019-09-10 ruj 2019-09-01
2019-10-10 lis 2019-10-01
2019-11-10 stu 2019-11-01
2019-12-10 pro 2019-12-01
MMMM 2019-01-11 siječnja 2019-01-01
2019-02-11 veljače 2019-02-01
2019-03-11 ožujka 2019-03-01
2019-04-10 travnja 2019-04-01
2019-05-10 svibnja 2019-05-01
2019-06-10 lipnja 2019-06-01
2019-07-10 srpnja 2019-07-01
2019-08-10 kolovoza Invalid Date
2019-09-10 rujna 2019-09-01
2019-10-10 listopada Invalid Date
2019-11-10 studenog 2019-11-01
2019-12-10 prosinca 2019-12-01
MMMMM 2019-01-11 1. 2019-01-01
2019-02-11 2. 2019-02-01
2019-03-11 3. 2019-03-01
2019-04-10 4. 2019-04-01
2019-05-10 5. 2019-05-01
2019-06-10 6. 2019-06-01
2019-07-10 7. 2019-07-01
2019-08-10 8. 2019-08-01
2019-09-10 9. 2019-09-01
2019-10-10 10. 2019-01-01
2019-11-10 11. 2019-01-01
2019-12-10 12. 2019-01-01
Month (stand-alone) Lo 2019-01-11 1. 2019-01-01
2019-02-11 2. 2019-02-01
2019-03-11 3. 2019-03-01
2019-04-10 4. 2019-04-01
2019-05-10 5. 2019-05-01
2019-06-10 6. 2019-06-01
2019-07-10 7. 2019-07-01
2019-08-10 8. 2019-08-01
2019-09-10 9. 2019-09-01
2019-10-10 10. 2019-10-01
2019-11-10 11. 2019-11-01
2019-12-10 12. 2019-12-01
LLL 2019-01-11 sij 2019-01-01
2019-02-11 velj 2019-02-01
2019-03-11 ožu 2019-03-01
2019-04-10 tra 2019-04-01
2019-05-10 svi 2019-05-01
2019-06-10 lip 2019-06-01
2019-07-10 srp 2019-07-01
2019-08-10 kol 2019-08-01
2019-09-10 ruj 2019-09-01
2019-10-10 lis 2019-10-01
2019-11-10 stu 2019-11-01
2019-12-10 pro 2019-12-01
LLLL 2019-01-11 siječanj 2019-01-01
2019-02-11 veljača 2019-02-01
2019-03-11 ožujak 2019-03-01
2019-04-10 travanj 2019-04-01
2019-05-10 svibanj 2019-05-01
2019-06-10 lipanj 2019-06-01
2019-07-10 srpanj 2019-07-01
2019-08-10 kolovoz 2019-08-01
2019-09-10 rujan 2019-09-01
2019-10-10 listopad 2019-10-01
2019-11-10 studeni 2019-11-01
2019-12-10 prosinac 2019-12-01
LLLLL 2019-01-11 1. 2019-01-01
2019-02-11 2. 2019-02-01
2019-03-11 3. 2019-03-01
2019-04-10 4. 2019-04-01
2019-05-10 5. 2019-05-01
2019-06-10 6. 2019-06-01
2019-07-10 7. 2019-07-01
2019-08-10 8. 2019-08-01
2019-09-10 9. 2019-09-01
2019-10-10 10. 2019-01-01
2019-11-10 11. 2019-01-01
2019-12-10 12. 2019-01-01

克罗地亚语月份最典型的语言特征是主格与属格(格式化)两套形式:独立使用(stand-alone,L 系列)用主格 siječanj、veljača,跟在日期后(formatting,M 系列)用属格 siječnja、veljače。这在 localize/index.ts 中通过 monthValues(主格)与 formattingMonthValues(属格)两套数组表达,并由 buildLocalizeFn 依据 context: "formatting" 自动选择。

快照里值得注意的 parse 行为:

  • MMMM 解析 kolovoza(8 月属格)与 listopada(10 月属格)返回 Invalid Date,而其它月份属格正常;从 match/index.ts 可见 wide 正则本身包含这两种形式,但快照记录的实际解析结果为 Invalid Date,属于当前已知边界行为。
  • MMMMM/LLLLL(窄格式)对 10–12 月输出 10./11./12.,parse 却得到 2019-01-01:窄格式反解析正则在 match/index.ts 中按 1..9 顺序排列,10. 会被 1 分支抢先命中,从而解析到 1 月。

2.3 周与日

Title Token Date format result parse result
Local week of year wo 2019-01-01 1. 2018-12-31
2019-12-01 48. 2019-11-25
ISO week of year Io 2019-01-01 1. 2018-12-31
2019-12-01 48. 2019-11-25
Day of month do 2019-02-01 1. 2019-02-01
2019-02-11 11. 2019-02-11
2019-02-28 28. 2019-02-28
do MMMM 2019-02-01 1. veljače 2019-02-01
2019-02-11 11. veljače 2019-02-11
2019-02-28 28. veljače 2019-02-28
Day of year Do 2019-02-11 42. 2019-02-11
2019-12-31 365. 2019-12-31
Day of week (formatting) E 2019-02-11 pon Invalid Date
2019-02-15 pet Invalid Date
EE 2019-02-11 pon Invalid Date
2019-02-15 pet Invalid Date
EEE 2019-02-11 pon Invalid Date
2019-02-15 pet Invalid Date
EEEE 2019-02-11 ponedjeljak Invalid Date
2019-02-15 petak Invalid Date
EEEEE 2019-02-11 P Invalid Date
2019-02-15 P Invalid Date
EEEEEE 2019-02-11 pon Invalid Date
2019-02-15 pet Invalid Date
ISO day of week (formatting) io 2019-02-11 1. 2019-02-11
2019-02-15 5. 2019-02-15
iii 2019-02-11 pon Invalid Date
2019-02-15 pet Invalid Date
iiii 2019-02-11 ponedjeljak Invalid Date
2019-02-15 petak Invalid Date
iiiii 2019-02-11 P Invalid Date
2019-02-15 P Invalid Date
iiiiii 2019-02-11 pon Invalid Date
2019-02-15 pet Invalid Date
Local day of week (formatting) eo 2019-02-11 1. 2019-02-11
2019-02-15 5. 2019-02-15
eee 2019-02-11 pon Invalid Date
2019-02-15 pet Invalid Date
eeee 2019-02-11 ponedjeljak Invalid Date
2019-02-15 petak Invalid Date
eeeee 2019-02-11 P Invalid Date
2019-02-15 P Invalid Date
eeeeee 2019-02-11 pon Invalid Date
2019-02-15 pet Invalid Date
Local day of week (stand-alone) co 2019-02-11 1. 2019-02-11
2019-02-15 5. 2019-02-15
ccc 2019-02-11 pon Invalid Date
2019-02-15 pet Invalid Date
cccc 2019-02-11 ponedjeljak Invalid Date
2019-02-15 petak Invalid Date
ccccc 2019-02-11 P Invalid Date
2019-02-15 P Invalid Date
cccccc 2019-02-11 pon Invalid Date
2019-02-15 pet Invalid Date

星期几数据(dayValues)在 localize/index.ts:narrow 为 N/P/U/S/Č/P/S,短/缩写形式为 ned/pon/uto/sri/čet/pet/sub,wide 为 nedjelja/ponedjeljak/utorak/srijeda/četvrtak/petak/subota。快照显示字母形式的星期 token(E/i/e/c 系列)parse 侧目前全部返回 Invalid Date,只有数字形式(io/eo/co)可以双向解析——这属于快照记录的实际行为,与 match/index.ts 中按英文前缀(/^su/、/^tu/ 等)编写的解析正则不完全对应克罗地亚语拼写有关。

2.4 上午/下午与柔性时段

Title Token Date format result parse result
AM, PM a / aa / aaaa / aaaaa 11:13 AM 00:00
14:13 PM 12:00
19:13 PM 12:00
02:13 AM 00:00
aaa 11:13 am 00:00
14:13 pm 12:00
19:13 pm 12:00
02:13 am 00:00
AM, PM, noon, midnight b / bb / bbbb / bbbbb 11:13 AM 00:00
14:13 PM 12:00
19:13 PM 12:00
02:13 AM 00:00
bbb 11:13 am 00:00
14:13 pm 12:00
19:13 pm 12:00
02:13 am 00:00
Flexible day period B / BB / BBB / BBBBB 11:13 ujutro 04:00
14:13 popodne 12:00
19:13 navečer 17:00
02:13 noću 00:00
BBBB 11:13 ujutro 04:00
14:13 poslije podne 12:00
19:13 navečer 17:00
02:13 noću 00:00

克罗地亚语没有专门的 AM/PM 词,a/b 系列直接沿用 AM/PM(aaa/bbb 为小写),而 B 系列输出自然时段词 ujutro(早晨)/popodne 或 poslije podne(下午,wide)/navečer(傍晚)/noću(夜晚)。这些词条定义在 localize/index.ts 的 formattingDayPeriodValues 与 dayPeriodValues 中,wide 的 afternoon 特意用 poslije podne 区分于 abbreviated 的 popodne。

2.5 小时、分钟与秒

Title Token Date format result parse result
Hour [1-12] ho 11:13 11. 11:00
23:13 11. 23:00
Hour [0-23] Ho 11:13 11. 11:00
23:13 23. 23:00
Hour [0-11] Ko 11:13 11. 11:00
23:13 11. 23:00
Hour [1-24] ko 11:13 11. 11:00
23:13 23. 23:00
Minute mo 12:01 1. 12:01
12:55 55. 12:55
Second so 12:13:01 1. 12:13:01
12:13:55 55. 12:13:55

所有数字单位都套用统一的序数词规则(数字 + 句点),parse 侧均能正确还原。

2.6 长日期 / 长时间 / 组合格式

Title Token Date format result parse result
Long localized date P 1987-01-11 11. 01. 1987. 1987-01-11
1987-02-11 11. 02. 1987. 1987-02-11
1987-03-11 11. 03. 1987. 1987-03-11
1987-04-11 11. 04. 1987. 1987-04-11
1453-05-29 29. 05. 1453. 1453-05-29
1987-06-11 11. 06. 1987. 1987-06-11
1987-07-11 11. 07. 1987. 1987-07-11
1987-08-11 11. 08. 1987. 1987-08-11
1987-09-11 11. 09. 1987. 1987-09-11
1987-10-11 11. 10. 1987. 1987-10-11
1987-11-11 11. 11. 1987. 1987-11-11
1987-12-11 11. 12. 1987. 1987-12-11
PP 1987-01-11 11. sij 1987. 1987-01-11
1987-02-11 11. velj 1987. 1987-02-11
1987-03-11 11. ožu 1987. 1987-03-11
1987-04-11 11. tra 1987. 1987-04-11
1453-05-29 29. svi 1453. 1453-05-29
1987-06-11 11. lip 1987. 1987-06-11
1987-07-11 11. srp 1987. 1987-07-11
1987-08-11 11. kol 1987. 1987-08-11
1987-09-11 11. ruj 1987. 1987-09-11
1987-10-11 11. lis 1987. 1987-10-11
1987-11-11 11. stu 1987. 1987-11-11
1987-12-11 11. pro 1987. 1987-12-11
PPP 1987-01-11 11. siječnja 1987. 1987-01-11
1987-02-11 11. veljače 1987. 1987-02-11
1987-03-11 11. ožujka 1987. 1987-03-11
1987-04-11 11. travnja 1987. 1987-04-11
1453-05-29 29. svibnja 1453. 1453-05-29
1987-06-11 11. lipnja 1987. 1987-06-11
1987-07-11 11. srpnja 1987. 1987-07-11
1987-08-11 11. kolovoza 1987. Invalid Date
1987-09-11 11. rujna 1987. 1987-09-11
1987-10-11 11. listopada 1987. Invalid Date
1987-11-11 11. studenog 1987. 1987-11-11
1987-12-11 11. prosinca 1987. 1987-12-11
PPPP 1987-01-11 nedjelja, 11. siječnja 1987. 1987-01-11
1987-02-11 srijeda, 11. veljače 1987. 1987-02-11
1987-03-11 srijeda, 11. ožujka 1987. 1987-03-11
1987-04-11 subota, 11. travnja 1987. 1987-04-11
1453-05-29 nedjelja, 29. svibnja 1453. 1453-05-29
1987-06-11 četvrtak, 11. lipnja 1987. 1987-06-11
1987-07-11 subota, 11. srpnja 1987. 1987-07-11
1987-08-11 utorak, 11. kolovoza 1987. Invalid Date
1987-09-11 petak, 11. rujna 1987. 1987-09-11
1987-10-11 nedjelja, 11. listopada 1987. Invalid Date
1987-11-11 srijeda, 11. studenog 1987. 1987-11-11
1987-12-11 petak, 11. prosinca 1987. 1987-12-11
Long localized time p 12:13 12:13 12:13:00
23:59 (1453-05-29) 23:59 23:59:00
pp 12:13:14 12:13:14 12:13:14
23:59:59 (1453-05-29) 23:59:59 23:59:59
ppp 12:13:14 12:13:14 GMT+0 Errored
23:59:59 (1453-05-29) 23:59:59 GMT+0 Errored
pppp 12:13:14 12:13:14 (GMT+00:00) Errored
23:59:59 (1453-05-29) 23:59:59 (GMT+00:00) Errored
Combination Pp 1987-01-11 11. 01. 1987. 12:13 1987-01-11 12:13
1453-05-29 29. 05. 1453. 23:59 1453-05-29 23:59
PPpp 1987-01-11 11. sij 1987. 12:13:14 1987-01-11 12:13:14
1453-05-29 29. svi 1453. 23:59:59 1453-05-29 23:59:59
PPPppp 1987-01-11 11. siječnja 1987. u 12:13:14 GMT+0 Errored
1987-08-11 11. kolovoza 1987. u 12:13:14 GMT+0 Invalid Date
1987-10-11 11. listopada 1987. u 12:13:14 GMT+0 Invalid Date
PPPPpppp 1987-01-11 nedjelja, 11. siječnja 1987. u 12:13:14 (GMT+00:00) Errored
1987-08-11 utorak, 11. kolovoza 1987. u 12:13:14 (GMT+00:00) Invalid Date
1987-10-11 nedjelja, 11. listopada 1987. u 12:13:14 (GMT+00:00) Invalid Date

这些组合格式的模板定义在 formatLong/index.ts:

const dateFormats = {
  full: "EEEE, d. MMMM y.",   // PPPP
  long: "d. MMMM y.",          // PPP
  medium: "d. MMM y.",         // PP
  short: "dd. MM. y.",         // P
};
const timeFormats = {
  full: "HH:mm:ss (zzzz)",     // pppp
  long: "HH:mm:ss z",          // ppp
  medium: "HH:mm:ss",          // pp
  short: "HH:mm",              // p
};
const dateTimeFormats = {
  full: "{{date}} 'u' {{time}}",   // 用引号包裹的 "u"(克罗地亚语 "at")
  long: "{{date}} 'u' {{time}}",
  medium: "{{date}} {{time}}",
  short: "{{date}} {{time}}",
};

由此可以解释快照中的三类行为:

  1. ppp/pppp 的 parse 为 Errored:时间格式含时区缩写(z/zzzz),date-fns 的 parse 不支持解析时区名缩写,因此报错而非返回 Invalid Date。
  2. 日期时间组合中的 u:PPPppp/PPPPpppp 输出形如 11. siječnja 1987. u 12:13:14 GMT+0,u 是克罗地亚语介词 "在…时",模板中用单引号 'u' 转义为字面量。
  3. 8 月与 10 月的属格解析问题在长格式中同样出现(kolovoza/listopada 返回 Invalid Date),与 2.2 节一致,属于贯穿所有 MMMM 相关 token 的已知边界行为。

三、formatDistance:克罗地亚语复数与介词后缀

快照假设"现在"为 2000 年 1 月 1 日 00:00,以下为完整对照(省略部分重复行,完整行为见 snapshot.md):

Date Result includeSeconds: true addSuffix: true
2006-01-01 oko 6 godina oko 6 godina za oko 6 godina
2005-01-01 oko 5 godina oko 5 godina za oko 5 godina
2004-01-01 oko 4 godine oko 4 godine za oko 4 godine
2003-01-01 oko 3 godine oko 3 godine za oko 3 godine
2002-01-01 oko 2 godine oko 2 godine za oko 2 godine
2001-06-01 preko 1 godinu preko 1 godinu za preko 1 godinu
2001-02-01 oko 1 godinu oko 1 godinu za oko 1 godinu
2001-01-01 oko 1 godinu oko 1 godinu za oko 1 godinu
2000-06-01 5 mjeseci 5 mjeseci za 5 mjeseci
2000-03-01 2 mjeseca 2 mjeseca za 2 mjeseca
2000-02-01 oko 1 mjesec oko 1 mjesec za oko 1 mjesec
2000-01-15 14 dana 14 dana za 14 dana
2000-01-02 1 dan 1 dan za 1 dan
2000-01-01T06:00 oko 6 sati oko 6 sati za oko 6 sati
2000-01-01T01:00 oko 1 sat oko 1 sat za oko 1 sat
2000-01-01T00:45 oko 1 sat oko 1 sat za oko 1 sat
2000-01-01T00:30 30 minuta 30 minuta za 30 minuta
2000-01-01T00:15 15 minuta 15 minuta za 15 minuta
2000-01-01T00:01 1 minuta 1 minuta za 1 minutu
2000-01-01T00:00:25 manje od 1 minute pola minute za manje od 1 minutu
2000-01-01T00:00:15 manje od 1 minute manje od 20 sekundi za manje od 1 minutu
2000-01-01T00:00:05 manje od 1 minute manje od 10 sekundi za manje od 1 minutu
2000-01-01T00:00:00 manje od 1 minute manje od 5 sekundi prije manje od 1 minute
1999-12-31T23:59:55 manje od 1 minute manje od 10 sekundi prije manje od 1 minute
1999-12-31T23:59:45 manje od 1 minute manje od 20 sekundi prije manje od 1 minute
1999-12-31T23:59:35 manje od 1 minute pola minute prije manje od 1 minute
1999-12-31T23:59:00 1 minuta 1 minuta prije 1 minute
1999-12-31T23:45 15 minuta 15 minuta prije 15 minuta
1999-12-31T23:30 30 minuta 30 minuta prije 30 minuta
1999-12-31T23:15 oko 1 sat oko 1 sat prije oko 1 sat
1999-12-31T23:00 oko 1 sat oko 1 sat prije oko 1 sat
1999-12-31T18:00 oko 6 sati oko 6 sati prije oko 6 sati
1999-12-30 2 dana 2 dana prije 2 dana
1999-12-15 17 dana 17 dana prije 17 dana
1999-12-01 oko 1 mjesec oko 1 mjesec prije oko 1 mjesec
1999-11-01 2 mjeseca 2 mjeseca prije 2 mjeseca
1999-06-01 7 mjeseci 7 mjeseci prije 7 mjeseci
1999-01-01 oko 1 godinu oko 1 godinu prije oko 1 godinu
1998-12-01 oko 1 godinu oko 1 godinu prije oko 1 godinu
1998-06-01 preko 1 godinu preko 1 godinu prije preko 1 godinu
1998-01-01 oko 2 godine oko 2 godine prije oko 2 godine
1997-01-01 oko 3 godine oko 3 godine prije oko 3 godine
1996-01-01 oko 4 godine oko 4 godine prije oko 4 godine
1995-01-01 oko 5 godina oko 5 godina prije oko 5 godina
1994-01-01 oko 6 godina oko 6 godina prije oko 6 godina

3.1 克罗地亚语的三段式复数规则

formatDistance 的核心逻辑在 _lib/formatDistance/index.ts。每个数值型 token 都带 one / dual / other 三套词形,选择规则为:

} else if (
  count % 10 > 1 &&
  count % 10 < 5 && // 末位数字在 2~4 之间
  String(count).substr(-2, 1) !== "1" // 且倒数第二位不是 "1"
) {
  result = tokenValue.dual.replace("{{count}}", String(count));
} else {
  result = tokenValue.other.replace("{{count}}", String(count));
}

这正对应克罗地亚语的格变化规则:

  • one(1):1 godina、1 mjesec、1 minuta;
  • dual(2–4,但 12–14 除外):2 godine、3 mjeseca、2 minute;14 dana 走 other 因为 14 末位 4 但倒数第二位是 1;
  • other(5+ 及 11–14 等):5 godina、30 minuta、17 dana。

3.2 介词后缀:za(未来)与 prije(过去)

当 addSuffix: true 时,未来时间加前缀 za ,过去时间加前缀 prije (见 formatDistance/index.ts)。同时,count 为 1 时还要在词形内部区分格位:options.comparison > 0(未来)使用 withPrepositionIn(如 1 minutu、1 sekundu),否则使用 withPrepositionAgo(如 1 minute、1 sekunde)。快照中的 za 1 minutu vs prije 1 minute 正是这套机制的直接体现。

四、formatDistanceStrict:精确距离与强制单位

同样以"现在"为 2000-01-01 00:00,严格模式不做"约"的模糊化(完整表格见 snapshot.md,以下为主要行):

Date Result addSuffix: true With forced unit (hour)
2006-01-01 6 godina za 6 godina 52608 sati
2005-01-01 5 godina za 5 godina 43848 sati
2004-01-01 4 godine za 4 godine 35064 sata
2003-01-01 3 godine za 3 godine 26304 sata
2002-01-01 2 godine za 2 godine 17544 sata
2001-06-01 1 godina za 1 godinu 12408 sati
2001-02-01 1 godina za 1 godinu 9528 sati
2001-01-01 1 godina za 1 godinu 8784 sata
2000-06-01 5 mjeseci za 5 mjeseci 3648 sati
2000-03-01 2 mjeseca za 2 mjeseca 1440 sati
2000-02-01 1 mjesec za 1 mjesec 744 sata
2000-01-15 14 dana za 14 dana 336 sati
2000-01-02 1 dan za 1 dan 24 sata
2000-01-01T06:00 6 sati za 6 sati 6 sati
2000-01-01T01:00 1 sat za 1 sat 1 sat
2000-01-01T00:45 45 minuta za 45 minuta 1 sat
2000-01-01T00:30 30 minuta za 30 minuta 1 sat
2000-01-01T00:15 15 minuta za 15 minuta 0 sati
2000-01-01T00:01 1 minuta za 1 minutu 0 sati
2000-01-01T00:00:25 25 sekundi za 25 sekundi 0 sati
2000-01-01T00:00:00 0 sekundi prije 0 sekundi 0 sati
1999-12-31T23:59:00 1 minuta prije 1 minute 0 sati
1999-12-31T23:30 30 minuta prije 30 minuta 1 sat
1999-12-31T23:00 1 sat prije 1 sat 1 sat
1999-12-31T18:00 6 sati prije 6 sati 6 sati
1999-12-30 2 dana prije 2 dana 48 sati
1999-12-15 17 dana prije 17 dana 408 sati
1999-12-01 1 mjesec prije 1 mjesec 744 sata
1999-11-01 2 mjeseca prije 2 mjeseca 1464 sata
1999-06-01 7 mjeseci prije 7 mjeseci 5136 sati
1999-01-01 1 godina prije 1 godine 8760 sati
1998-06-01 2 godine prije 2 godine 13896 sati
1994-01-01 6 godina prije 6 godina 52584 sata

严格模式同样复用 formatDistance 的词形表,因此复数与格位规则完全一致(如 za 1 minutu/prije 1 minute、2 godine/5 godina)。当通过 unit: "hour" 强制单位时,输出统一换算为小时并按小时词形变化(1 sat/2 sata/5 sati)。

五、formatRelative:上周/下周的阴阳性变化

假设"现在"为 2000-01-01 00:00(周六),快照结果:

Date Result
2000-01-10 10. 01. 2000.
2000-01-05 iduću srijedu u 00:00
2000-01-02 sutra u 00:00
2000-01-01 danas u 00:00
1999-12-31 jučer u 00:00
1999-12-27 prošli ponedjeljak u 00:00
1999-12-21 21. 12. 1999.

实现在 _lib/formatRelative/index.ts。lastWeek/nextWeek 是按星期几分派的函数:星期日、星期三、星期六使用阴性词尾 prošlu nedjelju/prošlu srijedu/prošlu subotu 与 iduću nedjelju/iduću srijedu/iduću subotu(因 "nedjelja/srijeda/subota" 为阴性名词),其余星期使用阳性形式 prošli + EEEE。快照中 2000-01-05(周三)输出 iduću srijedu u 00:00、1999-12-27(周一)输出 prošli ponedjeljak u 00:00,正是该逻辑的结果。超出上周/下周范围的日期(如 2000-01-10)回退到长日期格式 P(10. 01. 2000.)。

六、formatDuration:持续时间词形

快照完整结果:

Duration Result
{"years":0} 0 godina
{"years":1} 1 godina
{"years":2} 2 godine
{"months":0} 0 mjeseci
{"months":1} 1 mjesec
{"months":2} 2 mjeseca
{"weeks":0} 0 tjedana
{"weeks":1} 1 tjedan
{"weeks":2} 2 tjedna
{"days":0} 0 dana
{"days":1} 1 dan
{"days":2} 2 dana
{"hours":0} 0 sati
{"hours":1} 1 sat
{"hours":2} 2 sata
{"minutes":0} 0 minuta
{"minutes":1} 1 minuta
{"minutes":2} 2 minute
{"seconds":0} 0 sekundi
{"seconds":1} 1 sekunda
{"seconds":2} 2 sekunde

formatDuration 直接消费 formatDistanceLocale 中 x* 系列 token 的词形(见 _lib/formatDistance/index.ts),因此 0/1/2 三档输出严格遵循 one/dual/other 规则:1 sat、2 sata、0 sati;1 tjedan、2 tjedna、0 tjedana。注意周的单位词 tjedan 出现在 aboutXWeeks/xWeeks 词条中,而快照的 formatDistance 主表未单列周行(距离过近时不会落到周单位),formatDuration 恰好补全了周词形的验证。

七、反向解析(match):正则如何匹配克罗地亚语

parse 侧依赖 _lib/match/index.ts,它用正则表把本地化文本映射回数值:

  • 序数词:/^(\d+)\./i 匹配 1987.、11.(match/index.ts);
  • 月份缩写:/^(sij|velj|(ožu|ozu)|tra|svi|lip|srp|kol|ruj|lis|stu|pro)/i,其中 ožu 同时兼容无变音符拼写 ozu;wide 形式同时收录主格与属格(siječanj|siječnja、listopad|listopada 等,match/index.ts);
  • 星期:wide 正则收录 nedjelja|ponedjeljak|utorak|srijeda|(četvrtak|cetvrtak)|petak|subota(match/index.ts);
  • 时段:/^(am|pm|ponoc|ponoć|(po)?podne|navecer|navečer|noću|poslije podne|ujutro)/i(match/index.ts),同样为无变音符的 ASCII 拼写(ponoc、navecer)保留兼容分支。

这些正则经 buildMatchFn 与 buildMatchPatternFn 两个通用构造器装配成 match 对象,供 parse 在解析 token 时调用。快照中出现的 Invalid Date 与 Errored 行,正是这些正则与格式输出之间现存差异的直接记录——这也是快照文档最重要的价值:把每个 token 的 format 与 parse 行为固化下来,任何后续改动导致的输出变化都能被快照测试立刻捕获。

八、快照的定位与使用建议

snapshot.md 位于 locale 目录内(如 pkgs/core/src/locale/hr/snapshot.md),与实现源码(index.ts 与 _lib/ 五个子模块)一一对应,本质上是该 locale 的行为回归基线。实际开发中建议:

  1. 格式化克罗地亚语日期:优先使用 P–PPPP/p–pppp 组合,并传入 { locale: hr },避免手工拼接容易犯的属格/主格错误;
  2. 时间戳展示:用 formatDistance/formatRelative 输出自然语言,注意克罗地亚语的 one/dual/other 三态与 za/prije 后缀由库自动处理;
  3. 警惕已知边界:如需用 parse 反解析克罗地亚语文本,避开快照中标记为 Invalid Date/Errored 的 token 组合(窄格式季度/月份、星期字母形式、含时区缩写的 ppp/pppp、8 月与 10 月的属格形式),或对解析结果做 isValid 校验;
  4. 贡献与回归:若修改 hr locale 的实现,请同步核对本快照表格,确保既有行为未被破坏。
登录后查看全文
date-fns