date-fns 希伯来语(he)Locale 深度解析:format / parse 快照与本地化实现全览

原创2026-09-18 09:30:531,642 阅读
文章标签:国际化跨平台前端

date-fns 希伯来语(he)Locale 深度解析:format / parse 快照与本地化实现全览

本文以 date-fns 仓库中 pkgs/core/src/locale/he/snapshot.md 为骨架,完整解读希伯来语 locale 在 format、parse、formatDistance、formatDistanceStrict、formatRelative、formatDuration 六个 API 上的真实行为快照,并结合 pkgs/core/src/locale/he/ 下的 TypeScript 源码(localize、match、formatLong、formatDistance、formatRelative)逐项印证这些输出背后的实现机制。读完本文,你将掌握希伯来语 locale 的序数词性别规则、双数(dual)语法、时间表达习惯(如 "בשעה" 前缀、AM/PM 缩写),以及如何在项目中正确启用 he locale 并排查解析失败场景。

一、快照文档是什么:一份"行为契约"

snapshot.md 是 date-fns 为每个语言 locale 自动维护的行为快照:它用固定的一组输入日期,记录该 locale 在 format / parse / formatDistance / formatDistanceStrict / formatRelative / formatDuration 六个 API 上的精确输出。任何人(包括搜索引擎、Agent 和开发者)都可以把它当作一张"对照表":想确认希伯来语下某个 token 的输出,查快照即可;想排查本地化差异,也可以把快照与实际运行结果比对。

快照中的日期全部使用 UTC(时区后缀 Z),例如 1987-02-11T12:13:14.015Z,因此结果与运行环境的时区无关,具有可复现性。快照中 parse 列给出的是把 format 的输出再解析回去得到的时间点(通常精确到秒或天),若解析失败则标记为 Invalid Date 或 Errored——这两种标记本身就是重要的行为线索,后文会专门分析。

希伯来语 locale 的入口在 pkgs/core/src/locale/he/index.ts,它导出了 he 对象:

export const he: Locale = {
  code: "he",
  formatDistance: formatDistance,
  formatLong: formatLong,
  formatRelative: formatRelative,
  localize: localize,
  match: match,
  options: {
    weekStartsOn: 0 /* Sunday */,
    firstWeekContainsDate: 1,
  },
};

注意 options.weekStartsOn: 0(一周从周日开始,符合以色列习惯),firstWeekContainsDate: 1(一年第一周必须包含 1 月 1 日)。这两个选项直接影响了快照中本地周(wo/eo 等)与本地周年的计算。该 locale 已在 pkgs/core/src/locale/index.ts 中通过 export * from "./he/index.ts" 统一导出,可通过 date-fns/locale 直接引入。

二、启用希伯来语 locale 的三种方式

在写代码前先确认如何接入 he locale。date-fns 中 locale 作为最后一个可选参数传入支持本地化的函数:

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

format(new Date(1987, 1, 11, 12, 13), "PPPP", { locale: he });
// => "יום רביעי, 11 בפברואר 1987"

formatDistance(new Date(2000, 0, 1, 0, 0), new Date(2001, 0, 1, 0, 0), { locale: he });
// => "כשנה"

formatRelative(new Date(2000, 0, 2, 0, 0), new Date(2000, 0, 1, 0, 0), { locale: he });
// => "מחר בשעה 0:00"

也可以通过 setDefaultOptions 全局设置默认 locale,让所有支持 Locale 参数的函数自动使用希伯来语:

import { setDefaultOptions } from "date-fns";
import { he } from "date-fns/locale";

setDefaultOptions({ locale: he });

三、format 与 parse 快照全解

这是快照中体量最大的一张表:每个 token 用多个代表性日期验证输出,format 列是格式化结果,parse 列是把该结果交给 parse 函数解析回来的时间。以下分 token 家族逐一解读(日期均为 UTC)。

3.1 年份:yo 与 Yo

