date-fns 西弗里斯兰语(fy)Locale 全解析:format/parse 令牌快照与本地化实现原理

原创2026-09-18 23:10:281,652 阅读
文章标签:国际化跨平台前端

date-fns 西弗里斯兰语(fy)Locale 全解析:format/parse 令牌快照与本地化实现原理

本篇文章以 date-fns 仓库中 fy(West Frisian,西弗里斯兰语)locale 快照文档 为核心,系统梳理该语言环境下 format、parse、formatDistance、formatDistanceStrict、formatRelative、formatDuration 六个 API 的完整行为快照,并结合 locale 源码 剖析其本地化实现机制。读完本文,你将掌握 fy locale 的每个令牌(token)在格式化与解析时的输出规律、序数词与复数规则、相对时间措辞模式,以及 date-fns 中 locale 模块的分层构建方式,可直接用于 Frisian 语界面的日期本地化开发与自定义 locale 编写。

fy locale 在 date-fns 中的定位与结构

fy 是 date-fns 内置的约 80 余种 locale 之一,语言代码为 fy,ISO 639-2 编码为 fry。其入口定义位于 pkgs/core/src/locale/fy/index.ts,导出结构如下:

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

一个标准 date-fns Locale 对象由五个子模块与一组周选项构成:

  • localize:负责将"数值/枚举"翻译为本地化文本(如把月份 4 输出为 april);
  • match:负责在 parse 时把本地化文本匹配回数值(如把 april 解析回月份 4);
  • formatDistance / formatLong / formatRelative:分别提供距离短语、长格式模板、相对日期模板;
  • options:声明该地区的周规则——fy 的 weekStartsOn: 1 表示一周从星期一开始,firstWeekContainsDate: 4 表示一年中的第一周必须包含 1 月 4 日(即"含当年至少 4 天的那一周"),这两项直接决定 Yo(本地周年)、wo(本地周序)等令牌的计算基准。

从源码结构看,每个子模块又依赖 pkgs/core/src/locale/_lib/ 下的通用构建器 buildLocalizeFn、buildMatchFn、buildMatchPatternFn、buildFormatLongFn,这一"通用构建器 + 语言数据表"的分层设计是 date-fns 全部 locale 共用的架构模式。

format 与 parse 令牌快照解读

快照文档的第一部分以 1987-02-11T12:13:14.015Z 等基准日期逐令牌验证了 format 的输出与 parse 的回溯结果。以下按令牌族解读其规律,表格完整继承自快照(parse 结果均以 UTC 展示)。

年份与季度

Title Token string Date format result parse result
Calendar year yo 1987-02-11T12:13:14.015Z 1987e 1987-01-01T00:00:00.000Z
Calendar year yo 0005-01-01T12:13:14.015Z 5e 0005-01-01T00:00:00.000Z
Local week-numbering year Yo 1987-02-11T12:13:14.015Z 1987e 1986-12-29T00:00:00.000Z
Local week-numbering year Yo 0005-01-01T12:13:14.015Z 4e 0003-12-29T00:00:00.000Z
Quarter (formatting) Qo 2019-01-01T12:13:14.015Z 1e 2019-01-01T00:00:00.000Z
Quarter (formatting) QQQ 2019-01-01T12:13:14.015Z K1 2019-01-01T00:00:00.000Z
Quarter (formatting) QQQQ 2019-01-01T12:13:14.015Z 1e fearnsjier 2019-01-01T00:00:00.000Z
Quarter (formatting) QQQQQ 2019-01-01T12:13:14.015Z 1 2019-01-01T00:00:00.000Z
Quarter (stand-alone) qo 2019-01-01T12:13:14.015Z 1e 2019-01-01T00:00:00.000Z
Quarter (stand-alone) qqq 2019-01-01T12:13:14.015Z K1 2019-01-01T00:00:00.000Z
Quarter (stand-alone) qqqq 2019-01-01T12:13:14.015Z 1e fearnsjier 2019-01-01T00:00:00.000Z

