date-fns 马其顿语(mk)locale 完整参考:format/parse 令牌、距离与相对时间的本地化实现

原创2026-09-18 13:49:011,932 阅读
文章标签:国际化跨平台前端

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,有三个值得注意的语言细节:

  1. 性别一致的名词词尾:马其顿语星期名词分“阴性”(недела 周日、среда 周三、сабота 周六)与“阳性”(其余四天),模板据此切换——阴性用 'минатата …' / 'ова …' / 'следната …',阳性用 'минатиот …' / 'овој …' / 'следниот …';
  2. вo / во 双写法:ова … вo 0:00(同一周)与 денес во 0:00(今天)并存,是马其顿语介词的变体写法;
  3. 回退策略: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 支撑解析回填。快照与源码互为印证,既是一份可直接查阅的语言对照表,也是马其顿语支持的行为回归基线。

登录后查看全文
date-fns