Token Date format 结果 parse 结果
yo 1987-02-11T12:13:14.015Z 1987 1987-01-01T00:00:00.000Z
yo 0005-01-01T12:13:14.015Z חמישית Invalid Date
Yo 1987-02-11T12:13:14.015Z 1987 1986-12-28T00:00:00.000Z
Yo 0005-01-01T12:13:14.015Z חמישית Invalid Date
  • yo 是日历年的序数形式,Yo 是本地周-numbering 年(local week-numbering year)的序数形式。1987 年输出数字 1987,但年份 5 输出希伯来语序数词 חמישית("第五")。
  • 快照标记为 Invalid Date 的原因:0005 被格式化为希伯来语词形 חמישית,而 parse 的序数匹配(见 match.ordinalNumber)返回的是 1–10 的序号数字,当把 חמישית 作为年解析时无法映射回有效年份,因此解析失败。
  • 注意 Yo 的 parse 结果 1986-12-28:1987 年按 weekStartsOn: 0、firstWeekContainsDate: 1 规则,本地周年的第 1 周从 1986-12-28(周日)开始。

3.2 季度:Qo / QQQ / QQQQ / QQQQQ(格式化)与 qo / qqq / qqqq / qqqqq(独立)

Token Date format 结果 parse 结果
Qo 2019-01-01 ראשון 2019-01-01
Qo 2019-04-01 שני 2019-04-01
QQQ 2019-01-01 Q1 2019-01-01
QQQ 2019-04-01 Q2 2019-04-01
QQQQ 2019-01-01 רבעון 1 2019-01-01
QQQQ 2019-04-01 רבעון 2 2019-04-01
QQQQQ 2019-01-01 1 2019-01-01
QQQQQ 2019-04-01 2 2019-04-01
qo / qqq / qqqq / qqqqq 同上 与 Q 系列完全一致 与 Q 系列一致
  • Q 系列用于格式化上下文,q 系列用于独立上下文;希伯来语中两者输出完全一致。
  • 序数(Qo)输出 ראשון(第一)/ שני(第二);缩写(QQQ)输出 Q1/Q2;完整(QQQQ)输出 רבעון 1("第 1 季度");最窄(QQQQQ)只输出数字。
  • 这些词形定义在 localize 的 quarterValues:narrow: ["1","2","3","4"]、abbreviated: ["Q1",...]、wide: ["רבעון 1",...]。

3.3 月份:Mo / MMM / MMMM / MMMMM(格式化)与 Lo / LLL / LLLL / LLLLL(独立)

快照中 12 个月份全部取样(日期分别为 1/11、2/11、3/11、4/10、5/10 … 12/10),结果如下:

序数(Mo/Lo,1–10 月用希伯来语词,11、12 月退回数字):

月份 Mo 结果 月份 Mo 结果
1 月 ראשון 7 月 שביעי
2 月 שני 8 月 שמיני
3 月 שלישי 9 月 תשיעי
4 月 רביעי 10 月 עשירי
5 月 חמישי 11 月 11
6 月 שישי 12 月 12

缩写(MMM/LLL):

月份 结果 月份 结果
1 月 ינו׳ 7 月 יולי
2 月 פבר׳ 8 月 אוג׳
3 月 מרץ 9 月 ספט׳
4 月 אפר׳ 10 月 אוק׳
5 月 מאי 11 月 נוב׳
6 月 יוני 12 月 דצמ׳

完整(MMMM/LLLL): ינואר、פברואר、מרץ、אפריל、מאי、יוני、יולי、אוגוסט、ספטמבר、אוקטובר、נובמבר、דצמבר。

最窄(MMMMM/LLLLL): 直接输出数字 1–12。

这些数组定义在 localize 的 monthValues。值得注意的是,מרץ(三月)、מאי(五月)、יוני(六月)、יולי(七月)本身就是完整词形,因此缩写与完整形式相同,这是希伯来语自身拼写特点决定的。

3.4 周:本地周 wo 与 ISO 周 Io