解读要点:

  • 序数词规则:yo/Yo/Qo/qo 等带 o 的令牌统一输出 数字 + "e"(1987e、1e、10e)。这一规则由 localize 源码 中的 ordinalNumber 实现:return number + "e";——fy 语序数词不做复杂的形态变化,直接附加 e 后缀,与英语 st/nd/rd/th 的按尾数分发机制明显不同。
  • 季度缩写:QQQ/qqq 输出 K1–K4,取自 quarterValues.abbreviated;宽格式输出 1e fearnsjier("第一季度"),窄格式仅数字。
  • parse 的日期回退:注意 Yo 对 0005-01-01 解析出 0003-12-29——由于本地周年与公历年存在偏移,解析结果会落回该周年对应的周起始日(周一),这是周编号令牌的预期行为。

月份(formatting 与 stand-alone 两套宽度)

Title Token string Date format result parse result
Month (formatting) Mo 2019-01-11T12:13:14.015Z 1e 2019-01-01T00:00:00.000Z
Month (formatting) MMM 2019-01-11T12:13:14.015Z jan. 2019-01-01T00:00:00.000Z
Month (formatting) MMM 2019-05-10T12:13:14.015Z mai. 2019-03-01T00:00:00.000Z
Month (formatting) MMMM 2019-01-11T12:13:14.015Z jannewaris 2019-01-01T00:00:00.000Z
Month (formatting) MMMM 2019-05-10T12:13:14.015Z maaie 2019-03-01T00:00:00.000Z
Month (formatting) MMMMM 2019-01-11T12:13:14.015Z j 2019-01-01T00:00:00.000Z
Month (stand-alone) Lo 2019-01-11T12:13:14.015Z 1e 2019-01-01T00:00:00.000Z
Month (stand-alone) LLL 2019-01-11T12:13:14.015Z jan. 2019-01-01T00:00:00.000Z
Month (stand-alone) LLLL 2019-01-11T12:13:14.015Z jannewaris 2019-01-01T00:00:00.000Z
Month (stand-alone) LLLLL 2019-01-11T12:13:14.015Z j 2019-01-01T00:00:00.000Z

解读要点:

  • 五级宽度:MMMM(宽)输出全名 jannewaris、febrewaris、maart、april、maaie、juny、july、augustus、septimber、oktober、novimber、desimber;MMM(缩写)输出 jan.、feb.、mrt.、apr.、mai.、jun.、jul.、aug.、sep.、okt.、nov.、des.;MMMMM(窄)取首字母。
  • formatting 与 stand-alone 完全同形:对比 M 系列与 L 系列可发现输出完全一致。这是因为 localize/index.ts 中 month 只定义了 values 而未提供 formattingValues,buildLocalizeFn 因此回退到同一份数据表(见下文原理剖析)。
  • 快照揭示的"已知不完美":2019-05-10(五月)经 MMM/MMMM 格式化为 mai./maaie 后,parse 却回溯到 2019-03-01。根因在 match 源码:parseMonthPatterns.any 中 3 月(maart)与 5 月(maaie)共用 /^m(r|a)/i 前缀,buildMatchFn 按 findIndex 顺序匹配,导致 mai. 命中 3 月的正则。这是该 locale 当前实现中的已知解析歧义,值得在使用 parse 时留意。

周与日

Title Token string Date format result parse result
Local week of year wo 2019-01-01T12:13:14.015Z 1e 2018-12-31T00:00:00.000Z
ISO week of year Io 2019-01-01T12:13:14.015Z 1e 2018-12-31T00:00:00.000Z
Day of month do 2019-02-11T12:13:14.015Z 11e 2019-02-11T00:00:00.000Z
Day of month do MMMM 2019-02-11T12:13:14.015Z 11e febrewaris 2019-02-11T00:00:00.000Z
Day of year Do 2019-02-11T12:13:14.015Z 42e 2019-02-11T00:00:00.000Z
Day of week (formatting) E / EE / EEE 2019-02-11T12:13:14.015Z moa 2019-02-11T00:00:00.000Z
Day of week (formatting) EEEE 2019-02-11T12:13:14.015Z moandei 2019-02-11T00:00:00.000Z
Day of week (formatting) EEEEE 2019-02-11T12:13:14.015Z m 2019-02-11T00:00:00.000Z
Day of week (formatting) EEEEEE 2019-02-11T12:13:14.015Z mo 2019-02-11T00:00:00.000Z
ISO day of week io 2019-02-11T12:13:14.015Z 1e 2019-02-11T00:00:00.000Z
Local day of week eo 2019-02-11T12:13:14.015Z 1e 2019-02-11T00:00:00.000Z

