date-fns 希伯来语(he)Locale 深度解析:format / parse 快照与本地化实现全览
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 缩写),以及如何在项目中正确启用helocale 并排查解析失败场景。
一、快照文档是什么:一份"行为契约"
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];
};
规则清晰:
- 数字大于 10(或小于等于 0)时直接输出数字,这正是快照中月份 11/12 输出
11/12、周 49、日 11/28 输出数字的原因; - 1–10 使用希伯来语序数词,且根据被修饰单位的名词性别二选一:
- 阳性(male):
ראשון、שני、שלישי… 用于月份、季度、日期、星期(如Mo的ראשון、do的ראשון); - 阴性(female):
ראשונה、שנייה、שלישית… 用于年、小时、分钟、秒(如年份 5 的חמישית、分钟 1 的ראשונה、秒 1 的ראשונה)。
- 阳性(male):
- 性别判定写死在
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 שעות |
要点:
- 双数词仍然生效:
שנתיים、יומיים、חודשיים分别对应 2 年、2 天、2 个月; addSuffix: true的 1 天场景复用特殊词:2000-01-02 →מחר,1999-12-30 →שלשום(与formatDistance相同的 xDays 特判,因为formatDistanceStrict内部也走同一formatDistance回调);- 强制单位
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:相对日期模板。
十、实用要点速查
- 周起始:
he的weekStartsOn: 0(周日),影响所有本地周 token(wo、eo、Yo)的计算;ISO token(Io、io)不受影响。 - 序数词范围:1–10 用希伯来语词且分阴阳性(年/小时/分钟/秒为阴性,其余阳性),超过 10 一律输出数字。
- 双数:count = 2 时使用专门的双数词形(
שנתיים、יומיים、חודשיים等),这是实现formatDistance/formatDuration时最容易忽略的细节。 - 昨天/明天等:
formatDistance与formatDistanceStrict在addSuffix+ 1/2 天场景下输出מחר/מחרתיים/אתמול/שלשום,而不是常规的 "בעוד/לפני + יום"。 - 解析边界:带
GMT+0/GMT+00:00的长时间格式(ppp/pppp/PPPppp/PPPPpppp)无法被parse完整回读,快照中标记为Errored;把年份格式化为希伯来语序数词(如 5 →חמישית)也无法解析回有效日期(Invalid Date)。实际业务中应避免用这类输出做 round-trip 解析。 - 时段词:AM/PM 用
לפנה״צ/אחה״צ;弹性时段用בבוקר、אחר הצהריים、בערב、בלילה(窄形下午为בצהריים)。