date-fns 韩语（ko）语言包完整指南：format / parse / formatDistance 等全部快照行为详解

date-fns 韩语ko语言包完整指南format / parse / formatDistance 等全部快照行为详解【免费下载链接】date-fns⏳ Modern JavaScript date utility library ⌛️项目地址: https://gitcode.com/gh_mirrors/da/date-fns本指南以 date-fns 仓库中 韩语 locale 快照文档 为核心骨架完整解析韩语ko语言包在format、parse、formatDistance、formatDistanceStrict、formatRelative、formatDuration六大 API 下的全部输出行为与规则并结合 韩语 locale 实现源码 与快照生成脚本源码说明每个输出结果背后的实现原理、序数词规则、时段时间段映射以及如何自己动手复现验证。读完本文你将能够准确预判韩语 locale 在各种日期时间 token 下的格式输出与解析回推结果理解快照中每个字段如 1번째、약 6년、오후的来源掌握快照文档的生成与校验机制并学会在业务代码中正确使用ko语言包。快照文档是什么ko locale 的行为基准snapshot.md 不是手写文档而是 date-fns 构建流程中由脚本自动生成的行为快照它对韩语 locale 的全部关键 API 输入一组固定的测试日期与 token把真实运行结果以 Markdown 表格形式固化下来。生成逻辑位于 localeSnapshots 脚本脚本枚举仓库中所有 locale通过 listLocales.ts逐个读取src/locale/code/index.ts导出对象然后依次调用renderFormatParse、renderFormatDistance、renderFormatDistanceStrict、renderFormatRelative、renderFormatDuration五个渲染函数拼装后写入各 locale 目录下的snapshot.md。脚本对运行环境有硬性要求——TZ必须为utc见 index.ts#L24-L25因为快照中的日期字符串全部以Z结尾的 UTC ISO 格式呈现任何非 UTC 时区都会导致输出偏差。脚本支持两种模式默认generate模式把生成结果写回磁盘test模式则比较磁盘上的快照与重新生成的结果不一致即报错并提示运行pnpm run locale-snapshots。这意味着快照文档本身就是 ko locale 的回归测试基准任何对韩语翻译或格式模板的改动如果改变了输出都会在test模式下被发现。快照中每一行的parse结果同样由脚本实时计算renderFormatParse/index.ts先用format(date, token, { locale })得到格式串再调用parse(formatResult, token, date, { locale })尝试回推回推失败记作Errored。因此快照中format 结果与parse 结果天然构成一对可逆性验证。快速上手如何在项目中使用韩语 locale在代码中引入韩语语言包即可让format、parse、formatDistance等函数输出韩文import { format, parse, formatDistance } from date-fns; import { ko } from date-fns/locale; format(new Date(2019, 0, 11, 12, 13, 14), MMMM do, { locale: ko }); // 1월 11일 parse(1월 11일, MMMM do, new Date(2019, 0, 1), { locale: ko }); // 2019-01-11T00:00:00.000Z 附近的 Date formatDistance(new Date(2000, 5, 1), new Date(2000, 0, 1), { locale: ko }); // 5개월ko对象定义在 pkgs/core/src/locale/ko/index.ts包含五个必选字段与一个可选配置字段作用实现文件code语言代码koindex.ts#L18formatDistanceformatDistance/formatDistanceStrict使用的距离本地化函数_lib/formatDistance/index.tsformatLongformat使用的长格式模板P/PP/PPP/PPPP、p/pp等_lib/formatLong/index.tsformatRelativeformatRelative使用的相对时间模板_lib/formatRelative/index.tslocalizeformat使用的各类值序数、季度、月份、星期、时段本地化_lib/localize/index.tsmatchparse使用的各类韩文文本匹配/解析规则_lib/match/index.tsoptionsweekStartsOn: 0周日为一周第一天、firstWeekContainsDate: 1index.ts#L24-L27options两个值决定周相关计算weekStartsOn: 0表示韩语语境下每周从周日开始直接影响startOfWeek、getWeek等函数firstWeekContainsDate: 1表示每年的第一周是包含 1 月 1 日的那一周。这正是快照中Local week-numbering yearYo与Local week of yearwo的 parse 结果会回退到上一年 12 月末的原因详见下文。format与parse全部 token 输出速查表快照的第一大节覆盖format/parse的 40 余种 token。下面按类别整理format 列即韩语输出parse 列是韩语文本回推得到的日期UTC。年份Calendar yearyo/ Local week-numbering yearYoToken日期formatparseyo1987-02-111987번째1987-01-01yo0005-01-015번째0005-01-01Yo1987-02-111987번째1986-12-28Yo0005-01-015번째0004-12-26韩语序数后缀统一为번째实现见 localize 的 ordinalNumber。注意Yo的 parse 结果比输入日期更早因为周从周日开始且第一周包含 1 月 1 日1987 年 2 月 11 日所在周的第一天是 1986-12-28周日这正是该周编号年的起点。季度Quarter formattingQ/ stand-aloneqTokenformat含义Qo/qo1번째、2번째…序数季度QQQ/qqqQ1、Q2…缩写季度QQQQ/qqqq1분기、2분기…完整季度wideQQQQQ/qqqqq1、2…窄格式映射数据来自 localize 的 quarterValuesnarrow: [1,2,3,4]、abbreviated: [Q1,Q2,Q3,Q4]、wide: [1분기,2분기,3분기,4분기]。格式化与独立两种宽度输出完全一致。月份Month formattingM/ stand-aloneLTokenformat 示例1 月/12 月说明Mo/Lo1번째 / 12번째序数月份MMM/LLL1월 / 12월缩写MMMM/LLLL1월 / 12월完整wideMMMMM/LLLLL1 / 12窄格式韩语月份写作N월abbreviated 与 wide 相同见 monthValues。parse 侧正则见 match 的 matchMonthPatterns窄格式^(1[012]|[123456789])、缩写与完整格式^(1[012]|[123456789])월。星期Day of weekE / i / e / c 四族韩语星期名称实现于 dayValues일/월/화/수/목/금/토为窄/短/缩写일요일…토요일为完整。快照中具体映射Token 族格式2019-02-11周一2019-02-15周五E/EE/EEE/EEEEE/EEEEEE缩写/窄월금EEEE完整월요일금요일iISOeo/co本地序数序数1번째/2번째5번째/6번째iii/iiii/iiiii/iiiiiiISO 缩写同 E 族월 / 월요일금 / 금요일eee…eeeee本地缩写同 E 族월금ccc…ccccc独立缩写同 E 族월금io为 ISO 星期序数周一到周日 1–72019-02-11 是周一故为 1번째eo/co为本地序数周日开始周一排第 2、周五排第 6。parse 侧星期匹配见 matchDayPatterns。上下午与时段AM/PMa、bFlexible day periodB韩语时段词全部定义于 dayPeriodValues / formattingDayPeriodValues词韩语说明am / pm오전 / 오후上下午midnight / noon자정 / 정오午夜 / 正午morning / afternoon / evening / night아침 / 오후 / 저녁 / 밤弹性时段快照中的关键行为Token时间formatparse 结果aAM/PM11:13 / 14:13 / 02:13오전 / 오후 / 오전00:00 / 12:00 / 00:00bAM/PM/noon/midnight同上同a同aBflexible11:13아침04:00B14:13오후12:00B19:13저녁17:00B02:13밤00:00a/b的 parse 会把 오전 归一到当日 00:00、오후 归一到 12:00B的 parse 则按时段起点回推아침→04:00、오후→12:00、저녁→17:00、밤→00:00。这些解析锚点由 match 的 parseDayPeriodPatterns 与 date-fns 时段框架共同决定。注意快照中b的 5 个宽度b/bb/bbb/bbbb/bbbbb输出相同因为韩语在 narrow/abbreviated/wide 三档都使用同一组词。小时 / 分钟 / 秒Token含义format 示例hoHour [1-12]11번째、23:13 时仍为 11번째HoHour [0-23]11번째、23번째KoHour [0-11]11번째23:13 时也输出 11번째koHour [1-24]11번째、23번째moMinute1 / 55无后缀soSecond1 / 55无后缀序数规则的精髓在 ordinalNumber 的 switchminute与second直接返回纯数字date返回N일其余年、月、季度、星期、小时、日序一律返回N번째。这就是为什么分钟秒数是1/55而小时是11번째。date分支对应下文do日序。日序与周序Token日期formatparsedoDay of month2 月 1/11/28 日1일 / 11일 / 28일同日do MMMM同上1일 2월 / 11일 2월 / 28일 2월同日DoDay of year2019-02-1142번째2019-02-11Do2019-12-31365번째2019-12-31woLocal week2019-01-011번째2018-12-30wo2019-12-0149번째2019-12-01IoISO week2019-01-011번째2018-12-31Io2019-12-0148번째2019-11-25do的 parse 回推与输入日期一致wo的 parse 回退到该周第一天周日故 2019 年第 1 周回推为 2018-12-30Io按 ISO 周规则回推到周一2018-12-31 / 2019-11-25。周序数在韩语中也使用번째与N일形成对比二者都源自同一个 ordinalNumber。长日期 / 长时间 / 日期时间组合P 族与 p 族长格式模板定义于 formatLong/index.tsconst dateFormats { full: y년 M월 d일 EEEE, // PPPP long: y년 M월 d일, // PPP medium: y.MM.dd, // PP short: y.MM.dd, // P }; const timeFormats { full: a H시 mm분 ss초 zzzz, // pppp long: a H:mm:ss z, // ppp medium: HH:mm:ss, // pp short: HH:mm, // p };快照中的实际输出Token示例输出P/PP1987.01.11短格式含 1453-05-29 → 1453.05.29PPP1987년 1월 11일PPPP1987년 1월 11일 일요일含星期p12:13HH:mmpp12:13:14HH:mm:ssppp오후 12:13:14 GMT0pppp오후 12시 13분 14초 GMT00:00Pp1987.01.11 12:13PPpp1987.01.11 12:13:14PPPppp/PPPPpppp完整日期 完整时间含 오후 与 GMT 偏移一个值得注意的快照细节ppp、pppp、PPPppp、PPPPpppp这几行的parse 结果全部为Errored。原因在于时间模板中的z/zzzz时区名 GMT0 / GMT00:00在韩语match中没有对应的解析规则——match/index.ts 只实现了 ordinalNumber、era、quarter、month、day、dayPeriod 六类匹配器不含时区解析因此parse无法回推带时区名的完整时间格式。这是快照自动生成机制如实反映的实现边界而非文档错误。另外注意ppp行오후 23:59:59 GMT0这类输出a H:mm:ss z模板中a在 23 点输出 오후下午时间本身仍按 24 小时制H显示这是模板拼接的固有表现。formatDistance相对时间距离输出快照第二节固定now 2000-01-01T00:00:00Z考察formatDistance(date, baseDate, { locale: ko })。实现位于 formatDistance/index.ts其核心是{{count}}占位符模板与后缀逻辑if (options?.addSuffix) { if (options.comparison options.comparison 0) { return result 후; // 未来 } else { return result 전; // 过去 } }关键输出规律节选完整见 snapshot.md基准日期ResultincludeSeconds: trueaddSuffix: true2006-01-01약 6년약 6년약 6년 후2001-06-011년 이상1년 이상1년 이상 후2000-06-015개월5개월5개월 후2000-01-1514일14일14일 후2000-01-01T00:00:251분 미만30초1분 미만 후2000-01-01T00:00:151분 미만20초 미만1분 미만 후2000-01-01T00:00:051분 미만10초 미만1분 미만 후2000-01-01T00:00:001분 미만5초 미만1분 미만 전1999-12-31T23:59:351분 미만30초1분 미만 전可归纳出韩语 distance 的翻译策略秒级lessThanXSeconds→{{count}}초 미만、xSeconds→{{count}}초、halfAMinute→ 固定串30초分级近似aboutXHours→약 {{count}}시간、aboutXMonths→약 {{count}}개월、aboutXYears→약 {{count}}년超过整年overXYears→{{count}}년 이상后缀未来加후、过去加전且comparison 0才视为未来类型定义见 locale/types.ts。includeSeconds: true时 15–25 秒区间输出20초 미만/30초等更细粒度结果addSuffix: true时后缀후/전总是追加在完整短语末尾。formatDistanceStrict精确距离与强制单位第三节的基准同样为 2000-01-01T00:00:00Z但输出不再做약/이상近似而是精确到所选单位并展示unit: hour强制小时的换算效果日期ResultaddSuffix: true强制 hour 单位2006-01-016년6년 후52608시간2001-06-011년1년 후12408시간2000-06-015개월5개월 후3648시간2000-01-1514일14일 후336시간2000-01-01T00:00:2525초25초 후0시간1999-12-31T23:59:3525초25초 전0시간1999-12-31T23:00:001시간1시간 전1시간1994-01-016년6년 전52584시간要点formatDistanceStrict默认按最接近的自然单位输出如 45 分 45초 附近输出 45분00:45 与 00:30 均输出 45분/30분当传入unit: hour时一切换算为整小时向下取整如 25 秒 → 0시간。所有单位词干与formatDistance共用同一份 formatDistanceLocale只是不再使用약/이상修饰。formatRelative相对日期模板第四节基准为 2000-01-01T00:00:00Z输出由 formatRelative/index.ts 的模板决定const formatRelativeLocale { lastWeek: 지난 eeee p, yesterday: 어제 p, today: 오늘 p, tomorrow: 내일 p, nextWeek: 다음 eeee p, other: P, };日期Result2000-01-102000.01.10超过一周回落到P短日期2000-01-05다음 수요일 00:00下周三2000-01-02내일 00:002000-01-01오늘 00:001999-12-31어제 00:001999-12-27지난 월요일 00:00上周一1999-12-211999.12.21超过一周模板中的p使用formatLong的短时间格式HH:mm故为 00:00eeee输出完整星期名수요일/월요일지난/다음/어제/오늘/내일为韩语相对词P即短日期y.MM.dd。超过一周的日期回落到普通日期格式。formatDurationDuration 对象格式化最后一节覆盖formatDuration对 Duration 对象的输出所有单位词干同样复用 formatDistanceLocaleDurationResult{years:0}0년{years:2}2년{months:2}2개월{weeks:2}2주{days:2}2일{hours:2}2시간{minutes:2}2분{seconds:2}2초韩语没有英语的复数形态变化1주与2주等单位词完全一致仅数字变化因此快照中0/1/2各值均可直接推导。快照背后的实现原理与复现验证序数后缀规则总结从 ordinalNumber 可以提炼韩语序数三条规则它解释了快照中几乎所有번째/일/纯数字的分布minute、second→ 纯数字1、55date→N일1일、28일其余单位year、quarter、month、week、day-of-week、day-of-year、hour→N번째1987번째、5개월属 distance 另行处理11번째、42번째等。localize的其余部分用buildLocalizeFn统一构建pkgs/core/src/_lib/buildLocalizeFn/index.ts通过values、defaultWidth、argumentCallback、formattingValues等参数把上面看到的各 values 对象组装成format可直接调用的本地化函数。match 层的解析边界parse能否回推取决于 match/index.ts 是否覆盖对应 tokenordinalNumber用/^(\d)(일|번째)?/i匹配数字与可选后缀dayPeriod支持 오전/오후/자정/정오/아침/저녁/밤quarter支持Q1–Q4与N분기month/day支持N월与N요일。凡不在此列的如z/zzzz时区名parse 即返回Errored——这正是快照中 ppp/pppp 行全部 Errored 的根因。手动复现快照快照由 localeSnapshots 脚本 生成仓库包内提供了对应脚本命令。复现或校验韩语快照# 在 pkgs/core 包目录下 TZutc pnpm run locale-snapshots # 重新生成全部 locale 快照含 ko/snapshot.md TZutc pnpm run locale-snapshots test # 校验磁盘快照与重新生成结果一致也可直接用 node 手动验证某个 token// 伪代码TZutc 环境下 import { format } from date-fns; import { ko } from date-fns/locale; console.log(format(new Date(2019-02-11T12:13:14.015Z), EEEE, { locale: ko })); // 월요일test模式的意义在于任何对 ko locale 翻译文本或模板的改动只要改变输出就会让快照与生成结果不一致而构建失败——快照因此成为韩语语言包的行为契约。结语ko 快照文档 以 5 组表格完整刻画了韩语语言包在 format/parse、formatDistance、formatDistanceStrict、formatRelative、formatDuration 五大 API 下的全部行为。结合 localize、match、formatLong、formatRelative、formatDistance 五份源码可以清晰还原每个输出的来源序数后缀由ordinalNumber按单位分发时段词由dayPeriodValues提供长格式由formatLong模板拼接时区时间无法解析则是match未实现时区规则的如实反映。若需为韩语场景开发或校验本地化行为直接以本快照为基准、以pnpm run locale-snapshots test为回归手段即可。附ko locale 由 Hong Chulju、Lee Seoyoen、Taiki IKeda 三位贡献者维护见 index.ts 的 JSDoc 标注。【免费下载链接】date-fns⏳ Modern JavaScript date utility library ⌛️项目地址: https://gitcode.com/gh_mirrors/da/date-fns创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考