解读要点:

  • 星期全名:snein(周日)、moandei(周一)、tiisdei(周二)、woansdei(周三)、tongersdei(周四)、freed(周五)、sneon(周六);缩写取前三个字母 moa、tii、woa、ton、fre,短形 mo、ti、wo、to、fr,窄形取首字母。
  • 数字型日令牌:io(ISO 周内日,周一为 1)与 eo(本地周内日,因 weekStartsOn: 1 故同样周一为 1)输出序数形式 1e/5e。

AM/PM 与时段

Title Token string Date format result parse result
AM, PM a 2019-02-11T11:13:14.015Z AM 2019-02-11T00:00:00.000Z
AM, PM a 2019-02-11T14:13:14.015Z PM 2019-02-11T12:00:00.000Z
AM, PM aaa 2019-02-11T11:13:14.015Z am 2019-02-11T00:00:00.000Z
Flexible day period B 2019-02-11T11:13:14.015Z moarns 2019-02-11T04:00:00.000Z
Flexible day period B 2019-02-11T14:13:14.015Z middeis 2019-02-11T12:00:00.000Z
Flexible day period B 2019-02-11T19:13:14.015Z jûns 2019-02-11T17:00:00.000Z
Flexible day period B 2019-02-11T02:13:14.015Z nachts 2019-02-11T00:00:00.000Z

解读要点:

  • AM/PM:大写 AM/PM(a、aa、aaaa、aaaaa),小写 am/pm(aaa)。fy 语沿用英语的 AM/PM 标记,未做本土化翻译,与 dayPeriodValues 中 am/pm 字段保持一致。
  • 弹性时段(B 系列):按一天中的时间段输出 moarns(早晨)、middeis(下午)、jûns(傍晚)、nachts(夜间)。注意 parse 的回溯点:moarns → 04:00、middeis → 12:00、jûns → 17:00、nachts → 00:00,即 parse 把时段解析为各时段的代表时刻。

小时、分钟与秒

Title Token string Date format result parse result
Hour [1-12] ho 2019-02-11T23:13:14.015Z 11e 2019-02-11T23:00:00.000Z
Hour [0-23] Ho 2019-02-11T23:13:14.015Z 23e 2019-02-11T23:00:00.000Z
Hour [0-11] Ko 2019-02-11T23:13:14.015Z 11e 2019-02-11T23:00:00.000Z
Hour [1-24] ko 2019-02-11T23:13:14.015Z 23e 2019-02-11T23:00:00.000Z
Minute mo 2019-04-01T12:55:14.015Z 55e 2019-04-01T12:55:00.000Z
Second so 2019-04-01T12:13:55.015Z 55e 2019-04-01T12:13:55.000Z

所有序数化的小时/分钟/秒令牌均统一输出 数字 + "e",验证了 ordinalNumber 的全局适用性。

长本地化日期与时间(P/p 系列)

