date-fns 爱沙尼亚语etLocale 全解析基于 snapshot 快照的 format/parse 令牌与本地化实现指南【免费下载链接】date-fns⏳ Modern JavaScript date utility library ⌛️项目地址: https://gitcode.com/gh_mirrors/da/date-fnsdate-fns 的每个 locale 目录下都有一份snapshot.md它是该语言本地化行为的「验证快照」覆盖format/parse全部令牌、formatDistance、formatDistanceStrict、formatRelative与formatDuration的输出样例。本文以 爱沙尼亚语 locale 快照 为骨架结合 et locale 源码 及其_lib下的实现逐令牌讲解爱沙尼亚语日期格式化的输出规则、可解析性含Invalid Date与Errored的边界行为、序数词与变格declension处理读完你既能直接用etlocale 格式化爱沙尼亚语日期也能读懂 date-fns locale 快照的验证语义。一、snapshot.md 是什么locale 的自动验证快照snapshot.md不是手写文档而是 date-fns 用于测试 locale 的自动生成快照。正如 i18n 贡献指南 所述测试 locale 时使用快照生成命令为pnpm run locale-snapshots生成后快照会出现在对应 locale 目录下如src/locales/ru/snapshot.md。做完 locale 后生成快照并人工审查输出值即可确认每个令牌的行为是否符合该语言习惯。因此et/snapshot.md 实质上是一份「可运行的验证基准」表格中的每个format结果和parse结果都对应一条测试断言。阅读它的价值在于快速查阅每个日期令牌在爱沙尼亚语下的真实输出无需自己跑代码了解哪些字符串可以回解析parse、哪些不能表中明确标注Invalid Date与Errored作为实现参考对应到 localize、match、formatLong 等源码模块。二、et locale 结构总览五个模块与两个选项et/index.ts 导出一个标准Locale对象结构定义见 locale/types.tsexport const et: Locale { code: et, formatDistance, // 距离词含变格与 pärast/eest 后缀 formatLong, // 长日期/长时间模板P、PP、PPP、PPPP 等 formatRelative,// 相对时间eile/täna/homme 等 localize, // 世纪、季度、月份、星期、时段词的本地化 match, // 用于 parse 的正则匹配 options: { weekStartsOn: 1 /* Monday */, firstWeekContainsDate: 4, }, };两个关键选项决定了周的语义weekStartsOn: 1爱沙尼亚语环境周一为一周之始影响E/e/c/i系列星期令牌与startOfWeek等函数firstWeekContainsDate: 4一年中的第一周是包含 1 月 4 日的那一周与 ISO 8601 周编号约定一致影响Yo、wo等周编号令牌。使用时只需把et传给任何接受locale选项的函数import { format, parse, formatDistance, formatRelative } from date-fns; import { et } from date-fns/locale; format(new Date(1987, 1, 11), PPPP, { locale: et }); // kolmapäev, 11. veebruar 1987 formatDistance(new Date(2001, 0, 1), new Date(2000, 0, 1), { locale: et, addSuffix: true }); // umbes ühe aasta pärast三、format 与 parse令牌行为速查表以下表格逐行继承自 et/snapshot.md 的format/parse部分。format结果即该令牌在爱沙尼亚语下的输出parse结果表示用parse解析该输出得到的日期其中Invalid Date、Errored表示无法回解析。所有日期均为 UTC。3.1 年、季度Calendar year / Local week-numbering year / Quarter类别令牌输入日期format 结果parse 结果Calendar yearyo1987-02-11T12:13:14.015Z1987.1987-01-01T00:00:00.000Z0005-01-01T12:13:14.015Z5.0005-01-01T00:00:00.000ZLocal week-numbering yearYo1987-02-11T12:13:14.015Z1987.1986-12-29T00:00:00.000Z0005-01-01T12:13:14.015Z4.0003-12-29T00:00:00.000ZQuarter (formatting)Qo2019-01-01T12:13:14.015Z1.2019-01-01T00:00:00.000Z2019-04-01T12:13:14.015Z2.2019-04-01T00:00:00.000ZQQQ2019-01-01T12:13:14.015ZK12019-01-01T00:00:00.000Z2019-04-01T12:13:14.015ZK22019-04-01T00:00:00.000ZQQQQ2019-01-01T12:13:14.015Z1. kvartal2019-01-01T00:00:00.000Z2019-04-01T12:13:14.015Z2. kvartal2019-04-01T00:00:00.000ZQQQQQ2019-01-01T12:13:14.015Z12019-01-01T00:00:00.000Z2019-04-01T12:13:14.015Z22019-04-01T00:00:00.000ZQuarter (stand-alone)qo2019-01-01T12:13:14.015Z1.2019-01-01T00:00:00.000Z2019-04-01T12:13:14.015Z2.2019-04-01T00:00:00.000Zqqq2019-01-01T12:13:14.015ZK12019-01-01T00:00:00.000Z2019-04-01T12:13:14.015ZK22019-04-01T00:00:00.000Zqqqq2019-01-01T12:13:14.015Z1. kvartal2019-01-01T00:00:00.000Z2019-04-01T12:13:14.015Z2. kvartal2019-04-01T00:00:00.000Z对应源码在 localize/index.ts季度缩写固定为K1~K4宽格式为1. kvartal等buildLocalizeFn通过argumentCallback: (quarter) quarter - 1做下标转换。注意快照中yo/Qo/qo的 parse 结果都落在所在年/季度的第一天这是 ordinal 数字令牌的标准解析行为。3.2 月份Month formatting 与 stand-alone令牌2019 年各月输入格式化的日期format 结果序列parse 结果Mo序数2019-01-11 ~ 2019-12-101. / 2. / 3. / 4. / 5. / 6. / 7. / 8. / 9. / 10. / 11. / 12.各月 1 日 00:00:00.000ZMMM缩写同上jaan / veebr / märts / apr / mai / juuni / juuli / aug / sept / okt / nov / dets各月 1 日 00:00:00.000ZMMMM全称同上jaanuar / veebruar / märts / aprill / mai / juuni / juuli / august / september / oktoober / november / detsember各月 1 日 00:00:00.000ZMMMMM窄形同上J / V / M / A / M / J / J / A / S / O / N / D见下方说明Lo序数stand-alone同上1. ~ 12.各月 1 日 00:00:00.000ZLLL缩写同上jaan / veebr / märts / apr / mai / juuni / juuli / aug / sept / okt / nov / dets各月 1 日 00:00:00.000ZLLLL全称同上jaanuar ~ detsember各月 1 日 00:00:00.000ZLLLLL窄形同上J / V / M / A / M / J / J / A / S / O / N / D见下方说明完整逐行数据见 snapshot.md。爱沙尼亚语月份词源数据在 localize/index.ts缩写、全称、窄形三套并排定义且month与day都同时提供formattingValues保证在句子中与独立使用时措辞一致。窄形月份的解析歧义重要边界快照中MMMMM/LLLLL的 parse 结果并非总是「回到原月份」。例如5 月窄形Mmai→ parse 得2019-03-013 月märts6 月Jjuuni、7 月Jjuuli→ 都 parse 得2019-01-011 月jaanuar3 月M、1 月J、8 月A、9 月S等才正确回解析。原因在 match/index.ts 的parseMonthPatterns.narrow它按下标依次使用/^j/, /^v/, /^m/, /^a/, /^m/, /^j/, /^j/, /^a/, /^s/, /^o/, /^n/, /^d/即「取第一个匹配的下标」——M首先命中下标 2märtsJ首先命中下标 0jaanuar。这正是爱沙尼亚语窄形月份字母天然存在歧义J 对应 jaanuar/juuni/juuliM 对应 märts/mai快照如实记录了这一行为提示在实际业务中不要用窄形月份做双向往返解析。3.3 周编号与日week / day of month / day of year / day of week类别令牌输入日期format 结果parse 结果Local week of yearwo2019-01-01T12:13:14.015Z1.2018-12-31T00:00:00.000Z2019-12-01T12:13:14.015Z48.2019-11-25T00:00:00.000ZISO week of yearIo2019-01-01T12:13:14.015Z1.2018-12-31T00:00:00.000Z2019-12-01T12:13:14.015Z48.2019-11-25T00:00:00.000ZDay of monthdo2019-02-01T12:13:14.015Z1.2019-02-01T00:00:00.000Z2019-02-11T12:13:14.015Z11.2019-02-11T00:00:00.000Z2019-02-28T12:13:14.015Z28.2019-02-28T00:00:00.000Zdo MMMM2019-02-01T12:13:14.015Z1. veebruar2019-02-01T00:00:00.000Z2019-02-11T12:13:14.015Z11. veebruar2019-02-11T00:00:00.000Z2019-02-28T12:13:14.015Z28. veebruar2019-02-28T00:00:00.000ZDay of yearDo2019-02-11T12:13:14.015Z42.2019-02-11T00:00:00.000Z2019-12-31T12:13:14.015Z365.2019-12-31T00:00:00.000Z星期系列以周一2019-02-11与周五2019-02-15为例类别令牌format 结果周一 / 周五parse 结果周一 / 周五Day of week (formatting)E / EE / EEEesmasp. / reede.Invalid Date / Invalid DateEEEEesmaspäev / reede2019-02-11 / 2019-02-15EEEEE / EEEEEEE / R2019-02-11 / 2019-02-15ISO day of weekio1. / 5.2019-02-11 / 2019-02-15iiiesmasp. / reede.Invalid Date / Invalid Dateiiiiesmaspäev / reede2019-02-11 / 2019-02-15iiiii / iiiiiiE / R2019-02-11 / 2019-02-15Local day of week (formatting)eo1. / 5.2019-02-11 / 2019-02-15eeeesmasp. / reede.Invalid Date / Invalid Dateeeeeesmaspäev / reede2019-02-11 / 2019-02-15eeeee / eeeeeeE / R2019-02-11 / 2019-02-15Local day of week (stand-alone)co1. / 5.2019-02-11 / 2019-02-15cccesmasp. / reede.Invalid Date / Invalid Dateccccesmaspäev / reede2019-02-11 / 2019-02-15ccccc / ccccccE / R2019-02-11 / 2019-02-15星期词源数据在 localize/index.tsnarrow/short都是单字母P E T K N R Labbreviated为带句点的pühap. esmasp. teisip. kolmap. neljap. reede. laup.wide为完整词。匹配规则在 match/index.ts缩写形如/^(püh?|esm?|tei?|kolm?|nel?|ree?|laup?)\.?/i。值得注意的可解析性差异缩写形esmasp./reede.只能格式化无法通过parse回解析快照中记为Invalid Date而全称形esmaspäev/reede与窄形E/R都可以正常往返。快照的parse列正是用来暴露这类不对称行为的——在设计用户输入解析方案时应优先接受全称或窄形避免依赖缩写形。3.4 一天中的时段与时刻AM/PM、灵活时段、小时/分/秒类别令牌输入日期format 结果parse 结果AM, PMa / aa / aaaa / aaaaa11:13 / 14:13 / 19:13 / 02:13AM / PM / PM / AM00:00 / 12:00 / 12:00 / 00:00aaa / bbb同上am / pm / pm / am00:00 / 12:00 / 12:00 / 00:00AM, PM, noon, midnightb / bb / bbbb / bbbbb同上AM / PM / PM / AM00:00 / 12:00 / 12:00 / 00:00Flexible day periodB / BB / BBB / BBBB / BBBBB11:13 / 14:13 / 19:13 / 02:13hommikul / pärastlõunal / õhtul / öösel04:00 / 12:00 / 17:00 / 00:00Hour [1-12]ho11:13 / 23:1311. / 11.11:00 / 23:00Hour [0-23]Ho11:13 / 23:1311. / 23.11:00 / 23:00Hour [0-11]Ko11:13 / 23:1311. / 11.11:00 / 23:00Hour [1-24]ko11:13 / 23:1311. / 23.11:00 / 23:00Minutemo12:01 / 12:551. / 55.12:01:00 / 12:55:00Secondso12:13:01 / 12:13:551. / 55.12:13:01 / 12:13:55时段词在 localize/index.ts 中分为两套dayPeriodValues独立语境hommik/pärastlõuna/õhtu/öö与formattingDayPeriodValues句子中带词尾hommikul/pärastlõunal/õhtul/öösel——即快照中B系列的实际输出属于爱沙尼亚语「内格/状语」形式的典型本地化处理。B系列 parse 出的时间点04:00 / 12:00 / 17:00 / 00:00来自 match/index.ts 的parseDayPeriodPatterns分别映射 morning/afternoon/evening/night 的默认时刻。3.5 本地化长日期与长时间P/p 系列P系列模板定义在 formatLong/index.tsconst 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}} kell {{time}}, long: {{date}} kell {{time}}, medium: {{date}}. {{time}}, short: {{date}}. {{time}}, };dateTimeFormats中的kell是爱沙尼亚语「时钟/在……点」的介词词组合令牌Pp、PPpp、PPPppp、PPPPpppp由它拼接日期与时间。完整样例表format列与parse列均取自 snapshot.md令牌示例输入format 结果parse 结果P1987-01-11 ~ 1987-12-11每月 11 日11.01.1987 / 11.02.1987 / 11.03.1987 / 11.04.1987 / 29.05.1453 / 11.06.1987 / 11.07.1987 / 11.08.1987 / 11.09.1987 / 11.10.1987 / 11.11.1987 / 11.12.1987对应日期 00:00:00.000ZPP同上11. jaan 1987 / 11. veebr 1987 / 11. märts 1987 / 11. apr 1987 / 29. mai 1453 / 11. juuni 1987 / 11. juuli 1987 / 11. aug 1987 / 11. sept 1987 / 11. okt 1987 / 11. nov 1987 / 11. dets 1987对应日期 00:00:00.000ZPPP同上11. jaanuar 1987 / 11. veebruar 1987 / 11. märts 1987 / 11. aprill 1987 / 29. mai 1453 / 11. juuni 1987 / 11. juuli 1987 / 11. august 1987 / 11. september 1987 / 11. oktoober 1987 / 11. november 1987 / 11. detsember 1987对应日期 00:00:00.000ZPPPP同上pühapäev, 11. jaanuar 1987 / kolmapäev, 11. veebruar 1987 / kolmapäev, 11. märts 1987 / laupäev, 11. aprill 1987 / pühapäev, 29. mai 1453 / neljapäev, 11. juuni 1987 / laupäev, 11. juuli 1987 / teisipäev, 11. august 1987 / reede, 11. september 1987 / pühapäev, 11. oktoober 1987 / kolmapäev, 11. november 1987 / reede, 11. detsember 1987对应日期 00:00:00.000Zp各月 11 日 12:13:14 / 1453-05-29 23:59:5912:13 / 12:13 / … / 23:59对应日期 12:13:00 / 23:59:00pp同上12:13:14 / … / 23:59:59对应日期 完整时分秒ppp同上12:13:14 GMT0 / … / 23:59:59 GMT0Erroredpppp同上12:13:14 GMT00:00 / … / 23:59:59 GMT00:00ErroredPp同上11.01.1987. 12:13 / … / 29.05.1453. 23:59对应日期 时分PPpp同上11. jaan 1987. 12:13:14 / … / 29. mai 1453. 23:59:59对应日期 完整时分秒PPPppp同上11. jaanuar 1987 kell 12:13:14 GMT0 / … / 29. mai 1453 kell 23:59:59 GMT0ErroredPPPPpppp同上pühapäev, 11. jaanuar 1987 kell 12:13:14 GMT00:00 / … / reede, 11. detsember 1987 kell 12:13:14 GMT00:00Errored时区令牌不可回解析ppp/pppp及其组合的parse结果均为Errored。这是因为HH:mm:ss z/zzzz这类带时区GMT0/GMT00:00的输出在爱沙尼亚语 locale 的match模块中没有对应的时区解析规则快照用Errored明确标记「格式化可用、解析失败」的组合。如果业务需要同时保证双向解析应避免使用ppp/pppp改用pp及以下宽度。四、formatDistance变格、单复数与 pärast/eest 后缀快照的formatDistance部分假设「当前时间是 2000 年 1 月 1 日 00:00」覆盖过去与未来两个方向。完整逐行数据见 snapshot.md代表性片段如下输入日期结果includeSeconds: trueaddSuffix: true2006-01-01umbes 6 aastatumbes 6 aastatumbes 6 aasta pärast2001-06-01rohkem kui üks aasta同左rohkem kui ühe aasta pärast2001-01-01umbes üks aasta同左umbes ühe aasta pärast2000-06-015 kuud5 kuud5 kuu pärast2000-01-1514 päeva14 päeva14 päeva pärast2000-01-01T06:00umbes 6 tundi同左umbes 6 tunni pärast2000-01-01T00:45umbes üks tund同左umbes ühe tunni pärast2000-01-01T00:01üks minut同左ühe minuti pärast2000-01-01T00:00:25vähem kui üks minutpool minutitvähem kui ühe minuti pärast2000-01-01T00:00:00vähem kui üks minutvähem kui 5 sekunditvähem kui ühe minuti eest1999-12-31T23:59:00üks minut同左ühe minuti eest1999-12-302 päeva2 päeva2 päeva eest1999-11-012 kuud2 kuud2 kuu eest1999-01-01umbes üks aasta同左umbes ühe aasta eest1994-01-01umbes 6 aastat同左umbes 6 aasta eest其实现是 formatDistance/index.ts核心机制有两点独立形与介词形standalone / withPreposition双套模板每个 token 都定义standalone与withPreposition两组词形options.addSuffix为真时走withPreposition。这正是爱沙尼亚语属格变格的体现——例如5 kuud主格独立使用在带后缀时变为5 kuu pärastüks aasta变为ühe aasta pärastüks minut变为ühe minuti pärast。词形在 formatDistance/index.ts 中逐 token 声明共覆盖lessThanXSeconds、xSeconds、halfAMinute、lessThanXMinutes、xMinutes、aboutXHours、xHours、xDays、aboutXWeeks、xWeeks、aboutXMonths、xMonths、aboutXYears、xYears、overXYears、almostXYears全部 16 种距离 token。后缀方向由comparison决定options.addSuffix时未来comparison 0追加pärast“之后”过去追加eest“之前”——见 formatDistance/index.ts。comparison的取值范围在 locale/types.ts 中定义为-1 | 0 | 1。这一设计让同一个模板函数同时服务formatDistance与formatDistanceToNow等 API。五、formatDistanceStrict严格距离的确定性输出formatDistanceStrict不引入「约/多于一」的模糊措辞直接给出精确单位且addSuffix同样触发属格变格与pärast/eest后缀。快照snapshot.md关键行为如下输入日期结果addSuffix: true强制单位 hour2006-01-016 aastat6 aasta pärast52608 tundi2005-01-015 aastat5 aasta pärast43848 tundi2004-01-014 aastat4 aasta pärast35064 tundi2003-01-013 aastat3 aasta pärast26304 tundi2002-01-012 aastat2 aasta pärast17544 tundi2001-06-01üks aastaühe aasta pärast12408 tundi2001-01-01üks aastaühe aasta pärast8784 tundi2000-06-015 kuud5 kuu pärast3648 tundi2000-03-012 kuud2 kuu pärast1440 tundi2000-02-01üks kuuühe kuu pärast744 tundi2000-01-1514 päeva14 päeva pärast336 tundi2000-01-02üks päevühe päeva pärast24 tundi2000-01-01T06:006 tundi6 tunni pärast6 tundi2000-01-01T00:4545 minutit45 minuti pärastüks tund2000-01-01T00:1515 minutit15 minuti pärast0 tundi2000-01-01T00:000 sekundit0 sekundi eest0 tundi1999-12-31T23:3030 minutit30 minuti eestüks tund1999-12-31T18:006 tundi6 tunni eest6 tundi1999-12-302 päeva2 päeva eest48 tundi1994-01-016 aastat6 aasta eest52584 tundi严格模式下单复数的切换依然精确üks aasta / ühe aasta pärast1 年、2 aastat / 2 aasta pärast≥2 年üks kuu / ühe kuu pärast、2 kuud / 2 kuu pärast。而「强制单位」如unit: hour会把所有距离折算成小时——注意快照中 2004 年闰年折算 35064 小时、1996 年同样 35064 小时而 1995 年为 43824、1994 年为 52584这些数字精确反映了闰年 366 天与平年 365 天的小时差366×248784、365×248760。六、formatRelativeeile / täna / homme 相对时间formatRelative依据目标日期与基准日期快照假设为 2000-01-01 00:00的差生成「昨天/今天/明天/上周/下周」等措辞输入日期结果2000-01-1010.01.20002000-01-05järgmine kolmapäev kell 00:002000-01-02homme kell 00:002000-01-01täna kell 00:001999-12-31eile kell 00:001999-12-27eelmine esmaspäev kell 00:001999-12-2121.12.1999模板在 formatRelative/index.tsconst formatRelativeLocale { lastWeek: eelmine eeee kell p, yesterday: eile kell p, today: täna kell p, tomorrow: homme kell p, nextWeek: järgmine eeee kell p, other: P, };注意eelmine上周与järgmine下周后的eeee是不加句点的全称星期且p复用短时间模板HH:mm——所以输出形如järgmine kolmapäev kell 00:00下周星期三 00:00。超出上述窗口的日期如 10 天后、21 天前退化为Pdd.MM.y普通日期格式。FormatRelativeToken的全部取值lastWeek/yesterday/today/tomorrow/nextWeek/other见 locale/types.ts。七、formatDuration时长的单复数与零值输出formatDuration把 Duration 对象{years, months, weeks, days, hours, minutes, seconds}逐字段转成爱沙尼亚语快照snapshot.md覆盖 0、1、2 三个数量级Duration结果{years:0}0 aastat{years:1}üks aasta{years:2}2 aastat{months:0}0 kuud{months:1}üks kuu{months:2}2 kuud{weeks:0}0 nädalat{weeks:1}üks nädal{weeks:2}2 nädalat{days:0}0 päeva{days:1}üks päev{days:2}2 päeva{hours:0}0 tundi{hours:1}üks tund{hours:2}2 tundi{minutes:0}0 minutit{minutes:1}üks minut{minutes:2}2 minutit{seconds:0}0 sekundit{seconds:1}üks sekund{seconds:2}2 sekundit这里完整展现了爱沙尼亚语「1 用主格单数üks …、其余用复数主格」的规则1 nädal但2 nädalat、1 päev但2 päeva、1 tund但2 tundi。零值同样输出复数形式0 aastat与formatDistance中0 sekundit的措辞一致。八、序数词与 parse 的正则支撑爱沙尼亚语序数词极其简单数字后直接加英文句点如1.、2.、42.。这在 localize/index.ts 中实现const ordinalNumber: LocalizeFnnumber (dirtyNumber, _options) { const number Number(dirtyNumber); return number .; };对应的解析规则在 match/index.tsmatchOrdinalNumberPattern /^\d\./i识别「数字句点」parseOrdinalNumberPattern /\d/i抽取数字valueCallback用parseInt还原数值。这就是yo、Qo、Mo、do、Do、wo、Io、ho、mo、so等所有序数令牌能格式化又能回解析的底层保证。九、总结快照读法与实践建议把 snapshot 当测试基准et/snapshot.md由pnpm run locale-snapshots生成见 i18n 贡献指南任何对 localize、match、formatLong、formatDistance、formatRelative 的修改都应重新生成快照并人工核对输出。区分「可格式化」与「可解析」缩写星期esmasp.、窄形月份M/J、带时区的ppp/pppp都存在无法回解析或解析歧义的问题快照的Invalid Date/Errored列就是官方记录的边界证据。做用户输入解析时优先使用全称、窄形或数字令牌。利用双套词形做本地化formatDistance的 standalone/withPreposition 双模板与pärast/eest后缀是爱沙尼亚语变格属格的正确处理范式localize的formattingValues机制如hommikul等带词尾时段词同样值得在其它「词形随语境变化」的语言中复用。周与年的默认约定etlocale 固定weekStartsOn: 1周一、firstWeekContainsDate: 4所有周相关令牌Yo、wo、eo等均基于这一约定输出与 ISO 周编号一致如 2019-01-01 属于第 1 周2019-12-01 属于第 48 周。【免费下载链接】date-fns⏳ Modern JavaScript date utility library ⌛️项目地址: https://gitcode.com/gh_mirrors/da/date-fns创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
date-fns 爱沙尼亚语（et）Locale 全解析：基于 snapshot 快照的 format/parse 令牌与本地化实现指南
date-fns 爱沙尼亚语etLocale 全解析基于 snapshot 快照的 format/parse 令牌与本地化实现指南【免费下载链接】date-fns⏳ Modern JavaScript date utility library ⌛️项目地址: https://gitcode.com/gh_mirrors/da/date-fnsdate-fns 的每个 locale 目录下都有一份snapshot.md它是该语言本地化行为的「验证快照」覆盖format/parse全部令牌、formatDistance、formatDistanceStrict、formatRelative与formatDuration的输出样例。本文以 爱沙尼亚语 locale 快照 为骨架结合 et locale 源码 及其_lib下的实现逐令牌讲解爱沙尼亚语日期格式化的输出规则、可解析性含Invalid Date与Errored的边界行为、序数词与变格declension处理读完你既能直接用etlocale 格式化爱沙尼亚语日期也能读懂 date-fns locale 快照的验证语义。一、snapshot.md 是什么locale 的自动验证快照snapshot.md不是手写文档而是 date-fns 用于测试 locale 的自动生成快照。正如 i18n 贡献指南 所述测试 locale 时使用快照生成命令为pnpm run locale-snapshots生成后快照会出现在对应 locale 目录下如src/locales/ru/snapshot.md。做完 locale 后生成快照并人工审查输出值即可确认每个令牌的行为是否符合该语言习惯。因此et/snapshot.md 实质上是一份「可运行的验证基准」表格中的每个format结果和parse结果都对应一条测试断言。阅读它的价值在于快速查阅每个日期令牌在爱沙尼亚语下的真实输出无需自己跑代码了解哪些字符串可以回解析parse、哪些不能表中明确标注Invalid Date与Errored作为实现参考对应到 localize、match、formatLong 等源码模块。二、et locale 结构总览五个模块与两个选项et/index.ts 导出一个标准Locale对象结构定义见 locale/types.tsexport const et: Locale { code: et, formatDistance, // 距离词含变格与 pärast/eest 后缀 formatLong, // 长日期/长时间模板P、PP、PPP、PPPP 等 formatRelative,// 相对时间eile/täna/homme 等 localize, // 世纪、季度、月份、星期、时段词的本地化 match, // 用于 parse 的正则匹配 options: { weekStartsOn: 1 /* Monday */, firstWeekContainsDate: 4, }, };两个关键选项决定了周的语义weekStartsOn: 1爱沙尼亚语环境周一为一周之始影响E/e/c/i系列星期令牌与startOfWeek等函数firstWeekContainsDate: 4一年中的第一周是包含 1 月 4 日的那一周与 ISO 8601 周编号约定一致影响Yo、wo等周编号令牌。使用时只需把et传给任何接受locale选项的函数import { format, parse, formatDistance, formatRelative } from date-fns; import { et } from date-fns/locale; format(new Date(1987, 1, 11), PPPP, { locale: et }); // kolmapäev, 11. veebruar 1987 formatDistance(new Date(2001, 0, 1), new Date(2000, 0, 1), { locale: et, addSuffix: true }); // umbes ühe aasta pärast三、format 与 parse令牌行为速查表以下表格逐行继承自 et/snapshot.md 的format/parse部分。format结果即该令牌在爱沙尼亚语下的输出parse结果表示用parse解析该输出得到的日期其中Invalid Date、Errored表示无法回解析。所有日期均为 UTC。3.1 年、季度Calendar year / Local week-numbering year / Quarter类别令牌输入日期format 结果parse 结果Calendar yearyo1987-02-11T12:13:14.015Z1987.1987-01-01T00:00:00.000Z0005-01-01T12:13:14.015Z5.0005-01-01T00:00:00.000ZLocal week-numbering yearYo1987-02-11T12:13:14.015Z1987.1986-12-29T00:00:00.000Z0005-01-01T12:13:14.015Z4.0003-12-29T00:00:00.000ZQuarter (formatting)Qo2019-01-01T12:13:14.015Z1.2019-01-01T00:00:00.000Z2019-04-01T12:13:14.015Z2.2019-04-01T00:00:00.000ZQQQ2019-01-01T12:13:14.015ZK12019-01-01T00:00:00.000Z2019-04-01T12:13:14.015ZK22019-04-01T00:00:00.000ZQQQQ2019-01-01T12:13:14.015Z1. kvartal2019-01-01T00:00:00.000Z2019-04-01T12:13:14.015Z2. kvartal2019-04-01T00:00:00.000ZQQQQQ2019-01-01T12:13:14.015Z12019-01-01T00:00:00.000Z2019-04-01T12:13:14.015Z22019-04-01T00:00:00.000ZQuarter (stand-alone)qo2019-01-01T12:13:14.015Z1.2019-01-01T00:00:00.000Z2019-04-01T12:13:14.015Z2.2019-04-01T00:00:00.000Zqqq2019-01-01T12:13:14.015ZK12019-01-01T00:00:00.000Z2019-04-01T12:13:14.015ZK22019-04-01T00:00:00.000Zqqqq2019-01-01T12:13:14.015Z1. kvartal2019-01-01T00:00:00.000Z2019-04-01T12:13:14.015Z2. kvartal2019-04-01T00:00:00.000Z对应源码在 localize/index.ts季度缩写固定为K1~K4宽格式为1. kvartal等buildLocalizeFn通过argumentCallback: (quarter) quarter - 1做下标转换。注意快照中yo/Qo/qo的 parse 结果都落在所在年/季度的第一天这是 ordinal 数字令牌的标准解析行为。3.2 月份Month formatting 与 stand-alone令牌2019 年各月输入格式化的日期format 结果序列parse 结果Mo序数2019-01-11 ~ 2019-12-101. / 2. / 3. / 4. / 5. / 6. / 7. / 8. / 9. / 10. / 11. / 12.各月 1 日 00:00:00.000ZMMM缩写同上jaan / veebr / märts / apr / mai / juuni / juuli / aug / sept / okt / nov / dets各月 1 日 00:00:00.000ZMMMM全称同上jaanuar / veebruar / märts / aprill / mai / juuni / juuli / august / september / oktoober / november / detsember各月 1 日 00:00:00.000ZMMMMM窄形同上J / V / M / A / M / J / J / A / S / O / N / D见下方说明Lo序数stand-alone同上1. ~ 12.各月 1 日 00:00:00.000ZLLL缩写同上jaan / veebr / märts / apr / mai / juuni / juuli / aug / sept / okt / nov / dets各月 1 日 00:00:00.000ZLLLL全称同上jaanuar ~ detsember各月 1 日 00:00:00.000ZLLLLL窄形同上J / V / M / A / M / J / J / A / S / O / N / D见下方说明完整逐行数据见 snapshot.md。爱沙尼亚语月份词源数据在 localize/index.ts缩写、全称、窄形三套并排定义且month与day都同时提供formattingValues保证在句子中与独立使用时措辞一致。窄形月份的解析歧义重要边界快照中MMMMM/LLLLL的 parse 结果并非总是「回到原月份」。例如5 月窄形Mmai→ parse 得2019-03-013 月märts6 月Jjuuni、7 月Jjuuli→ 都 parse 得2019-01-011 月jaanuar3 月M、1 月J、8 月A、9 月S等才正确回解析。原因在 match/index.ts 的parseMonthPatterns.narrow它按下标依次使用/^j/, /^v/, /^m/, /^a/, /^m/, /^j/, /^j/, /^a/, /^s/, /^o/, /^n/, /^d/即「取第一个匹配的下标」——M首先命中下标 2märtsJ首先命中下标 0jaanuar。这正是爱沙尼亚语窄形月份字母天然存在歧义J 对应 jaanuar/juuni/juuliM 对应 märts/mai快照如实记录了这一行为提示在实际业务中不要用窄形月份做双向往返解析。3.3 周编号与日week / day of month / day of year / day of week类别令牌输入日期format 结果parse 结果Local week of yearwo2019-01-01T12:13:14.015Z1.2018-12-31T00:00:00.000Z2019-12-01T12:13:14.015Z48.2019-11-25T00:00:00.000ZISO week of yearIo2019-01-01T12:13:14.015Z1.2018-12-31T00:00:00.000Z2019-12-01T12:13:14.015Z48.2019-11-25T00:00:00.000ZDay of monthdo2019-02-01T12:13:14.015Z1.2019-02-01T00:00:00.000Z2019-02-11T12:13:14.015Z11.2019-02-11T00:00:00.000Z2019-02-28T12:13:14.015Z28.2019-02-28T00:00:00.000Zdo MMMM2019-02-01T12:13:14.015Z1. veebruar2019-02-01T00:00:00.000Z2019-02-11T12:13:14.015Z11. veebruar2019-02-11T00:00:00.000Z2019-02-28T12:13:14.015Z28. veebruar2019-02-28T00:00:00.000ZDay of yearDo2019-02-11T12:13:14.015Z42.2019-02-11T00:00:00.000Z2019-12-31T12:13:14.015Z365.2019-12-31T00:00:00.000Z星期系列以周一2019-02-11与周五2019-02-15为例类别令牌format 结果周一 / 周五parse 结果周一 / 周五Day of week (formatting)E / EE / EEEesmasp. / reede.Invalid Date / Invalid DateEEEEesmaspäev / reede2019-02-11 / 2019-02-15EEEEE / EEEEEEE / R2019-02-11 / 2019-02-15ISO day of weekio1. / 5.2019-02-11 / 2019-02-15iiiesmasp. / reede.Invalid Date / Invalid Dateiiiiesmaspäev / reede2019-02-11 / 2019-02-15iiiii / iiiiiiE / R2019-02-11 / 2019-02-15Local day of week (formatting)eo1. / 5.2019-02-11 / 2019-02-15eeeesmasp. / reede.Invalid Date / Invalid Dateeeeeesmaspäev / reede2019-02-11 / 2019-02-15eeeee / eeeeeeE / R2019-02-11 / 2019-02-15Local day of week (stand-alone)co1. / 5.2019-02-11 / 2019-02-15cccesmasp. / reede.Invalid Date / Invalid Dateccccesmaspäev / reede2019-02-11 / 2019-02-15ccccc / ccccccE / R2019-02-11 / 2019-02-15星期词源数据在 localize/index.tsnarrow/short都是单字母P E T K N R Labbreviated为带句点的pühap. esmasp. teisip. kolmap. neljap. reede. laup.wide为完整词。匹配规则在 match/index.ts缩写形如/^(püh?|esm?|tei?|kolm?|nel?|ree?|laup?)\.?/i。值得注意的可解析性差异缩写形esmasp./reede.只能格式化无法通过parse回解析快照中记为Invalid Date而全称形esmaspäev/reede与窄形E/R都可以正常往返。快照的parse列正是用来暴露这类不对称行为的——在设计用户输入解析方案时应优先接受全称或窄形避免依赖缩写形。3.4 一天中的时段与时刻AM/PM、灵活时段、小时/分/秒类别令牌输入日期format 结果parse 结果AM, PMa / aa / aaaa / aaaaa11:13 / 14:13 / 19:13 / 02:13AM / PM / PM / AM00:00 / 12:00 / 12:00 / 00:00aaa / bbb同上am / pm / pm / am00:00 / 12:00 / 12:00 / 00:00AM, PM, noon, midnightb / bb / bbbb / bbbbb同上AM / PM / PM / AM00:00 / 12:00 / 12:00 / 00:00Flexible day periodB / BB / BBB / BBBB / BBBBB11:13 / 14:13 / 19:13 / 02:13hommikul / pärastlõunal / õhtul / öösel04:00 / 12:00 / 17:00 / 00:00Hour [1-12]ho11:13 / 23:1311. / 11.11:00 / 23:00Hour [0-23]Ho11:13 / 23:1311. / 23.11:00 / 23:00Hour [0-11]Ko11:13 / 23:1311. / 11.11:00 / 23:00Hour [1-24]ko11:13 / 23:1311. / 23.11:00 / 23:00Minutemo12:01 / 12:551. / 55.12:01:00 / 12:55:00Secondso12:13:01 / 12:13:551. / 55.12:13:01 / 12:13:55时段词在 localize/index.ts 中分为两套dayPeriodValues独立语境hommik/pärastlõuna/õhtu/öö与formattingDayPeriodValues句子中带词尾hommikul/pärastlõunal/õhtul/öösel——即快照中B系列的实际输出属于爱沙尼亚语「内格/状语」形式的典型本地化处理。B系列 parse 出的时间点04:00 / 12:00 / 17:00 / 00:00来自 match/index.ts 的parseDayPeriodPatterns分别映射 morning/afternoon/evening/night 的默认时刻。3.5 本地化长日期与长时间P/p 系列P系列模板定义在 formatLong/index.tsconst 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}} kell {{time}}, long: {{date}} kell {{time}}, medium: {{date}}. {{time}}, short: {{date}}. {{time}}, };dateTimeFormats中的kell是爱沙尼亚语「时钟/在……点」的介词词组合令牌Pp、PPpp、PPPppp、PPPPpppp由它拼接日期与时间。完整样例表format列与parse列均取自 snapshot.md令牌示例输入format 结果parse 结果P1987-01-11 ~ 1987-12-11每月 11 日11.01.1987 / 11.02.1987 / 11.03.1987 / 11.04.1987 / 29.05.1453 / 11.06.1987 / 11.07.1987 / 11.08.1987 / 11.09.1987 / 11.10.1987 / 11.11.1987 / 11.12.1987对应日期 00:00:00.000ZPP同上11. jaan 1987 / 11. veebr 1987 / 11. märts 1987 / 11. apr 1987 / 29. mai 1453 / 11. juuni 1987 / 11. juuli 1987 / 11. aug 1987 / 11. sept 1987 / 11. okt 1987 / 11. nov 1987 / 11. dets 1987对应日期 00:00:00.000ZPPP同上11. jaanuar 1987 / 11. veebruar 1987 / 11. märts 1987 / 11. aprill 1987 / 29. mai 1453 / 11. juuni 1987 / 11. juuli 1987 / 11. august 1987 / 11. september 1987 / 11. oktoober 1987 / 11. november 1987 / 11. detsember 1987对应日期 00:00:00.000ZPPPP同上pühapäev, 11. jaanuar 1987 / kolmapäev, 11. veebruar 1987 / kolmapäev, 11. märts 1987 / laupäev, 11. aprill 1987 / pühapäev, 29. mai 1453 / neljapäev, 11. juuni 1987 / laupäev, 11. juuli 1987 / teisipäev, 11. august 1987 / reede, 11. september 1987 / pühapäev, 11. oktoober 1987 / kolmapäev, 11. november 1987 / reede, 11. detsember 1987对应日期 00:00:00.000Zp各月 11 日 12:13:14 / 1453-05-29 23:59:5912:13 / 12:13 / … / 23:59对应日期 12:13:00 / 23:59:00pp同上12:13:14 / … / 23:59:59对应日期 完整时分秒ppp同上12:13:14 GMT0 / … / 23:59:59 GMT0Erroredpppp同上12:13:14 GMT00:00 / … / 23:59:59 GMT00:00ErroredPp同上11.01.1987. 12:13 / … / 29.05.1453. 23:59对应日期 时分PPpp同上11. jaan 1987. 12:13:14 / … / 29. mai 1453. 23:59:59对应日期 完整时分秒PPPppp同上11. jaanuar 1987 kell 12:13:14 GMT0 / … / 29. mai 1453 kell 23:59:59 GMT0ErroredPPPPpppp同上pühapäev, 11. jaanuar 1987 kell 12:13:14 GMT00:00 / … / reede, 11. detsember 1987 kell 12:13:14 GMT00:00Errored时区令牌不可回解析ppp/pppp及其组合的parse结果均为Errored。这是因为HH:mm:ss z/zzzz这类带时区GMT0/GMT00:00的输出在爱沙尼亚语 locale 的match模块中没有对应的时区解析规则快照用Errored明确标记「格式化可用、解析失败」的组合。如果业务需要同时保证双向解析应避免使用ppp/pppp改用pp及以下宽度。四、formatDistance变格、单复数与 pärast/eest 后缀快照的formatDistance部分假设「当前时间是 2000 年 1 月 1 日 00:00」覆盖过去与未来两个方向。完整逐行数据见 snapshot.md代表性片段如下输入日期结果includeSeconds: trueaddSuffix: true2006-01-01umbes 6 aastatumbes 6 aastatumbes 6 aasta pärast2001-06-01rohkem kui üks aasta同左rohkem kui ühe aasta pärast2001-01-01umbes üks aasta同左umbes ühe aasta pärast2000-06-015 kuud5 kuud5 kuu pärast2000-01-1514 päeva14 päeva14 päeva pärast2000-01-01T06:00umbes 6 tundi同左umbes 6 tunni pärast2000-01-01T00:45umbes üks tund同左umbes ühe tunni pärast2000-01-01T00:01üks minut同左ühe minuti pärast2000-01-01T00:00:25vähem kui üks minutpool minutitvähem kui ühe minuti pärast2000-01-01T00:00:00vähem kui üks minutvähem kui 5 sekunditvähem kui ühe minuti eest1999-12-31T23:59:00üks minut同左ühe minuti eest1999-12-302 päeva2 päeva2 päeva eest1999-11-012 kuud2 kuud2 kuu eest1999-01-01umbes üks aasta同左umbes ühe aasta eest1994-01-01umbes 6 aastat同左umbes 6 aasta eest其实现是 formatDistance/index.ts核心机制有两点独立形与介词形standalone / withPreposition双套模板每个 token 都定义standalone与withPreposition两组词形options.addSuffix为真时走withPreposition。这正是爱沙尼亚语属格变格的体现——例如5 kuud主格独立使用在带后缀时变为5 kuu pärastüks aasta变为ühe aasta pärastüks minut变为ühe minuti pärast。词形在 formatDistance/index.ts 中逐 token 声明共覆盖lessThanXSeconds、xSeconds、halfAMinute、lessThanXMinutes、xMinutes、aboutXHours、xHours、xDays、aboutXWeeks、xWeeks、aboutXMonths、xMonths、aboutXYears、xYears、overXYears、almostXYears全部 16 种距离 token。后缀方向由comparison决定options.addSuffix时未来comparison 0追加pärast“之后”过去追加eest“之前”——见 formatDistance/index.ts。comparison的取值范围在 locale/types.ts 中定义为-1 | 0 | 1。这一设计让同一个模板函数同时服务formatDistance与formatDistanceToNow等 API。五、formatDistanceStrict严格距离的确定性输出formatDistanceStrict不引入「约/多于一」的模糊措辞直接给出精确单位且addSuffix同样触发属格变格与pärast/eest后缀。快照snapshot.md关键行为如下输入日期结果addSuffix: true强制单位 hour2006-01-016 aastat6 aasta pärast52608 tundi2005-01-015 aastat5 aasta pärast43848 tundi2004-01-014 aastat4 aasta pärast35064 tundi2003-01-013 aastat3 aasta pärast26304 tundi2002-01-012 aastat2 aasta pärast17544 tundi2001-06-01üks aastaühe aasta pärast12408 tundi2001-01-01üks aastaühe aasta pärast8784 tundi2000-06-015 kuud5 kuu pärast3648 tundi2000-03-012 kuud2 kuu pärast1440 tundi2000-02-01üks kuuühe kuu pärast744 tundi2000-01-1514 päeva14 päeva pärast336 tundi2000-01-02üks päevühe päeva pärast24 tundi2000-01-01T06:006 tundi6 tunni pärast6 tundi2000-01-01T00:4545 minutit45 minuti pärastüks tund2000-01-01T00:1515 minutit15 minuti pärast0 tundi2000-01-01T00:000 sekundit0 sekundi eest0 tundi1999-12-31T23:3030 minutit30 minuti eestüks tund1999-12-31T18:006 tundi6 tunni eest6 tundi1999-12-302 päeva2 päeva eest48 tundi1994-01-016 aastat6 aasta eest52584 tundi严格模式下单复数的切换依然精确üks aasta / ühe aasta pärast1 年、2 aastat / 2 aasta pärast≥2 年üks kuu / ühe kuu pärast、2 kuud / 2 kuu pärast。而「强制单位」如unit: hour会把所有距离折算成小时——注意快照中 2004 年闰年折算 35064 小时、1996 年同样 35064 小时而 1995 年为 43824、1994 年为 52584这些数字精确反映了闰年 366 天与平年 365 天的小时差366×248784、365×248760。六、formatRelativeeile / täna / homme 相对时间formatRelative依据目标日期与基准日期快照假设为 2000-01-01 00:00的差生成「昨天/今天/明天/上周/下周」等措辞输入日期结果2000-01-1010.01.20002000-01-05järgmine kolmapäev kell 00:002000-01-02homme kell 00:002000-01-01täna kell 00:001999-12-31eile kell 00:001999-12-27eelmine esmaspäev kell 00:001999-12-2121.12.1999模板在 formatRelative/index.tsconst formatRelativeLocale { lastWeek: eelmine eeee kell p, yesterday: eile kell p, today: täna kell p, tomorrow: homme kell p, nextWeek: järgmine eeee kell p, other: P, };注意eelmine上周与järgmine下周后的eeee是不加句点的全称星期且p复用短时间模板HH:mm——所以输出形如järgmine kolmapäev kell 00:00下周星期三 00:00。超出上述窗口的日期如 10 天后、21 天前退化为Pdd.MM.y普通日期格式。FormatRelativeToken的全部取值lastWeek/yesterday/today/tomorrow/nextWeek/other见 locale/types.ts。七、formatDuration时长的单复数与零值输出formatDuration把 Duration 对象{years, months, weeks, days, hours, minutes, seconds}逐字段转成爱沙尼亚语快照snapshot.md覆盖 0、1、2 三个数量级Duration结果{years:0}0 aastat{years:1}üks aasta{years:2}2 aastat{months:0}0 kuud{months:1}üks kuu{months:2}2 kuud{weeks:0}0 nädalat{weeks:1}üks nädal{weeks:2}2 nädalat{days:0}0 päeva{days:1}üks päev{days:2}2 päeva{hours:0}0 tundi{hours:1}üks tund{hours:2}2 tundi{minutes:0}0 minutit{minutes:1}üks minut{minutes:2}2 minutit{seconds:0}0 sekundit{seconds:1}üks sekund{seconds:2}2 sekundit这里完整展现了爱沙尼亚语「1 用主格单数üks …、其余用复数主格」的规则1 nädal但2 nädalat、1 päev但2 päeva、1 tund但2 tundi。零值同样输出复数形式0 aastat与formatDistance中0 sekundit的措辞一致。八、序数词与 parse 的正则支撑爱沙尼亚语序数词极其简单数字后直接加英文句点如1.、2.、42.。这在 localize/index.ts 中实现const ordinalNumber: LocalizeFnnumber (dirtyNumber, _options) { const number Number(dirtyNumber); return number .; };对应的解析规则在 match/index.tsmatchOrdinalNumberPattern /^\d\./i识别「数字句点」parseOrdinalNumberPattern /\d/i抽取数字valueCallback用parseInt还原数值。这就是yo、Qo、Mo、do、Do、wo、Io、ho、mo、so等所有序数令牌能格式化又能回解析的底层保证。九、总结快照读法与实践建议把 snapshot 当测试基准et/snapshot.md由pnpm run locale-snapshots生成见 i18n 贡献指南任何对 localize、match、formatLong、formatDistance、formatRelative 的修改都应重新生成快照并人工核对输出。区分「可格式化」与「可解析」缩写星期esmasp.、窄形月份M/J、带时区的ppp/pppp都存在无法回解析或解析歧义的问题快照的Invalid Date/Errored列就是官方记录的边界证据。做用户输入解析时优先使用全称、窄形或数字令牌。利用双套词形做本地化formatDistance的 standalone/withPreposition 双模板与pärast/eest后缀是爱沙尼亚语变格属格的正确处理范式localize的formattingValues机制如hommikul等带词尾时段词同样值得在其它「词形随语境变化」的语言中复用。周与年的默认约定etlocale 固定weekStartsOn: 1周一、firstWeekContainsDate: 4所有周相关令牌Yo、wo、eo等均基于这一约定输出与 ISO 周编号一致如 2019-01-01 属于第 1 周2019-12-01 属于第 48 周。【免费下载链接】date-fns⏳ Modern JavaScript date utility library ⌛️项目地址: https://gitcode.com/gh_mirrors/da/date-fns创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考