date-fns 希腊语(el)Locale 全解析:format / parse / formatDistance 快照与源码实现

原创2026-09-18 13:53:111,733 阅读
文章标签:国际化跨平台前端

date-fns 希腊语(el)Locale 全解析:format / parse / formatDistance 快照与源码实现

导读

本文以 date-fns 仓库中希腊语(el)locale 的测试快照文档 snapshot.md 为主体,完整梳理希腊语环境下 format、parse、formatDistance、formatDistanceStrict、formatRelative、formatDuration 六大能力的实际输出,并结合 locale/el 的源码与 locale/types.ts 的类型契约,解释希腊语序数后缀(-ος / -η / -ο)、复数形式、时段词(π.μ./μ.μ./πρωί/βράδυ)以及解析(match)正则背后的实现逻辑。读完本文,你将掌握希腊语 locale 的完整行为表、底层数据组织方式,以及如何在项目中引入并验证 el locale。

一、快照文档是什么:locale 行为的"参考答案"

snapshot.md 是希腊语 locale 的行为快照,它记录了在固定输入下所有格式化函数的预期输出。它不只是一份文档,更是测试与回归的基准:任何对希腊语本地化数据的修改,都必须让这些表格中的结果保持一致(或同步更新快照)。快照分为五个部分:

  • format 与 parse:覆盖年份、季度、月份、星期、时段、小时、分钟、秒、长格式日期/时间、日期时间组合等全部 token;
  • formatDistance:相对时间距离(含 includeSeconds 与 addSuffix 两种选项);
  • formatDistanceStrict:严格距离(支持强制指定单位);
  • formatRelative:相对日期(今天/明天/昨天/本周等);
  • formatDuration:结构化时长对象的本地化输出。

快照中的所有结果都对应 el locale 源码 中 formatDistance、formatLong、formatRelative、localize、match 五个模块的联合输出,是验证实现正确性的直接证据。

二、引入希腊语 locale

希腊语 locale 的代码为 el(ISO 639-2 代码 ell),作者信息与导出定义见 el/index.ts。它通过 locale/index.ts 的 export * from "./el/index.ts" 统一对外导出。

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

// 格式化
format(new Date(1987, 0, 11, 12, 13, 14), "PPPP", { locale: el });
// => "Κυριακή, 11 Ιανουαρίου 1987"

// 相对距离
formatDistance(new Date(2000, 5, 1), new Date(2000, 0, 1), { locale: el });
// => "5 μήνες"

// 解析
parse("11 Φεβ 1987", "d MMM y", new Date(), { locale: el });

locale 对象还携带两个全局选项(见 el/index.ts):

  • weekStartsOn: 1:一周从星期一开始;
  • firstWeekContainsDate: 4:包含当年 1 月 4 日的周算作第一周(ISO 周规则)。

这两个选项直接影响"Local week-numbering year"(Yo)、"Local week of year"(wo)、"Local day of week"(eo/co)等 token 的计算结果。

三、format 与 parse:完整 token 行为表

快照的第一部分是核心,它同时给出 format 输出与 parse 回读结果。parse 结果列为"该格式化字符串能被 parse 回原始日期"的能力证明,两者组合验证了 format 与 match 的对称性。以下按类别解读关键行为。

3.1 序数年份、季度与月份(希腊语后缀系统)

希腊语序数按语法性别变化后缀,实现见 localize/index.ts 的 ordinalNumber:

单位 后缀 示例
年(yo/Yo)、月(Mo/Lo) ος 1987ος、5ος、1ος
周(wo/Io)、日(do/Do/eo/io/co)、小时(ho/Ho/Ko/ko) η 1η、42η、11η
季度(Qo/qo)、分钟(mo)、秒(so) ο 1ο、55ο

快照中的典型结果:

Token 输入 format 结果
yo 1987-02-11 1987ος
Yo(本地周年) 0005-01-01 4ος(按周一起始、1 月 4 日规则回退到上一年)
Qo 2019-04-01 2ο
QQQ 2019-04-01 Τ2
QQQQ 2019-04-01 2ο τρίμηνο
Mo 2019-02-11 2ος
MMMM(属格,formatting 上下文) 2019-05-10 Μαΐου
LLLL(主格,stand-alone 上下文) 2019-05-10 Μάιος

注意 M 系(formatting)与 L 系(stand-alone)月份在宽格式下不同:MMMM 输出属格 Ιανουαρίου("1 月的"),而 LLLL 输出主格 Ιανουάριος。这一差异在 localize/index.ts 中通过 formattingMonthValues 与 monthValues 两套数据实现。