Title Token string Date format result parse result
Long localized date P 1987-02-11T12:13:14.015Z 11-02-1987 1987-02-11T00:00:00.000Z
Long localized date PP 1987-02-11T12:13:14.015Z 11 feb. 1987 1987-02-11T00:00:00.000Z
Long localized date PPP 1987-02-11T12:13:14.015Z 11 febrewaris 1987 1987-02-11T00:00:00.000Z
Long localized date PPPP 1987-02-11T12:13:14.015Z woansdei 11 febrewaris 1987 1987-02-11T00:00:00.000Z
Long localized time p 1987-01-11T12:13:14.015Z 12:13 1987-01-11T12:13:00.000Z
Long localized time pp 1987-01-11T12:13:14.015Z 12:13:14 1987-01-11T12:13:14.000Z
Long localized time ppp 1987-01-11T12:13:14.015Z 12:13:14 GMT+0 Errored
Combination of date and time Pp 1987-01-11T12:13:14.015Z 11-01-1987, 12:13 1987-01-11T12:13:00.000Z
Combination of date and time PPpp 1987-02-11T12:13:14.015Z 11 feb. 1987, 12:13:14 1987-02-11T12:13:14.000Z
Combination of date and time PPPppp 1987-02-11T12:13:14.015Z 11 febrewaris 1987 om 12:13:14 GMT+0 Errored
Combination of date and time PPPPpppp 1987-02-11T12:13:14.015Z woansdei 11 febrewaris 1987 om 12:13:14 GMT+00:00 Errored

解读要点:

  • P 系列日模板来自 formatLong/index.ts 的 dateFormats:short: "dd-MM-y"、medium: "d MMM y"、long: "d MMMM y"、full: "EEEE d MMMM y",分别对应 P/PP/PPP/PPPP。
  • p 系列时间模板来自 timeFormats:short: "HH:mm"、medium: "HH:mm:ss"、long/full 追加时区。
  • 组合模板:dateTimeFormats 中 short/medium 用 {{date}}, {{time}} 逗号拼接,long/full 用 {{date}} 'om' {{time}}(om 即"在……时")。快照中 PPPPpppp 的完整输出 woansdei 11 febrewaris 1987 om 12:13:14 GMT+00:00 直观展示了这一模板拼接效果。
  • ppp/pppp 解析失败(Errored):带时区偏移(GMT+0/GMT+00:00)的文本无法被 parse 还原。从快照看,这是该 locale 当前已知的限制,使用带时区的 ppp/pppp 令牌做格式化后不应再期望 parse 能逆向解析。

formatDistance 相对距离短语

快照以「now 为 2000-01-01 00:00」为基准,验证 formatDistance 对过去/未来日期的措辞。核心结论:

Date Result includeSeconds: true addSuffix: true
2006-01-01T00:00:00.000Z sawat 6 jier sawat 6 jier oer sawat 6 jier
2001-06-01T00:00:00.000Z mear as 1 jier mear as 1 jier oer mear as 1 jier
2000-06-01T00:00:00.000Z 5 moannen 5 moannen oer 5 moannen
2000-01-15T00:00:00.000Z 14 dagen 14 dagen oer 14 dagen
2000-01-01T06:00:00.000Z sawat 6 oere sawat 6 oere oer sawat 6 oere
2000-01-01T00:01:00.000Z 1 minút 1 minút oer 1 minút
2000-01-01T00:00:25.000Z minder as 1 minút oardel minút oer minder as 1 minút
2000-01-01T00:00:15.000Z minder as 1 minút minder as 20 sekonden oer minder as 1 minút
2000-01-01T00:00:00.000Z minder as 1 minút minder as 5 sekonden minder as 1 minút lyn
1999-12-31T23:59:00.000Z 1 minút 1 minút 1 minút lyn
1999-12-31T23:15:00.000Z sawat 1 oere sawat 1 oere sawat 1 oere lyn
1999-12-30T00:00:00.000Z 2 dagen 2 dagen 2 dagen lyn
1999-11-01T00:00:00.000Z 2 moannen 2 moannen 2 moannen lyn
1998-06-01T00:00:00.000Z mear as 1 jier mear as 1 jier mear as 1 jier lyn
1994-01-01T00:00:00.000Z sawat 6 jier sawat 6 jier sawat 6 jier lyn