Token Date format 结果 parse 结果
wo 2019-01-01 ראשון 2018-12-30T00:00:00.000Z
wo 2019-12-01 49 2019-12-01T00:00:00.000Z
Io 2019-01-01 ראשון 2018-12-31T00:00:00.000Z
Io 2019-12-01 48 2019-11-25T00:00:00.000Z
  • 周 1(序数)输出 ראשון;周 49/48 输出数字。
  • 本地周(wo)从周日开始:2019-01-01 落在 2019 年本地第 1 周,该周起始日为 2018-12-30;ISO 周(Io)从周一开始:同一日期落在 ISO 2019 年第 1 周,起始日为 2018-12-31。这正是 he 的 weekStartsOn: 0 与 ISO 标准(weekStartsOn: 1)差异的直接体现。

3.5 日:do(日序)、Do(年中日)、do MMMM(组合)

Token Date format 结果 parse 结果
do 2019-02-01 ראשון 2019-02-01
do 2019-02-11 11 2019-02-11
do 2019-02-28 28 2019-02-28
do MMMM 2019-02-01 ראשון פברואר 2019-02-01
do MMMM 2019-02-11 11 פברואר 2019-02-11
do MMMM 2019-02-28 28 פברואר 2019-02-28
Do 2019-02-11 42 2019-02-11
Do 2019-12-31 365 2019-12-31
  • 日期 1 输出 ראשון(第一),其余输出纯数字。do MMMM 组合时词序为"数字 + 月份"。
  • Do(年中第几天)始终输出数字,2 月 11 日是 2019 年第 42 天,12 月 31 日是第 365 天。

3.6 星期:E/EE/EEE/EEEE/EEEEE/EEEEEE(格式化日)、i 系列(ISO 日)、e 系列(本地日)、c 系列(独立日)

快照以周一(2019-02-11)与周五(2019-02-15)取样:

Token 周一 周五
E / EE / EEE יום ב׳ יום ו׳
EEEE יום שני יום שישי
EEEEE / EEEEEE ב׳ ו׳
io(ISO 序数) ראשון חמישי
iii יום ב׳ יום ו׳
iiii יום שני יום שישי
iiiii / iiiiii ב׳ ו׳
eo(本地序数) שני שישי
eee / eeee 与 E 系列相同 与 E 系列相同
eeeee / eeeeee ב׳ / ו׳ ב׳ / ו׳
co(独立序数) שני שישי
ccc / cccc / ccccc / cccccc 与 e 系列相同 与 e 系列相同
  • E/e/c 系列在希伯来语中输出基本一致:缩写为 יום ב׳("第 2 天")、完整为 יום שני("星期一")、最窄为 ב׳。
  • 序数词(io/eo/co)中,eo/co 直接输出星期名(周一为 שני),而 io(ISO 序数,周一=1)输出 ראשון。注意 ISO 序数与本地序数的错位:快照中同为 2019-02-11(周一),io → ראשון,eo/co → שני,这是 weekday 编号体系不同(ISO 从 1=周一,本地从 0=周日)造成的。

3.7 时段:a / b / B 三族

AM/PM(a 系列,长度 1–5 输出相同):

Date format 结果 parse 结果
2019-02-11T11:13 לפנה״צ 2019-02-11T00:00:00.000Z
2019-02-11T14:13 אחה״צ 2019-02-11T12:00:00.000Z
2019-02-11T19:13 אחה״צ 2019-02-11T12:00:00.000Z
2019-02-11T02:13 לפנה״צ 2019-02-11T00:00:00.000Z

לפנה״צ 是 "לפני הצהריים"(中午之前,AM)的缩写,אחה״צ 是 "אחרי הצהריים"(中午之后,PM)的缩写。解析时只恢复时段边界(00:00 或 12:00)。

AM/PM/noon/midnight(b 系列,1–5 长度输出相同): 与 a 系列完全一致,因为希伯来语中午夜/正午没有单独的独立词形需求;相关词形(חצות=午夜、צהריים=正午)定义在 localize 的 dayPeriodValues。

弹性时段(B 系列):