3.2 窄格式的"歧义回退"现象

MMMMM(窄格式月份)输出单个首字母,如 Ι、Φ、Μ、Α。快照中 parse 结果列出现一个特殊现象:当窄字符有歧义时,parse 回读的是第一个匹配项,例如:

  • Μ(2019-05,五月)解析回 2019-03-01(三月,因为 Μάρτιος 与 Μάιος 都以 Μ 开头);
  • Ι(2019-06,六月)解析回 2019-01-01(一月,Ιανουάριος/Ιούνιος/Ιούλιος 都以 Ι 开头);
  • Α(2019-08)解析回 2019-04-01(四月,Απρίλιος/Αύγουστος 都以 Α 开头)。

这正是 match/index.ts 中 parseMonthPatterns 的窄格式数组 [/^ι/i, /^φ/i, /^μ/i, /^α/i, ...] 顺序匹配的结果:每个正则命中"第一个以该字母开头的月份"。这是希腊语窄格式的固有限制,快照如实记录了它——使用窄格式 token 时,parse 的回读可能不唯一。

3.3 星期:格式化与 stand-alone、ISO 与本地

快照覆盖了星期相关的全部 token 家族:

  • E/EE/EEE(格式化,缩写):Δευ、Παρ;
  • EEEE(格式化,完整):Δευτέρα、Παρασκευή;
  • EEEEE(格式化,窄):Δ、Π(此时 Π 同时代表 Πέμπτη 和 Παρασκευή,parse 回读为 2019-02-14 周四——第一个以 Π 开头的匹配,与月份窄格式同理);
  • EEEEEE(格式化,短):Δε、Πα;
  • i 系(ISO 星期,周一到周日为 1–7):iii→Δευ,io 序数→1η/5η;
  • e 系(本地星期,同样周一起始):缩写与完整输出和 i 系一致;
  • c 系(stand-alone 星期):输出与 e 系一致(希腊语不区分)。

这些值来自 localize/index.ts 的 dayValues(narrow/short/abbreviated/wide 四档),匹配正则见 match/index.ts。

3.4 时段(day period):a / b / B 三组 token

快照区分了三组时段 token,全部数据在 localize/index.ts 的 dayPeriodValues:

  • a(AM/PM 系):π.μ. / μ.μ.,其中 aaaaa 窄格式为 πμ / μμ;
  • b(AM/PM/noon/midnight 系):希腊语实现中与 a 输出一致;
  • B(弹性时段,flexible day period):按时间段输出 πρωί(凌晨/上午,parse 基准 04:00)、απόγευμα(下午,12:00)、βράδυ(傍晚,17:00)、νύχτα(夜间,00:00)。

快照的 parse 结果列给出了各时段的"代表时刻":πρωί→04:00、απόγευμα→12:00、βράδυ→17:00、νύχτα→00:00。匹配正则见 match/index.ts。

3.5 长格式日期时间(P / p 系)与已知限制

formatLong 在 formatLong/index.ts 中定义:

const dateFormats = {
  full: "EEEE, d MMMM y",
  long: "d MMMM y",
  medium: "d MMM y",
  short: "d/M/yy",
};
const timeFormats = {
  full: "h:mm:ss a zzzz",
  long: "h:mm:ss a z",
  medium: "h:mm:ss a",
  short: "h:mm a",
};
const dateTimeFormats = {
  full: "{{date}} - {{time}}",
  long: "{{date}} - {{time}}",
  medium: "{{date}}, {{time}}",
  short: "{{date}}, {{time}}",
};

快照中 P→11/1/87、PP→11 Ιαν 1987、PPP→11 Ιανουαρίου 1987、PPPP→Κυριακή, 11 Ιανουαρίου 1987;p→12:13 μ.μ.、pp→12:13:14 μ.μ.。

重要已知限制:带时区的 ppp、pppp 以及含时区的组合 PPPppp、PPPPpppp 在快照中 parse 列为 Errored——即 parse 目前无法回读这些含时区(z/zzzz)的字符串。这是快照明确记录的行为边界,使用时应避免用 parse 回读带时区的长格式。

组合格式 Pp→11/1/87, 12:13 μ.μ.、PPpp→11 Ιαν 1987, 12:13:14 μ.μ.、PPPppp→11 Ιανουαρίου 1987 - 12:13:14 μ.μ. GMT+0(full/long 用 - 连接,medium/short 用 , 连接)。