解读要点(对照 formatDistance 实现):

  • 模糊量词:sawat(大约)、mear as(超过)、minder as(少于)、oardel minút(一分半);includeSeconds 开启后,25 秒以内会细化为 minder as X sekonden,其中 30 秒附近输出 oardel minút。
  • 单复数形态:短语表按 { one, other } 组织,count === 1 时取 one,否则用 {{count}} 占位替换。注意 fy 的复数并不总是规则加后缀——1 dei/2 dagen(日)、1 moanne/2 moannen(月)、1 minút/2 minuten(分钟)、1 sekonde/2 sekonden(秒),而 jier(年)与 oere(小时)单复数同形。
  • addSuffix 方向规则:未来时间前缀 oer (在……之后),过去时间后缀 lyn(之前),逻辑见实现中的 options.comparison > 0 分支。快照中 0 秒(现在时刻)走过去分支输出 minder as 1 minút lyn。

formatDistanceStrict 严格距离

与 formatDistance 不同,formatDistanceStrict 不做"大约/超过"的模糊化,直接按最近单位输出,且支持 unit 强制单位。快照要点:

Date Result addSuffix: true With forced unit (i.e. hour)
2006-01-01T00:00:00.000Z 6 jier oer 6 jier 52608 oere
2004-01-01T00:00:00.000Z 4 jier oer 4 jier 35064 oere
2000-06-01T00:00:00.000Z 5 moannen oer 5 moannen 3648 oere
2000-01-15T00:00:00.000Z 14 dagen oer 14 dagen 336 oere
2000-01-01T06:00:00.000Z 6 oere oer 6 oere 6 oere
2000-01-01T00:45:00.000Z 45 minuten oer 45 minuten 1 oere
2000-01-01T00:00:00.000Z 0 sekonden 0 sekonden lyn 0 oere
1999-12-31T23:59:00.000Z 1 minút 1 minút lyn 0 oere
1999-12-31T23:00:00.000Z 1 oere 1 oere lyn 1 oere
1994-01-01T00:00:00.000Z 6 jier 6 jier lyn 52584 oere

解读要点:

  • 严格模式直接使用 xSeconds/xMinutes/xHours/xDays/xMonths/xYears 等精确短语,不再有 sawat/mear as 修饰(sawat 仅在自动选择单位时对非整边界做近似处理,例如 45 分钟 在默认模式下已足够精确仍输出 45 minuten)。
  • 强制单位为 hour 时全部折算为小时:2 jier ≈ 17544 oere、1 moanne ≈ 744 oere(31 天月)、1 jier ≈ 8760 oere(平年)与 8784 oere(闰年 2001 距 2000 含 366 天)。这些数值可直接用于验证单位的换算精度。

formatRelative 相对日期模板

快照(now = 2000-01-01 00:00)展示了 5 个相对槽位的措辞:

Date Result
2000-01-10T00:00:00.000Z 10-01-2000
2000-01-05T00:00:00.000Z woansdei om 00:00
2000-01-02T00:00:00.000Z moarn om 00:00
2000-01-01T00:00:00.000Z hjoed om 00:00
1999-12-31T00:00:00.000Z juster om 00:00
1999-12-27T00:00:00.000Z ôfrûne moandei om 00:00
1999-12-21T00:00:00.000Z 21-12-1999

对应的模板在 formatRelative/index.ts 中一目了然:

const formatRelativeLocale = {
  lastWeek: "'ôfrûne' eeee 'om' p",
  yesterday: "'juster om' p",
  today: "'hjoed om' p",
  tomorrow: "'moarn om' p",
  nextWeek: "eeee 'om' p",
  other: "P",
};
  • hjoed(今天)、juster(昨天)、moarn(明天);
  • 上周用 ôfrûne("过去的")+ 星期名,如下周三、下周五等"即将到来"场景则直接 eeee 'om' p;
  • 超出上述槽位的日期回退到 P(即 dd-MM-y,如 10-01-2000、21-12-1999)。

formatDuration 时长格式化

快照验证了 formatDuration 对 { years, months, weeks, days, hours, minutes, seconds } 各单位的单复数与零值输出:

Duration Result
{"years":0} 0 jier
{"years":1} 1 jier
{"years":2} 2 jier
{"months":0} 0 moannen
{"months":1} 1 moanne
{"months":2} 2 moannen
{"weeks":0} 0 wiken
{"weeks":1} 1 wike
{"weeks":2} 2 wiken
{"days":0} 0 dagen
{"days":1} 1 dei
{"days":2} 2 dagen
{"hours":0} 0 oere
{"hours":1} 1 oere
{"hours":2} 2 oere
{"minutes":0} 0 minuten
{"minutes":1} 1 minút
{"minutes":2} 2 minuten
{"seconds":0} 0 sekonden
{"seconds":1} 1 sekonde
{"seconds":2} 2 sekonden