Date B/BB/BBB/BBBB 结果 BBBBB 结果 parse 结果
11:13 בבוקר(上午) בבוקר 2019-02-11T04:00:00.000Z
14:13 אחר הצהריים(下午) בצהריים 2019-02-11T12:00:00.000Z
19:13 בערב(晚上) בערב 2019-02-11T17:00:00.000Z
02:13 בלילה(夜里) בלילה 2019-02-11T00:00:00.000Z
  • 完整/缩写形式区分四个时段:בבוקר、אחר הצהריים、בערב、בלילה;最窄形式 BBBBB 的下午用 בצהריים("中午")而非 אחר הצהריים。
  • parse 结果反映时段的起始边界:上午→04:00、下午→12:00、晚上→17:00、夜里→00:00。这些"时段→默认时间"的映射来自 date-fns 的 parse 实现与 match 的 parseDayPeriodPatterns 配合。

3.8 小时、分钟、秒

Token Date format 结果 parse 结果
ho(1–12) 11:13 11 11:00
ho 23:13 11 23:00
Ho(0–23) 11:13 11 11:00
Ho 23:13 23 23:00
Ko(0–11) 11:13 11 11:00
Ko 23:13 11 23:00
ko(1–24) 11:13 11 11:00
ko 23:13 23 23:00
mo 12:01 ראשונה 12:01
mo 12:55 55 12:55
so 12:13:01 ראשונה 12:13:01
so 12:13:55 55 12:13:55
  • 小时 token 的 format 输出均为纯数字;parse 结果按 token 范围还原(如 ho 对 23:13 输出 11,解析回 23:00,说明 12 小时制依赖 AM/PM 上下文才能唯一确定)。
  • 分钟/秒的序数(mo/so)在值为 1 时输出 ראשונה——注意这里是阴性形式(ראשונה 而非 ראשון),因为分钟(דקה)和秒(שנייה)在希伯来语中是阴性名词。这正是序数词性别规则的应用点,详见下文"序数词实现"。

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

日期:

Token 示例结果(1987-02-11) 说明
P 11.2.1987 短,d.M.y
PP 11 בפבר׳ 1987 中,d בMMM y,月份带介词 ב
PPP 11 בפברואר 1987 长,d בMMMM y
PPPP יום רביעי, 11 בפברואר 1987 完整,EEEE, d בMMMM y,带星期

时间:

Token 示例结果 parse 结果
p 12:13 12:13:00
pp 12:13:14 12:13:14
ppp 12:13:14 GMT+0 Errored
pppp 12:13:14 GMT+00:00 Errored

日期 + 时间组合:

Token 示例结果(1987-02-11) parse 结果
Pp 11.2.1987, 12:13 12:13:00
PPpp 11 בפבר׳ 1987, 12:13:14 12:13:14
PPPppp 11 בפברואר 1987 בשעה 12:13:14 GMT+0 Errored
PPPPpppp יום רביעי, 11 בפברואר 1987 בשעה 12:13:14 GMT+00:00 Errored
  • P/p 系列的模板定义在 formatLong:日期为 EEEE, d בMMMM y(full)、d בMMMM y(long)、d בMMM y(medium)、d.M.y(short);时间为 H:mm:ss zzzz(full)、H:mm:ss z(long)、H:mm:ss(medium)、H:mm(short)。
  • 希伯来语特有的介词 ב("在/于")被嵌入模板:11 בינואר 1987 意为 "11 于 一月 1987"。日期与时间的组合模板使用 {{date}} 'בשעה' {{time}}("在...时刻")和 {{date}}, {{time}}。
  • ppp/pppp 包含 GMT+0 / GMT+00:00 时区文本,而 parse 的本地化匹配没有覆盖该时区文本格式,因此快照中所有带时区文本的结果均标记为 Errored。这是使用含时区长格式做 round-trip 解析时需要注意的已知边界。

四、序数词的性别规则:为什么 5 是 "חמישית" 而不是 "חמישי"

快照中最有语言特色的现象是序数词的阴阳性。看 localize 的 ordinalNumber 实现:

const ordinalNumber: LocalizeFn<number> = (dirtyNumber, options) => {
  const number = Number(dirtyNumber);
  // We only show words till 10
  if (number <= 0 || number > 10) return String(number);

  const unit = String(options?.unit);
  const isFemale = ["year", "hour", "minute", "second"].indexOf(unit) >= 0;

  const male = ["ראשון","שני","שלישי","רביעי","חמישי","שישי","שביעי","שמיני","תשיעי","עשירי"];
  const female = ["ראשונה","שנייה","שלישית","רביעית","חמישית","שישית","שביעית","שמינית","תשיעית","עשירית"];

  const index = number - 1;
  return isFemale ? female[index] : male[index];
};

规则清晰:

  1. 数字大于 10(或小于等于 0)时直接输出数字,这正是快照中月份 11/12 输出 11/12、周 49、日 11/28 输出数字的原因;
  2. 1–10 使用希伯来语序数词,且根据被修饰单位的名词性别二选一:
    • 阳性(male):ראשון、שני、שלישי … 用于月份、季度、日期、星期(如 Mo 的 ראשון、do 的 ראשון);
    • 阴性(female):ראשונה、שנייה、שלישית … 用于年、小时、分钟、秒(如年份 5 的 חמישית、分钟 1 的 ראשונה、秒 1 的 ראשונה)。
  3. 性别判定写死在 isFemale 列表里:["year", "hour", "minute", "second"] 为阴性,其余为阳性。

同时,match 的 ordinalNumber 定义了对应的解析正则:

const matchOrdinalNumberPattern =
  /^(\d+|(ראשון|שני|שלישי|רביעי|חמישי|שישי|שביעי|שמיני|תשיעי|עשירי|ראשונה|שנייה|שלישית|רביעית|חמישית|שישית|שביעית|שמינית|תשיעית|עשירית))/i;
const parseOrdinalNumberPattern = /^(\d+|רא|שנ|של|רב|ח|שי|שב|שמ|ת|ע)/i;

解析时优先匹配数字,若匹配到希伯来语词根(רא、שנ…),通过 valueCallback 在 ordinalName 数组中的索引 +1 还原成数字。因此 1–10 的序数词可以正确 round-trip,而大于 10 的数字序数(如年份 1987 的 1987)也能解析——唯独像 "年份 5 → חמישית" 这种把年份写成序数词的场景,解析器把 חמישית 还原为数字 5 后作为年份无法构成有效日期,快照便标记为 Invalid Date。

五、formatDistance:双数语法与特殊日期词

快照假设基准时间为 2000 年 1 月 1 日 00:00,第三列 includeSeconds: true、第四列 addSuffix: true。实现位于 formatDistance,每个 token 都是 { one, two, other } 三态结构——这正是希伯来语**双数(dual)**语法的体现:

token one(1) two(2) other(≥3)
lessThanXSeconds פחות משנייה פחות משתי שניות פחות מ־{{count}} שניות
xSeconds שנייה שתי שניות {{count}} שניות
halfAMinute חצי דקה — —
lessThanXMinutes פחות מדקה פחות משתי דקות פחות מ־{{count}} דקות
xMinutes דקה שתי דקות {{count}} דקות
aboutXHours כשעה כשעתיים כ־{{count}} שעות
xHours שעה שעתיים {{count}} שעות
xDays יום יומיים {{count}} ימים
aboutXWeeks כשבוע כשבועיים כ־{{count}} שבועות
xWeeks שבוע שבועיים {{count}} שבועות
aboutXMonths כחודש כחודשיים כ־{{count}} חודשים
xMonths חודש חודשיים {{count}} חודשים
aboutXYears כשנה כשנתיים כ־{{count}} שנים
xYears שנה שנתיים {{count}} שנים
overXYears יותר משנה יותר משנתיים יותר מ־{{count}} שנים
almostXYears כמעט שנה כמעט שנתיים כמעט {{count}} שנים

