date-fns 马其顿语(mk)locale 完整参考:format/parse 令牌、距离与相对时间的本地化实现
date-fns 马其顿语(mk)locale 完整参考:format/parse 令牌、距离与相对时间的本地化实现
本篇以 date-fns 仓库中的 马其顿语 locale 快照文档 为主体,结合 mk locale 的完整源码实现,系统梳理马其顿语在 date-fns 中格式化(format)、解析(parse)、距离表达(formatDistance / formatDistanceStrict)、相对时间(formatRelative)与时长格式化(formatDuration)的全部本地化行为。读完本文,你将掌握 mk locale 的全部令牌输出、序数词规则、解析边界与实现文件对应关系,可直接用于多语言项目的时间显示与回填解析。
snapshot.md 是什么:locale 的“活文档”
在 date-fns 中,每个语言包目录下都有一份 snapshot.md,它是一份由真实运行结果生成的快照:以固定日期为输入,逐一记录 format、parse、formatDistance、formatDistanceStrict、formatRelative、formatDuration 的输出。因此它既是开发者的速查手册,也是回归测试的行为基线——任何对 locale 数据的修改都会反映到这份快照中。
mk 目录的完整结构如下(pkgs/core/src/locale/mk):
| 文件/目录 | 职责 |
|---|---|
index.ts |
汇总并导出 mk: Locale 对象,定义语言代码与周起始选项 |
_lib/formatDistance/index.ts |
距离表达词表与后缀逻辑(за / пред) |
_lib/formatLong/index.ts |
长格式(P/PP/PPP/PPPP、p/pp/ppp/pppp)模板 |
_lib/formatRelative/index.ts |
相对时间模板(вчера / денес / утре 等) |
_lib/localize/index.ts |
序数词、纪元、季度、月份、星期、时段的本土化值 |
_lib/match/index.ts |
上述值的正则匹配与解析模式 |
snapshot.md |
全部行为的运行快照 |
Locale 接口(pkgs/core/src/locale/types.ts)要求每个 locale 提供 code、formatDistance、formatRelative、localize、formatLong、match 六项能力,mk 正是按此结构组织的。
mk locale 的全局配置
index.ts 中导出的 mk 对象定义了关键选项:
export const mk: Locale = {
code: "mk",
formatDistance: formatDistance,
formatLong: formatLong,
formatRelative: formatRelative,
localize: localize,
match: match,
options: {
weekStartsOn: 1 /* Monday */,
firstWeekContainsDate: 4,
},
};
两个选项直接决定快照中 Yo、wo、Io 等“本地周/ISO 周”令牌的边界行为:
weekStartsOn: 1:每周从周一开始,这是马其顿的通用习惯;firstWeekContainsDate: 4:一年中的第一周必须包含 1 月 4 日(ISO 8601 同款规则)。
正因为如此,快照中 1987-02-11 的本地周编号年(Yo)解析结果是 1986-12-29(周一),而非该日所在公历年;0005-01-01 解析为 0003-12-29,即“本地周编号年”可以从公历年前一年开始。
format 与 parse:全部令牌行为详解
快照第一部分以 format 输出与 parse 回填两列并置,展示了同一日期文本能否被 parse 无损还原。以下按类别列出完整令牌数据(输入日期均含 12:13:14.015Z 时间部分,parse 结果列是该文本解析回的时间戳)。
年份:Calendar year(yo)与 Local week-numbering year(Yo)
| 令牌 | 日期 | format 结果 | parse 结果 |
|---|---|---|---|
| yo | 1987-02-11 | 1987-ми | 1987-01-01T00:00:00.000Z |
| yo | 0005-01-01 | 5-ти | 0005-01-01T00:00:00.000Z |
| Yo | 1987-02-11 | 1987-ми | 1986-12-29T00:00:00.000Z |
| Yo | 0005-01-01 | 4-ти | 0003-12-29T00:00:00.000Z |
可见年份也带序数词后缀,且本地周编号年(Yo)受 weekStartsOn/firstWeekContainsDate 影响,解析结果落到对应 ISO 周年的 12 月 29 日(周一)。
季度:formatting(Q)与 stand-alone(q)
| 令牌 | 日期 | format 结果 | parse 结果 |
|---|---|---|---|
| Qo | 2019-01-01 | 1-ви | 2019-01-01T00:00:00.000Z |
| Qo | 2019-04-01 | 2-ри | 2019-04-01T00:00:00.000Z |
| QQQ | 2019-01-01 | 1-ви кв. | 2019-01-01T00:00:00.000Z |
| QQQ | 2019-04-01 | 2-ри кв. | 2019-04-01T00:00:00.000Z |
| QQQQ | 2019-01-01 | 1-ви квартал | 2019-01-01T00:00:00.000Z |
| QQQQ | 2019-04-01 | 2-ри квартал | 2019-04-01T00:00:00.000Z |
| QQQQQ | 2019-01-01 | 1 | 2019-01-01T00:00:00.000Z |
| QQQQQ | 2019-04-01 | 2 | 2019-04-01T00:00:00.000Z |
qo/qqq/qqqq(stand-alone 季度)输出与 Qo/QQQ/QQQQ 完全一致:1-ви、1-ви кв.、1-ви квартал 等,parse 同样可还原。对应词表见 localize/index.ts。
月份:formatting(M)与 stand-alone(L)
序数月份(Mo / Lo),12 个月全部带序数后缀:
| 日期 | Mo / Lo 结果 |
|---|---|
| 01-11 | 1-ви |
| 02-11 | 2-ри |
| 03-11 | 3-ти |
| 04-10 | 4-ти |
| 05-10 | 5-ти |
| 06-10 | 6-ти |
| 07-10 | 7-ми |
| 08-10 | 8-ми |
| 09-10 | 9-ти |
| 10-10 | 10-ти |
| 11-10 | 11-ти |
| 12-10 | 12-ти |
缩写月份(MMM / LLL):
| 月份 | 结果 | parse |
|---|---|---|
| 1 月 | јан | 2019-01-01T00:00:00.000Z |
| 2 月 | фев | 2019-02-01T00:00:00.000Z |
| 3 月 | мар | 2019-03-01T00:00:00.000Z |
| 4 月 | апр | 2019-04-01T00:00:00.000Z |
| 5 月 | мај | 2019-05-01T00:00:00.000Z |
| 6 月 | јун | 2019-06-01T00:00:00.000Z |
| 7 月 | јул | 2019-07-01T00:00:00.000Z |
| 8 月 | авг | 2019-08-01T00:00:00.000Z |
| 9 月 | септ | Invalid Date |
| 10 月 | окт | 2019-10-01T00:00:00.000Z |
| 11 月 | ноем | 2019-11-01T00:00:00.000Z |
| 12 月 | дек | 2019-12-01T00:00:00.000Z |
全称月份(MMMM / LLLL):јануари、февруари、март、април、мај、јуни、јули、август、септември、октомври、ноември、декември,全部可被 parse 还原。
窄格式(MMMMM / LLLLL):输出与全称相同(马其顿语未单独定义窄格式,回退到全称),parse 均可还原。
注意快照中 9 月缩写
септ的 parse 结果为 Invalid Date:format 输出的是септ,而 match/index.ts 的缩写匹配模式是/^(јан|фев|мар|апр|мај|јун|јул|авг|сеп|окт|ноем|дек)/i(сеп而非септ),两者不一致导致文本无法被完整消费回填。这是快照作为“行为基线”直接暴露出的边界情况。
周与日:wo、Io、do、Do
| 令牌 | 日期 | format 结果 | parse 结果 |
|---|---|---|---|
| wo | 2019-01-01 | 1-ви | 2018-12-31T00:00:00.000Z |
| wo | 2019-12-01 | 48-ми | 2019-11-25T00:00:00.000Z |
| Io | 2019-01-01 | 1-ви | 2018-12-31T00:00:00.000Z |
| Io | 2019-12-01 | 48-ми | 2019-11-25T00:00:00.000Z |
| do | 2019-02-01 | 1-ви | 2019-02-01T00:00:00.000Z |
| do | 2019-02-11 | 11-ти | 2019-02-11T00:00:00.000Z |
| do | 2019-02-28 | 28-ми | 2019-02-28T00:00:00.000Z |
| do MMMM | 2019-02-01 | 1-ви февруари | 2019-02-01T00:00:00.000Z |
| do MMMM | 2019-02-11 | 11-ти февруари | 2019-02-11T00:00:00.000Z |
| do MMMM | 2019-02-28 | 28-ми февруари | 2019-02-28T00:00:00.000Z |
| Do | 2019-02-11 | 42-ри | 2019-02-11T00:00:00.000Z |
| Do | 2019-12-31 | 365-ти | 2019-12-31T00:00:00.000Z |
本地周(wo)与 ISO 周(Io)在该测试区间结果一致(1-ви / 48-ми),但注意周序号解析回的是当周的周一(如 48-ми → 2019-11-25)。
星期:formatting(E)、ISO(i)、local(e/c)
马其顿语一周七天(周日开始)为:недела、понеделник、вторник、среда、четврток、петок、сабота。以 2019-02-11(周一)与 2019-02-15(周五)为例:
| 令牌 | 周一 format | 周五 format | parse |
|---|---|---|---|
| E / EE / EEE | пон | пет | 可还原 |
| EEEE | понеделник | петок | 可还原 |
| EEEEE | П | П | 可还原(窄格式周一/周五同为 П) |
| EEEEEE | по | пе | 可还原 |
| io | 1-ви | 5-ти | 可还原 |
| iii / eee / ccc | пон | пет | 可还原 |
| iiii / eeee / cccc | понеделник | петок | 可还原 |
| iiiii / eeeee / ccccc | П | П | 可还原 |
| iiiiii / eeeeee / cccccc | по | пе | 可还原 |
ISO 日(io)与本地日(eo/co)的序数结果相同:周一为 1-ви、周五为 5-ти。窄格式 EEEEE 中周一与周五均输出 П,因为马其顿语“понеделник(周一)”和“петок(周五)”都以 П 开头——这类窄格式歧义在 parse 时由 parseDayPatterns 按顺序取首个匹配项解决。
时段:AM/PM(a)、含正午/午夜(b)、灵活时段(B)
快照显示 a/aa/aaa/aaaa/aaaaa、b/bb/bbb/bbbb/bbbbb、B/BB/BBB/BBBB/BBBBB 五种宽度输出完全一致:
| 时段 | 日期 | 结果 |
|---|---|---|
| a(am) | 11:13 / 02:13 | претпладне |
| a(pm) | 14:13 / 19:13 | попладне |
| b(同上) | — | претпладне / попладне |
| B 上午 | 11:13 | наутро |
| B 下午 | 14:13 | попладне |
| B 傍晚 | 19:13 | навечер |
| B 夜间 | 02:13 | ноќе |
全部时段类令牌(a/b/B 及其各宽度)的 parse 结果均为 Invalid Date——马其顿语时段的解析模式(见 match/index.ts)为 претпладне / попладне / полноќ / напладне / наутро / навечер / ноќе 等完整词,而快照输入文本无法被这些模式完整消费。从源码结构看,这是 parse 侧对时段文本的覆盖限制,format 侧输出不受影响。
小时、分钟、秒
| 令牌 | 日期 | format 结果 | parse 结果 |
|---|---|---|---|
| ho([1-12]) | 11:13 | 11-ти | 11:00:00 |
| ho | 23:13 | 11-ти | 23:00:00 |
| Ho([0-23]) | 11:13 | 11-ти | 11:00:00 |
| Ho | 23:13 | 23-ти | 23:00:00 |
| Ko([0-11]) | 11:13 | 11-ти | 11:00:00 |
| Ko | 23:13 | 11-ти | 23:00:00 |
| ko([1-24]) | 11:13 | 11-ти | 11:00:00 |
| ko | 23:13 | 23-ти | 23:00:00 |
| mo | 12:01 | 1-ви | 12:01:00 |
| mo | 12:55 | 55-ти | 12:55:00 |
| so | 12:13:01 | 1-ви | 12:13:01 |
| so | 12:13:55 | 55-ти | 12:13:55 |
长格式:P/p 系列(本地化日期、时间与组合)
日期(P 系列),以 1987-01-11 等为代表(parse 均可还原,除带 9 月缩写者外):
| 令牌 | 示例结果 |
|---|---|
| P | 11/01/1987(dd/MM/yyyy) |
| PP | 11 јан 1987(dd MMM yyyy,9 月为 11 септ 1987,parse 为 Invalid Date) |
| PPP | 11 јануари 1987(dd MMMM yyyy) |
| PPPP | недела, 11 јануари 1987(EEEE, dd MMMM yyyy,含星期全称) |
时间(p 系列):
| 令牌 | 示例结果 | parse |
|---|---|---|
| p | 12:13(H:mm) | 可还原 |
| pp | 12:13:14(HH:mm:ss) | 可还原 |
| ppp | 12:13:14 GMT+0(HH:mm:ss z) | Errored |
| pppp | 12:13:14 GMT+00:00(HH:mm:ss zzzz) | Errored |
日期 + 时间组合:
| 令牌 | 示例结果 | parse |
|---|---|---|
| Pp | 11/01/1987 12:13 | 可还原 |
| PPpp | 11 јан 1987 12:13:14 | 可还原(9 月为 Invalid Date) |
| PPPppp | 11 јануари 1987 12:13:14 GMT+0 | Errored |
| PPPPpppp | недела, 11 јануари 1987 12:13:14 GMT+00:00 | Errored |
这些模板定义在 formatLong/index.ts:short: "dd/MM/yyyy"、medium: "dd MMM yyyy"、long: "dd MMMM yyyy"、full: "EEEE, dd MMMM yyyy",时间侧为 H:mm、HH:mm:ss、HH:mm:ss z、HH:mm:ss zzzz。快照中 ppp/pppp 等带时区令牌的 parse 结果为 Errored(而非 Invalid Date),说明带 GMT+0 / GMT+00:00 时区后缀的文本无法被 mk 的匹配表完整解析,属于快照如实记录的解析边界。
马其顿语序数词规则(源码级)
快照中大量 -ви / -ри / -ми / -ти 后缀来自 localize/index.ts 的 ordinalNumber 实现:
const rem100 = number % 100;
if (rem100 > 20 || rem100 < 10) {
switch (rem100 % 10) {
case 1: return number + "-ви"; // 1, 21, 31…
case 2: return number + "-ри"; // 2, 22, 32…
case 7:
case 8: return number + "-ми"; // 7, 8, 27, 28…
}
}
return number + "-ти"; // 其余默认
规则可归纳为:个位为 1 → -ви,个位为 2 → -ри,个位为 7 或 8 → -ми,其余(含 10–20 整段)→ -ти。这解释了快照中 1-ви、2-ри、7-ми、8-ми、11-ти、42-ри、365-ти 的分布。解析侧由 match/index.ts 的 /^(\d+)(-?[врмт][и])?/i 模式匹配任意序数后缀,parse 提取纯数字。
formatDistance:马其顿语距离表达
快照以 2000-01-01 00:00 为基准(“now”),列出过去与未来两个方向的距离表达。核心输出如下(完整数据见 snapshot.md):
| 目标日期 | 结果 | includeSeconds: true | addSuffix: true(未来) |
|---|---|---|---|
| 2006-01-01 | околу 6 години | 同左 | за околу 6 години |
| 2001-06-01 | повеќе од 1 година | 同左 | за повеќе од 1 година |
| 2001-02-01 | околу 1 година | 同左 | за околу 1 година |
| 2000-06-01 | 5 месеци | 同左 | за 5 месеци |
| 2000-03-01 | 2 месеци | 同左 | за 2 месеци |
| 2000-01-15 | 14 дена | 同左 | за 14 дена |
| 2000-01-02 | 1 ден | 同左 | за 1 ден |
| 2000-01-01 06:00 | околу 6 часа | 同左 | за околу 6 часа |
| 2000-01-01 00:45 | околу 1 час | 同左 | за околу 1 час |
| 2000-01-01 00:30 | 30 минути | 同左 | за 30 минути |
| 2000-01-01 00:01 | 1 минута | 同左 | за 1 минута |
| 2000-01-01 00:00:25 | помалку од минута | половина минута | за помалку од минута |
| 2000-01-01 00:00:15 | помалку од минута | помалку од 20 секунди | за помалку од минута |
| 2000-01-01 00:00:05 | помалку од минута | помалку од 10 секунди | за помалку од минута |
| 2000-01-01 00:00:00 | помалку од минута | помалку од 5 секунди | пред помалку од минута |
过去方向(1999-12-31 及更早)对应输出为 пред … 前缀:пред 1 минута、пред 15 минути、пред 30 минути、пред 2 дена、пред 2 месеци、пред 7 месеци、пред 1 година、пред 6 години 等,且 includeSeconds 的秒级细分同样生效(половина минута = 半分钟、помалку од 10/20 секунди = 不足 10/20 秒)。
关键实现位于 formatDistance/index.ts:
- 词表使用
one/other双形模板,count === 1取one,否则将{{count}}替换进other(马其顿语无复数三形,单数/复数两形即可覆盖); - 当
addSuffix: true时,comparison > 0(未来)加前缀за,否则(过去)加前缀пред。
这与快照中“за(未来)/ пред(过去)”的分布完全吻合。另外注意词表中 aboutXWeeks 的复数形误植为 околу {{count}} месеци、aboutXMonths 为 околу {{count}} недели(源码现状),从源码结构看属于需要留意的词表细节。
formatDistanceStrict:精确距离
formatDistanceStrict 不再使用“околу(大约)/ повеќе од(多于)”等约数,直接输出精确数字(全部支持 за/пред 后缀与强制单位):
| 目标日期 | 结果 | addSuffix: true | 强制单位 hour |
|---|---|---|---|
| 2006-01-01 | 6 години | за 6 години | 52608 часа |
| 2001-06-01 | 1 година | за 1 година | 12408 часа |
| 2000-06-01 | 5 месеци | за 5 месеци | 3648 часа |
| 2000-01-15 | 14 дена | за 14 дена | 336 часа |
| 2000-01-02 | 1 ден | за 1 ден | 24 часа |
| 2000-01-01 06:00 | 6 часа | за 6 часа | 6 часа |
| 2000-01-01 00:45 | 45 минути | за 45 минути | 1 час |
| 2000-01-01 00:15 | 15 минути | за 15 минути | 0 часа |
| 2000-01-01 00:00:25 | 25 секунди | за 25 секунди | 0 часа |
| 2000-01-01 00:00:00 | 0 секунди | пред 0 секунди | 0 часа |
过去方向输出 пред …:пред 25 секунди、пред 1 минута、пред 45 минути、пред 1 час、пред 6 часа、пред 17 дена、пред 2 месеци、пред 1 година、пред 5 години 等。“强制单位”(如 unit: 'hour')会把整个差值换算成小时,如 2006-01-01 距基准 52608 小时。
formatRelative:相对时间表达
以 2000-01-01 00:00 为基准,formatRelative 的完整输出:
| 目标日期 | 结果 |
|---|---|
| 2000-01-10 | 10/01/2000(超出本周,回退 P 格式) |
| 2000-01-05 | следната среда вo 0:00 |
| 2000-01-02 | утре во 0:00 |
| 2000-01-01 | денес во 0:00 |
| 1999-12-31 | вчера во 0:00 |
| 1999-12-27 | овој понеделник вo 0:00 |
| 1999-12-21 | 21/12/1999(超出本周,回退 P 格式) |
实现位于 formatRelative/index.ts,有三个值得注意的语言细节:
- 性别一致的名词词尾:马其顿语星期名词分“阴性”(недела 周日、среда 周三、сабота 周六)与“阳性”(其余四天),模板据此切换——阴性用
'минатата …'/'ова …'/'следната …',阳性用'минатиот …'/'овој …'/'следниот …'; - вo / во 双写法:
ова … вo 0:00(同一周)与денес во 0:00(今天)并存,是马其顿语介词的变体写法; - 回退策略:
lastWeek/nextWeek内部先调用isSameWeek(pkgs/core/src/isSameWeek/index.ts)判断目标是否仍在同一周,若不在则退回“上周/下周”模板;超出本周范围(如 2000-01-10)直接回退P(dd/MM/yyyy)。
formatDuration:时长格式化
formatDuration 将 Duration 对象格式化为马其顿语,覆盖 0/1/2 三档以展示单复数变化:
| Duration | 结果 | Duration | 结果 | |
|---|---|---|---|---|
| {"years":0} | 0 години | {"hours":0} | 0 часа | |
| {"years":1} | 1 година | {"hours":1} | 1 час | |
| {"years":2} | 2 години | {"hours":2} | 2 часа | |
| {"months":0} | 0 месеци | {"minutes":0} | 0 минути | |
| {"months":1} | 1 месец | {"minutes":1} | 1 минута | |
| {"months":2} | 2 месеци | {"minutes":2} | 2 минути | |
| {"weeks":0} | 0 недели | {"seconds":0} | 0 секунди | |
| {"weeks":1} | 1 недела | {"seconds":1} | 1 секунда | |
| {"weeks":2} | 2 недели | {"seconds":2} | 2 секунди | |
| {"days":0} | 0 дена | |||
| {"days":1} | 1 ден | |||
| {"days":2} | 2 дена |
单复数形态清晰:година/години、месец/месеци、недела/недели、ден/дена、час/часа、минута/минути、секунда/секунди,全部复用 formatDistance 词表的单复数两形机制。
如何在自己的项目中使用 mk locale
mk 是标准 date-fns locale,按 i18n 使用指南 引入即可:
import { format, formatDistance, formatRelative, parse } from "date-fns";
import { mk } from "date-fns/locale";
// 格式化
format(new Date(2019, 0, 11), "do MMMM yyyy", { locale: mk });
// => "11-ти јануари 2019"
format(new Date(1987, 1, 11), "PPPP", { locale: mk });
// => "среда, 11 февруари 1987"
// 相对时间
formatRelative(new Date(2000, 0, 2), new Date(2000, 0, 1), { locale: mk });
// => "утре во 0:00"
// 距离
formatDistance(new Date(2000, 5, 1), new Date(2000, 0, 1), { locale: mk });
// => "5 месеци"
使用前请留意快照中记录的三类解析边界:9 月缩写 септ 无法 parse、时段类(a/b/B)文本 parse 返回 Invalid Date、带时区的 ppp/pppp 系列 parse 返回 Errored——在设计“先格式化再回填解析”的场景时,应避免依赖这些令牌做往返还原。
小结
mk locale 的本地化行为可完整归纳为“一份快照 + 五份实现”:snapshot.md 记录了全部 format/parse 令牌、距离、相对时间与时长的马其顿语输出;localize 定义了序数词与单位词表,formatDistance 实现了 за/пред 前后缀,formatLong 提供 P/p 系列模板,formatRelative 处理周内/周外与性别词尾,match 支撑解析回填。快照与源码互为印证,既是一份可直接查阅的语言对照表,也是马其顿语支持的行为回归基线。