形态规律与 formatDistance 完全一致:0 与 ≥2 均走 other 复数形式(0 jier、0 dagen、0 oere),1 走单数形式(1 dei、1 wike、1 minút)。

源码级原理:buildLocalizeFn 与 buildMatchFn 如何驱动快照

快照中每个输出都不是魔法,而是 localize 数据表 + 通用构建器的确定性产物。以 fy 的月份本地化为线索,梳理调用链:

  1. localize.month 由 buildLocalizeFn 构造。该工厂函数读取 options.context(formatting 或 standalone)与 options.width(narrow/short/abbreviated/wide),再从 values/formattingValues 中取对应宽度数组。fy 的 month 只传了 values,因此 formatting(M 系列)与 stand-alone(L 系列)共享同一份数据——这正是快照中两系列输出完全相同的底层原因。
  2. 季度下标回调:quarter 的 argumentCallback: (quarter) => quarter - 1 把 1–4 的季度号映射为数组下标 0–3,从而取出 Q1 对应 "1e fearnsjier"。
  3. match.month 由 buildMatchFn 构造:先用 matchPatterns 选出与输入匹配的正则(如 ^... 匹配 mai.),再用 parsePatterns 数组按顺序 findIndex 定位下标并映射回枚举值。fy 的 parseMonthPatterns.any 中 /^m(r|a)/i 同时匹配 maart 与 maaie,且顺序上 maart 在前,导致快照中五月解析回三月——这是理解快照中若干"预期外"解析结果的关键。
  4. 序数统一后缀:ordinalNumber 不做参数区分,所有序数令牌(年/季/月/周/日/时/分/秒)统一 数字 + "e",保证了快照全表的一致性。

此外,formatLong 通过 buildFormatLongFn 依据宽度从 dateFormats/timeFormats/dateTimeFormats 取模板,formatRelative 则是纯模板查表。整条链路印证了 date-fns 的 locale 设计哲学:语言差异收敛为数据表,行为差异收敛为通用构建器。

如何在项目中使用 fy locale

按照 i18n 使用说明,date-fns 中支持本地化的函数包括 format、formatDistance、formatDistanceStrict、formatRelative(以及 formatDuration 等),使用方式是显式引入 locale 并作为 locale 选项传入:

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

format(new Date(2019, 1, 11), "EEEE d MMMM y", { locale: fy });
//=> 'moandei 11 febrewaris 2019'

format(new Date(2019, 1, 11), "PPPP", { locale: fy });
//=> 'moandei 11 febrewaris 2019'

formatDistance(new Date(2000, 5, 1), new Date(2000, 0, 1), { locale: fy });
//=> '5 moannen'

formatDistance(new Date(2000, 5, 1), new Date(2000, 0, 1), {
  locale: fy,
  addSuffix: true,
});
//=> 'oer 5 moannen'

date-fns 采用"按需引入"策略,不会像部分旧库那样默认打包全部语言,因此引入 fy 不会拖累其他语言用户的包体积。若需要统一的默认语言封装,可参考 i18n 文档中"默认 PP 格式 + 全局 localeId"的 wrapper 模式。

快照文档的工程价值

snapshot.md 本质上是 fy locale 的行为契约与回归测试基准。它把 format/parse 的双向映射、距离短语的模糊/严格两级表达、相对日期模板、时长单复数全部固化为可对拍的表格:任何人修改 localize 或 match 数据表后,都可以逐行核对快照,第一时间发现如"五月解析回三月"这类正则歧义回归。对于需要深度定制 fy 输出的开发者,快照 + 上述源码路径(localize、match、formatDistance、formatLong、formatRelative)构成了"结果可验证、原因可追踪"的完整闭环。

登录后查看全文
date-fns