四、formatDistance:相对时间的自然语言表达

快照假设"当前时间"为 2000 年 1 月 1 日 00:00,逐行给出不同历史/未来日期的输出。希腊语的距离文案定义在 formatDistance/index.ts,每个 token 分 one(单数)与 other(复数,用 {{count}} 占位):

Token 单数 复数
xSeconds 1 δευτερόλεπτο {{count}} δευτερόλεπτα
halfAMinute μισό λεπτό —
xMinutes 1 λεπτό {{count}} λεπτά
aboutXHours περίπου 1 ώρα περίπου {{count}} ώρες
xDays 1 ημέρα {{count}} ημέρες
xMonths 1 μήνας {{count}} μήνες
xYears 1 χρόνο {{count}} χρόνια
overXYears πάνω από 1 χρόνο πάνω από {{count}} χρόνια
lessThanXSeconds λιγότερο από ένα δευτερόλεπτο λιγότερο από {{count}} δευτερόλεπτα

addSuffix 的拼接逻辑见 formatDistance/index.ts:未来加前缀 σε ("在……之后"),过去加后缀 πριν("……之前")。快照示例:

  • 2000-01-02(未来 1 天)→ 1 ημέρα,带 addSuffix → σε 1 ημέρα;
  • 1999-12-30(过去 2 天)→ 2 ημέρες,带 addSuffix → 2 ημέρες πριν;
  • 2000-01-01T00:00:25 → 默认 λιγότερο από ένα λεπτό,includeSeconds: true 时输出 μισό λεπτό;
  • 2000-01-01T00:00:00(同一时刻)→ 带后缀输出 λιγότερο από ένα λεπτό πριν(comparison 为 0 时走 πριν 分支)。

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

formatDistanceStrict 不做"约/多于/少于"的近似,直接给出精确单位和数值,并支持 unit 选项强制指定单位(快照最后一列强制为 hour)。快照示例:

  • 2006-01-01 → 6 χρόνια,强制小时 → 52608 ώρες;
  • 2000-01-01T00:45 → 45 λεπτά,强制小时 → 1 ώρα(四舍五入);
  • 2000-01-01T00:15 → 15 λεπτά,强制小时 → 0 ώρες;
  • 2000-01-01T00:00 → 0 δευτερόλεπτα,带后缀 → 0 δευτερόλεπτα πριν。

注意该函数同样复用了 formatDistance/index.ts 中的希腊语单复数文案(如 xYears 的 1 χρόνο / {{count}} χρόνια),因此 1998-06-01(18 个月前)输出 2 χρόνια,而 1998-12-01(约 13 个月前)输出 1 χρόνο——严格模式下按完整月数取整。

六、formatRelative:上下文相关相对日期

formatRelative 根据目标日期与基准日期的关系选择模板,模板定义在 formatRelative/index.ts:

const formatRelativeLocale = {
  lastWeek: (date) =>
    date.getDay() === 6
      ? "'το προηγούμενο' eeee 'στις' p"   // 周六用中性冠词
      : "'την προηγούμενη' eeee 'στις' p",
  yesterday: "'χθες στις' p",
  today: "'σήμερα στις' p",
  tomorrow: "'αύριο στις' p",
  nextWeek: "eeee 'στις' p",
  other: "P",
};

一个值得注意的细节:上周六使用中性形式 το προηγούμενο Σάββατο,而其他星期用阴性形式 την προηγούμενη Δευτέρα——因为希腊语中"Σάββατο"(周六)是中性名词。快照对应结果:

  • 2000-01-01(当天)→ σήμερα στις 12:00 π.μ.;
  • 1999-12-31(昨天)→ χθες στις 12:00 π.μ.;
  • 2000-01-02(明天)→ αύριο στις 12:00 π.μ.;
  • 1999-12-27(上周一)→ την προηγούμενη Δευτέρα στις 12:00 π.μ.;
  • 超出上一周范围(1999-12-21)→ 回退到短日期 21/12/99(P 格式);
  • 2000-01-10(超出下一周)→ 10/1/00。

七、formatDuration:结构化时长对象的本地化

formatDuration 接收 Duration 对象(如 { years: 2, months: 1 }),按希腊语单复数输出。快照覆盖每种单位的 0/1/2 三个取值:

Duration 结果
{"years":0} 0 χρόνια
{"years":1} 1 χρόνο
{"years":2} 2 χρόνια
{"months":1} 1 μήνας
{"weeks":1} 1 εβδομάδα
{"days":1} 1 ημέρα
{"hours":1} 1 ώρα
{"minutes":1} 1 λεπτό
{"seconds":1} 1 δευτερόλεπτο

复数形式规律:μήνας→μήνες、εβδομάδα→εβδομάδες、ημέρα→ημέρες、ώρα→ώρες、λεπτό→λεπτά、χρόνο→χρόνια。这些文案同样复用 formatDistance/index.ts 中定义的 token(xYears、xMonths、xWeeks、xDays、xHours、xMinutes、xSeconds 的 one/other 形式),保证了 formatDistance、formatDistanceStrict、formatDuration 三个函数使用完全一致的词汇。

八、底层机制:Localize 与 Match 的分工

快照中 format 与 parse 的对称性,来自 locale 的 localize(输出)与 match(输入)两套数据。类型契约见 locale/types.ts:

  • Localize(types.ts)提供 ordinalNumber、era、quarter、month、day、dayPeriod,配合 width(narrow/short/abbreviated/wide)与 context(formatting/standalone)两个选项;
  • Match(types.ts)提供对应的 matchXxx 函数,返回 { value, rest } 结构(types.ts),即"匹配到的值 + 剩余未消费字符串",供 parse 逐步消费。

希腊语实现中值得注意的三点:

  1. 大小写宽容:所有 match 正则都带 i 标志(如 matchOrdinalNumberPattern = /^(\d+)(ος|η|ο)?/i),因此 parse("11 ΦΕΒ 1987", ...) 也能工作;
  2. 变音与拼写宽容:月份正则如 μ<a href="https://link.gitcode.com/i/df93daa496c71b921c08aa0610d82321" target="_blank">άα]ρ、μ[άα][ιΐ]、ιο[ύυ]ν 同时接受带/不带重音或不同重音变体(见 [match/index.ts),这对用户输入的健壮性至关重要;
  3. 宽格式正则的语法变体:matchEraPatterns.wide 同时接受 προ Χριστού、πριν από την Κοινή Χρονολογία 等多种写法(match/index.ts)。

九、如何验证与使用这些行为

快照本身就是验证工具:将 snapshot.md 中的每个 format 结果与 parse 结果与 format / parse 的实际输出比对,即可确认 locale 数据未被破坏。结合源码可以做更细粒度的验证:

import { el } from "date-fns/locale";
import { format, parse, formatDistance, formatDuration } from "date-fns";

// 序数后缀按单位变化
format(new Date(2019, 3, 1), "Qo", { locale: el });       // "2ο"
format(new Date(2019, 1, 11), "do MMMM", { locale: el }); // "11η Φεβρουαρίου"
format(new Date(2019, 1, 11), "Ho", { locale: el });      // "11η"

// 窄格式歧义(MMMMM 五月 → 解析回三月)
format(new Date(2019, 4, 10), "MMMMM", { locale: el });   // "Μ"
parse("Μ", "MMMMM", new Date(), { locale: el });           // 2019-03-01

// 弹性时段
format(new Date(2019, 1, 11, 19, 13), "B", { locale: el }); // "βράδυ"

// 距离与时长
formatDistance(new Date(2000, 5, 1), new Date(2000, 0, 1), { locale: el });
// "5 μήνες"
formatDuration({ years: 2, months: 3 }, { locale: el });
// "2 χρόνια 3 μήνες"

需要注意的是:ppp/pppp 及含时区的长格式组合在 parse 回读时必然失败(快照中标记为 Errored),这是当前希腊语 locale 的行为边界,设计业务逻辑时应避免依赖 parse 回读带时区字符串。

十、小结:一张快照看懂一个 locale

希腊语 locale 的 snapshot 文档揭示了一个现代日期库本地化实现所需的完整维度:序数后缀随语法性别变化(-ος/-η/-ο)、月份区分主格/属格两套宽格式、窄格式天然存在解析歧义、时段系统支持弹性分段(πρωί/απόγευμα/βράδυ/νύχτα)、相对距离带 σε … / … πριν 前后缀、formatRelative 甚至要考虑"Σάββατο"的中性语法性别。这些行为全部有 el/_lib 下的源码与正则作为依据,快照则保证它们在后续迭代中保持稳定。对想贡献新 locale 或深入理解 date-fns 本地化机制的开发者而言,从一份 snapshot.md 加对应的 _lib 目录读起,是最直接的路径。

登录后查看全文
date-fns