date-fns 意大利语itlocale 完整指南format/parse 令牌、距离与时长格式化对照速查【免费下载链接】date-fns⏳ Modern JavaScript date utility library ⌛️项目地址: https://gitcode.com/gh_mirrors/da/date-fns本篇指南以 date-fns 仓库中 pkgs/core/src/locale/it/snapshot.md 为骨架系统梳理意大利语 locale 在format、parse、formatDistance、formatDistanceStrict、formatRelative、formatDuration六大 API 下的全部本地化输出。读者可将其作为意大利语日期格式化的“预期行为对照表”用于调试输出、编写测试断言并理解 date-fns 多语言 locale 的数据组织方式与底层实现原理。一、snapshot.md 是什么locale 的“行为快照”在 date-fns 仓库中每个语言 locale 目录下都有一份snapshot.md文件。以意大利语为例其路径为 pkgs/core/src/locale/it/snapshot.md它由构建脚本 pkgs/core/scripts/build/localeSnapshots/index.ts 自动生成脚本遍历所有 locale对format/parse/formatDistance/formatDistanceStrict/formatRelative/formatDuration六个 API 分别渲染固定输入把输出结果以 Markdown 表格的形式写入每个 locale 目录下的snapshot.md。该脚本支持generate默认重新生成快照与test比对磁盘快照与生成结果不一致即报错两种模式并要求在TZutc环境下运行。快照的用途在 pkgs/core/docs/i18nContributionGuide.md 中有明确说明快照即 locale 的测试基准。新增或修改语言后需运行pnpm run locale-snapshots重新生成快照人工审查输出值是否符合该语言的语法习惯再随代码一并提交。快照与实现不一致时test模式会直接失败从机制上防止本地化文案悄悄回归。意大利语 locale 的入口为 pkgs/core/src/locale/it/index.ts其导出对象由五个数据模块拼装而成export const it: Locale { code: it, formatDistance: formatDistance, formatLong: formatLong, formatRelative: formatRelative, localize: localize, match: match, options: { weekStartsOn: 1 /* Monday */, firstWeekContainsDate: 4, }, };其中options.weekStartsOn: 1表示意大利语一周从星期一开始firstWeekContainsDate: 4表示每年的第一周包含当年 1 月 4 日符合 ISO 8601 周历约定。这两个选项直接影响快照中 “Local week-numbering year”“Local week of year”“Local day of week” 等令牌的计算结果。二、format 与 parse令牌到意大利语文本的完整映射快照中format与parse两个 API 共用一张大表左边输入固定的 UTC 时间戳中间是令牌字符串右边分别是format的输出与parse的输出。parse的结果会解析回“该文本所代表的当日起点/时段起点”因此表中parse result常出现整点如T00:00:00.000Z或时段起始如T04:00:00.000Z。2.1 年份与季度标题令牌format 示例说明Calendar year历年yo1987/5序数形式直接输出数字无后缀Local week-numbering yearYo1987/4基于本地周历周一起始、含 1 月 4 日的年份QuarterformattingQo/QQQ/QQQQ/QQQQQ1、T1、1º trimestre、1缩写用T1~T4宽式用1º trimestreQuarterstand-aloneqo/qqq/qqqq/qqqqq同 Q 系列独立上下文如列表使用从源码 pkgs/core/src/locale/it/_lib/localize/index.ts 可看到季度数据const quarterValues { narrow: [1, 2, 3, 4], abbreviated: [T1, T2, T3, T4], wide: [1º trimestre, 2º trimestre, 3º trimestre, 4º trimestre], };注意年份Yo的差异1987-02-11在本地周历中仍属 1987 年但0005-01-01公历 1 月 1 日在意大利周历中属于上一年的第 52 周因此Yo输出为4parse结果回退到0003-12-29。这是weekStartsOn: 1与firstWeekContainsDate: 4联合作用的典型表现。2.2 月份格式化的五种宽度月份是本地化最丰富的部分Mformatting与Lstand-alone各有五种宽度宽度令牌示例1 月/5 月对应数据数字序数Mo/Lo1ordinalNumber缩写MMM/LLLgen/magmonthValues.abbreviated全称MMMM/LLLLgennaio/maggiomonthValues.wide单个字母MMMMM/LLLLLG/MmonthValues.narrow意大利语月份缩写全部取前三个字母gen, feb, mar, apr, mag, giu, lug, ago, set, ott, nov, dic与英文的Jan式缩写形成鲜明对比。窄式单字母存在歧义M同时代表 marzo 和 maggioA代表 aprile 和 agosto快照中MMMMM对 5 月与 3 月都输出M即为此歧义的体现这类歧义由 pkgs/core/src/locale/it/_lib/match/index.ts 中的解析正则处理窄式按首字母匹配、any宽度按ge/f/mar/ap/mag/gi/l/ag/s/o/n/d前缀区分。2.3 星期格式化、ISO 与本地三种体系快照中星期相关令牌分三大类每类五种宽度o/E/i/e/c后缀的数字序数 三/四/五/六字母Day of weekE系列格式化EEE→lunEEEE→lunedìEEEEE→L首字母Lunedì 取LEEEEEE→lun。ISO day of weeki系列io输出 1~7周一1iiii→lunedì。Local day of weeke/c系列意大利语本地周从周一开始因此eo对周一输出1c系列为 stand-alone。一个值得注意的细节EEEEEE与iiiiii/eeeee/cccccc这类最短宽度的 parse 结果是Invalid Date。快照原样记录了该行为——三字母缩写lun同时对应“短格式”与“窄格式”数据见源码dayValues.short与dayValues.abbreviated内容相同解析器无法把lun唯一映射回某个宽度故返回Invalid Date。这是快照作为“行为基准”最有价值的部分它如实记录边界行为而非掩盖。2.4 一天中的时段AM/PM、正午午夜与弹性时段意大利语的时段表达相当讲究快照覆盖三类令牌a/b系列AM/PM 与 正午/午夜宽式均为AM/PM意大利语书面语直接使用拉丁缩写窄式aaaaa/bbbbb输出m.与p.。快照显示m.可解析回当天T00:00:00.000Z而p.的 parse 结果为Invalid Date因为p.与日期的“前一天/后一天”判断存在歧义解析器无法确定基准时刻。B系列Flexible day period弹性时段意大利语按一天四段表达时间点format 输出parse 结果11:13di mattina早上T04:00:00.000Z凌晨 4 点起14:13del pomeriggio下午T12:00:00.000Z正午起19:13di sera晚上T17:00:00.000Z17 点起02:13di notte夜里T00:00:00.000Z零点起其数据源见 localize/index.ts 中的formattingDayPeriodValuesmorning/afternoon/evening/night分别对应di mattina/del pomeriggio/di sera/di notte解析端由 match/index.ts 的matchDayPeriodPatterns正则(di|del) (mattina|pomeriggio|sera|notte)负责回读。2.5 小时、分钟、秒与序数ho/Ho/Ko/ko四种小时制1-12、0-23、0-11、1-24、mo分钟、so秒均为序数令牌意大利语序数输出即普通数字ordinalNumber直接String(number)无º后缀——注意matchOrdinalNumberPattern虽允许º输入但输出不带。快照显示Ho对 23 点输出23ho对 23 点输出1112 小时制Ko对 23 点输出110-11 制ko对 23 点输出231-24 制。2.6 本地化长格式P/p 系列组合formatLong定义了意大利语的长格式模板见 pkgs/core/src/locale/it/_lib/formatLong/index.tsconst dateFormats { full: EEEE d MMMM y, long: d MMMM y, medium: d MMM y, short: dd/MM/y, }; const timeFormats { full: HH:mm:ss zzzz, long: HH:mm:ss z, medium: HH:mm:ss, short: HH:mm, };对应的快照输出P短日期→11/01/1987日/月/年意大利语顺序PP中日期→11 gen 1987PPP长日期→11 gennaio 1987PPPP完整日期→domenica 11 gennaio 1987含星期p→12:13pp→12:13:14ppp/pppp→12:13:14 GMT0/12:13:14 GMT00:00其 parse 结果为Errored带时区缩写/偏移的长时间无法被parse回读快照如实标注Pp→11/01/1987 12:13PPpp→11 gen 1987 12:13:14依此类推PPPppp/PPPPpppp组合同样 Errored日期时间组合模板dateTimeFormats使用{{date}} {{time}}占位符拼接。快照中1453-05-29这一历史日期君士坦丁堡陷落日用于验证任意年份的兼容性PP输出29 mag 1453PPPP输出domenica 29 maggio 1453。三、formatDistance模糊距离的意大利语表达快照假设now 2000-01-01 00:00列出目标日期对应的模糊距离文本。意大利语的量词体系与英文类似但更细致核心规则见 formatDistance/index.ts为count 1时取one形式否则用other模板替换{{count}}。时间差默认输出includeSeconds: trueaddSuffix: true25 秒内meno di un minutomeno di 20 secondi/meno di 10 secondi/meno di 5 secondi/alcuni seconditra meno di un minuto/meno di un minuto fa1 分钟un minutoun minutotra un minuto/un minuto fa45 分钟circa unora同左tra circa unora1 天un giorno同左tra un giorno2 个月2 mesi同左tra 2 mesi1 年circa un anno同左tra circa un anno6 年以上circa 6 anni同左tra circa 6 anni关键细节单复数形态un giorno1 天对{{count}} giorni多天un mese/mesi、un anno/anni同理。约数表达circa大约用于小时、周、月、年级别如circa 6 ore、circa un anno超过 1 年 6 个月则升级为più di un anno超过一年。秒级细分includeSeconds: true时按 5/10/20 秒分档halfAMinute输出alcuni secondi若干秒。方向后缀addSuffix: true时未来加前缀tra“在……之后”过去加后缀fa“……之前”例如tra 5 mesi与5 mesi fa。该逻辑位于源码 formatDistance/index.tsif (options?.addSuffix) { if (options.comparison options.comparison 0) { return tra result; } else { return result fa; } }注意meno di un minuto不到一分钟在未来方向是tra meno di un minuto过去方向是meno di un minuto fa——fa紧跟量词而非minuto。四、formatDistanceStrict精确距离与强制单位formatDistanceStrict不做约化直接给出精确数值配合unit选项可强制以指定单位输出。快照第三列展示了强制小时hour单位时的换算结果日期默认结果addSuffix: true强制hour2001-01-01un annotra un anno8784 ore2000-06-015 mesitra 5 mesi3648 ore2000-01-02un giornotra un giorno24 ore2000-01-01 06:006 oretra 6 ore6 ore1999-12-31 23:59un minutoun minuto fa0 ore1994-01-016 anni6 anni fa52584 ore三个可验证的细节严格量化45 分钟默认输出45 minuti不同于formatDistance的circa unora。单位换算强制小时时1 年 8760 ore平年、2001 年跨闰日故 2000-06-01 至 2001-06-01 为8784 ore闰年 366 天6 年跨 2000 闰年 52584 ore 6×8760 24。快照中的数值与公历闰年规则完全吻合。过去后缀addSuffix: true对过去输出un anno fa、6 anni fa。五、formatRelative相对日期文案formatRelative把“今天/昨天/明天/本周内”等相对关系转成带时间的地道文案now 2000-01-01 00:00日期输出2000-01-1010/01/2000超出周范围回退为短日期P2000-01-05mercoledì prossimo alle 00:002000-01-02domani alle 00:002000-01-01oggi alle 00:001999-12-31ieri alle 00:001999-12-27lunedì alle 00:001999-12-2121/12/1999实现位于 formatRelative/index.ts要点today/tomorrow/yesterday模板为oggi alle p、domani alle p、ieri alle pp是短时间HH:mm。上周/下周模板按星期几分单复数domenica scorsa alle/domenica prossima alle阴/阳性特殊其他星期用lunedì scorso alle、mercoledì prossimo alle等——注意scorso/prossimo的性数随星期名词变化domenica 为阴性。lastWeek/nextWeek通过isSameWeek复用 pkgs/core/src/isSameWeek/index.ts并透传 locale 的weekStartsOn: 1选项判断目标日期是否与基准日同属一周若同周则退化为thisWeek的lunedì alle p形式。超出上述范围的日期回退到other: P即dd/MM/y短日期。六、formatDuration时长对象的本地化formatDuration接收形如{years:2, months:1}的时长对象按单位键逐项输出意大利语文本快照只验证单键情况时长输出{years:1}un anno{years:2}2 anni{months:1}un mese{months:2}2 mesi{weeks:1}una settimana{weeks:2}2 settimane{days:1}un giorno{hours:1}unora{minutes:1}un minuto{seconds:2}2 secondi值得注意的形态变化unora一元音省略una 遇 ora 省略 a、una settimana阴性单数、2 ore、0 anni零值也走复数形式。这些文案同样定义在 formatDistance/index.ts 的量词表中formatDuration与formatDistance共用同一套单复数数据保证两类 API 的措辞一致。七、如何验证与复现快照的生成与检查快照本身既是文档又是测试基准若需在本地复现或更新意大利语快照在仓库根目录安装依赖后以 UTC 时区运行快照生成命令该脚本强制要求TZutc见 localeSnapshots/index.tsTZutc pnpm run locale-snapshots生成结果会覆盖写入pkgs/core/src/locale/it/snapshot.md。若要检查磁盘上的快照与当前实现是否一致CI 校验模式TZutc pnpm run locale-snapshots test不一致时脚本会抛出The snapshot on the disk doesnt match the generated snapshot...错误提示重新生成并提交。在应用层验证意大利语输出可直接引入 locale 并与format/formatDistance组合使用示例import { format, formatDistance, formatRelative, formatDuration } from date-fns; import { it } from date-fns/locale; const date new Date(1987-02-11T12:13:14.000Z); format(date, PPPP, { locale: it }); // mercoledì 11 febbraio 1987 format(date, PPpp, { locale: it }); // 11 feb 1987 12:13:14 formatDistance(new Date(2000-06-01T00:00:00.000Z), new Date(2000-01-01T00:00:00.000Z), { locale: it, addSuffix: true, }); // tra 5 mesi formatRelative(new Date(2000-01-02T00:00:00.000Z), new Date(2000-01-01T00:00:00.000Z), { locale: it, }); // domani alle 00:00 formatDuration({ years: 1, months: 2, days: 3 }, { locale: it }); // un anno 2 mesi 3 giorni八、小结意大利语 snapshot 展示了一个高质量 locale 的全部要素五种宽度的月份/星期词汇、1º trimestre式季度表达、di mattina/del pomeriggio/di sera/di notte弹性时段、tra … / … fa方向后缀、circa/più di模糊量词以及scorso/prossimo的性数变化。同时快照如实记录了若干边界行为最短宽度星期的Invalid Date、带时区长度的 Errored这些正是调试parse回读时最容易被忽视的坑。对开发者的实用建议需要“预期值”时直接查阅本快照对应语言的文件如意大利语为 pkgs/core/src/locale/it/snapshot.md无需运行代码即可断言输出修改任何 locale 实现后务必重新生成并审查快照再提交到版本库若发现format能输出但parse返回Invalid Date或 Errored请先对照快照确认是否为该语言已知的固有行为再决定是否值得为解析器补充歧义消解规则。关联参考文件locale 入口、本地化数据、匹配/解析正则、长格式模板、相对格式实现、距离量词表、快照生成脚本、i18n 贡献指南。【免费下载链接】date-fns⏳ Modern JavaScript date utility library ⌛️项目地址: https://gitcode.com/gh_mirrors/da/date-fns创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考