对应快照中的代表性输出(addSuffix: false):

  • 6 年前(2006)→ כ־6 שנים;2 年前(2002)→ כשנתיים(双数);1 年多(2001-06)→ יותר משנה;1 年前(2001-01)→ כשנה。
  • 14 天 → 14 ימים;2 天前 → יומיים(双数);1 天前(1999-12-30)→ יומיים?不,注意快照:1999-12-30 是两天前,结果为 יומיים(双数"两天"),1999-12-31 是昨天 → יום,2000-01-02 是明天 → יום。
  • 分钟:דקה(1)、30 דקות、15 דקות;秒相关:פחות מדקה(不足一分钟)、חצי דקה(半分钟)、פחות מ־10 שניות 等。

5.1 addSuffix 与特殊日期词

addSuffix: true 时,未来加前缀 בעוד ("在...之后"),过去加 לפני ("在...之前"):בעוד 5 חודשים、לפני 17 ימים。

但代码里有一段特殊处理(xDays + addSuffix + count ≤ 2):

if (token === "xDays" && options?.addSuffix && count <= 2) {
  if (options.comparison && options.comparison > 0) {
    return count === 1 ? "מחר" : "מחרתיים";
  }
  return count === 1 ? "אתמול" : "שלשום";
}

即不输出 "בעוד יום"(一天后)/ "לפני יום"(一天前)这类表达,而是直接使用专用日期词:

  • 明天 → מחר;后天 → מחרתיים;
  • 昨天 → אתמול;前天 → שלשום。

快照验证:2000-01-02(明天)→ מחר;1999-12-31(昨天)→ אתמול;1999-12-30(前天)→ שלשום。

5.2 includeSeconds

includeSeconds: true 时,不足一分钟的时间被细分:25s → חצי דקה(半分钟)、15s → פחות מ־20 שניות、5s → פחות מ־10 שניות、0s → פחות מ־5 שניות。这与 lessThanXSeconds/xSeconds/halfAMinute 三个 token 的分段逻辑一致。

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

快照同样以 2000-01-01 00:00 为基准,区别是不做约数,直接输出精确值;第四列展示强制单位(unit: 'hour')时全部折算为小时。

代表性输出:

日期 默认结果 addSuffix: true 强制 hour
2006-01-01 6 שנים בעוד 6 שנים 52608 שעות
2002-01-01 שנתיים בעוד שנתיים 17544 שעות
2000-01-15 14 ימים בעוד 14 ימים 336 שעות
2000-01-01T01:00 שעה בעוד שעה שעה
2000-01-01T00:00:00 0 שניות לפני 0 שניות 0 שעות
1999-12-31T23:59:55 5 שניות לפני 5 שניות 0 שעות
1999-12-30 יומיים שלשום 48 שעות
1994-01-01 6 שנים לפני 6 שנים 52584 שעות

要点:

  1. 双数词仍然生效:שנתיים、יומיים、חודשיים 分别对应 2 年、2 天、2 个月;
  2. addSuffix: true 的 1 天场景复用特殊词:2000-01-02 → מחר,1999-12-30 → שלשום(与 formatDistance 相同的 xDays 特判,因为 formatDistanceStrict 内部也走同一 formatDistance 回调);
  3. 强制单位 hour 时把任意时间差折算为小时(含闰年/非闰年差异:2004 年(闰年)→ 35064 小时,2003 年 → 26304 小时,差值恰为 1 天),不足 1 小时的小数部分按四舍五入显示为 0/1 小时。

七、formatRelative:相对日期短语

formatRelative 把"今天/明天/昨天/上周/下周"等相对日期翻译成希伯来语短语(基准 2000-01-01 00:00)。模板在 formatRelative:

const formatRelativeLocale = {
  lastWeek: "eeee 'שעבר בשעה' p",
  yesterday: "'אתמול בשעה' p",
  today: "'היום בשעה' p",
  tomorrow: "'מחר בשעה' p",
  nextWeek: "eeee 'בשעה' p",
  other: "P",
};

快照验证:

日期 结果
2000-01-10(下周) 10.1.2000(超出下周范围 → 回退 P 格式)
2000-01-05(下周三) יום רביעי בשעה 0:00
2000-01-02(明天) מחר בשעה 0:00
2000-01-01(今天) היום בשעה 0:00
1999-12-31(昨天) אתמול בשעה 0:00
1999-12-27(上周一) יום שני שעבר בשעה 0:00
1999-12-21(更早) 21.12.1999(回退 P 格式)

结构规律:'אתמול בשעה' p 中 '...' 是字面量、p 是本地化短时间(H:mm,输出 0:00);eeee 展开为星期完整词;lastWeek 用 שעבר("过去的")而 nextWeek 用 בשעה;超出相对范围(大于 1 周)时回退到 P(d.M.y)。这解释了 0:00 这种看似"非 24 小时"的输出——H 是 0–23 制,午夜即为 0。

八、formatDuration:持续时间片段

formatDuration 把 Duration 对象按单位片段本地化,同样使用 one/two/other 三态:

Duration 结果 Duration 结果
{"years":0} 0 שנים {"days":0} 0 ימים
{"years":1} שנה {"days":1} יום
{"years":2} שנתיים {"days":2} יומיים
{"months":0} 0 חודשים {"hours":0} 0 שעות
{"months":1} חודש {"hours":1} שעה
{"months":2} חודשיים {"hours":2} שעתיים
{"weeks":0} 0 שבועות {"minutes":0} 0 דקות
{"weeks":1} שבוע {"minutes":1} דקה
{"weeks":2} שבועיים {"minutes":2} שתי דקות
{"seconds":0} 0 שניות
{"seconds":1} שנייה
{"seconds":2} שתי שניות

可以看到 0 使用复数形式(0 שנים、0 חודשים),1 用单数,2 用双数——与希伯来语名词性数系统完全对应。注意 {"minutes":2} 输出 שתי דקות("两个分钟"),与 formatDistance 中 xMinutes 的 two 值一致。

九、从快照到源码:如何验证与扩展

快照是行为契约,源码是行为实现,两者可以互相印证。想在本仓库中复现快照,可以阅读 format、parse 的实现(pkgs/core/src/format/index.ts、pkgs/core/src/parse/index.ts)以及 locale 类型定义(其中定义了 Locale 接口的六大组成部分:formatDistance、formatRelative、localize、formatLong、match、options)。

希伯来语 locale 的全部构成文件一览(均位于 pkgs/core/src/locale/he/):

  • index.ts:he 对象出口,含 code: "he" 与周选项;
  • _lib/localize/index.ts:月份、星期、季度、纪元、时段词表与带性别规则的序数词;
  • _lib/match/index.ts:各单位的解析正则(月份缩写、星期窄形、时段等);
  • _lib/formatLong/index.ts:P/p 系列长格式模板;
  • _lib/formatDistance/index.ts:距离词表、双数与 addSuffix/特殊日期词;
  • _lib/formatRelative/index.ts:相对日期模板。

十、实用要点速查

  1. 周起始:he 的 weekStartsOn: 0(周日),影响所有本地周 token(wo、eo、Yo)的计算;ISO token(Io、io)不受影响。
  2. 序数词范围:1–10 用希伯来语词且分阴阳性(年/小时/分钟/秒为阴性,其余阳性),超过 10 一律输出数字。
  3. 双数:count = 2 时使用专门的双数词形(שנתיים、יומיים、חודשיים 等),这是实现 formatDistance/formatDuration 时最容易忽略的细节。
  4. 昨天/明天等:formatDistance 与 formatDistanceStrict 在 addSuffix + 1/2 天场景下输出 מחר/מחרתיים/אתמול/שלשום,而不是常规的 "בעוד/לפני + יום"。
  5. 解析边界:带 GMT+0/GMT+00:00 的长时间格式(ppp/pppp/PPPppp/PPPPpppp)无法被 parse 完整回读,快照中标记为 Errored;把年份格式化为希伯来语序数词(如 5 → חמישית)也无法解析回有效日期(Invalid Date)。实际业务中应避免用这类输出做 round-trip 解析。
  6. 时段词:AM/PM 用 לפנה״צ/אחה״צ;弹性时段用 בבוקר、אחר הצהריים、בערב、בלילה(窄形下午为 בצהריים)。
登录后查看全文
date-fns