date-fns 维吾尔语ugLocale 完全指南format/parse 快照、距离与时长本地化【免费下载链接】date-fns⏳ Modern JavaScript date utility library ⌛️项目地址: https://gitcode.com/gh_mirrors/da/date-fns导读本指南以 date-fns 仓库中 pkgs/core/src/locale/ug/snapshot.md 为骨架系统讲解维吾尔语UighurISO 639-2 代码uig仓库内代码为ug语言环境在 date-fns 中的完整行为包括format/parse全部日期时间 token 的实际输出与回解析结果、formatDistance/formatDistanceStrict的相对时间表达、formatRelative的上下文日期措辞以及formatDuration的时长格式化。读完本文你将理解 date-fns 如何通过Locale对象组装本地化能力能够正确使用uglocale 并读懂快照表中每一列的含义。一、快照文档是什么快照snapshot是 date-fns 每个语言环境的行为契约在TZutc环境下用固定的测试日期逐一执行format、parse、formatDistance、formatDistanceStrict、formatRelative、formatDuration等函数把结果固化成 snapshot.md 这样的文档。它同时服务于三个目的给使用者无需运行代码即可查证某个 token 在该语言下的实际显示文本给维护者改动本地化词条后通过快照对比可以立刻发现哪些语言行为发生了回归给测试脚本会校验磁盘上的快照与重新生成结果是否一致。快照的生成逻辑位于 pkgs/core/scripts/build/localeSnapshots/index.ts其中明确要求必须以TZutc运行第 25 行以保证所有时区相关结果可复现脚本逐条生成后调用格式化工具并在第 61-66 行校验磁盘快照与生成结果是否匹配不匹配会提示 Please run pnpm run locale-snapshots and commit the results.。这正是快照能够长期充当语言行为基准的原因。uglocale 的代码实现在 pkgs/core/src/locale/ug/index.ts并通过 pkgs/core/src/locale/index.ts#L90 的export * from ./ug/index.ts汇入全局 locale 导出因此可以直接import { ug } from date-fns/locale使用。二、format与parse快照详解ug快照的第一大部分覆盖format与parse的全部核心 token。表头含义Token string是传入format的模板Date是被格式化的输入时间format result是format的实际输出parse result是把format result回传给parse后得到的归一化时间解析失败显示Invalid Date或Errored。以下按 token 类别逐一解读。2.1 年份与季度Calendar yearyo输出数字年份1987→19870005→5维吾尔语不做数字本地化改写序数函数直接返回原数字见下。Local week-numbering yearYo按ug的周规则计算本地周编号年。快照中1987-02-11的Yo仍为1987而parse回解析得到1986-12-28说明该日期落在 1987 本地周年的第一周起点附近0005-01-01回解析为0004-12-26。QuarterQo/QQQ/QQQQ/QQQQQ数字形式Qo、QQQ、QQQQQ输出1、2等只有宽式文本QQQQ输出维吾尔语「بىرىنجى چارەك」第一季度、「ئىككىنجى چارەك」第二季度。注意宽式季度文本在parse中返回Invalid Date——从 match 实现 看matchQuarterPatterns的wide是/^چارەك [1234]/i期望「چارەك 1」这种形态而快照里的宽式词条是「بىرىنجى چارەك」两者不匹配因此回解析失败。这是快照暴露出的真实解析边界使用时应避免用宽式季度文本做往返解析。Quarter (stand-alone)qo/qqq/qqqq/qqqqq独立形式与格式化形式行为一致qqqq同样输出「بىرىنجى چارەك」且parse失败。2.2 月份Mo格式化数字月份1–12parse归一化为当月 1 日。MMM/MMMM缩写/全称两者在ug中词条完全相同见 localize/index.tsabbreviated 与 wide 均为同一组 12 个月名يانۋار1 月、فېۋىرال2 月、مارت3 月、ئاپرىل4 月、ماي5 月、ئىيۇن6 月、ئىيول7 月、ئاۋغۇست8 月、سىنتەبىر9 月、ئۆكتەبىر10 月、نويابىر11 月、دىكابىر12 月。全部可被parse成功回解析。MMMMM窄式只取月份首字符ي、ف、م、ا、م、ى、ى、ا、س、ۆ、ن、د。注意窄式存在歧义如 3 月「م」与 5 月「م」相同、6/7 月均为「ى」、4/8 月均为「ا」快照显示parse会命中数组中最先匹配的条目如「م」解析为 3 月2019-03-01而非 5 月「ى」直接Invalid Date「ا」解析为 4 月。因此窄式月份适合展示不适合作为唯一依据做精确回解析。Lo/LLL/LLLL/LLLLL独立形式行为与格式化形式一致LLLL输出完整月名LLLLL存在同样的窄式歧义。2.3 周、日与星期Local week of yearwoug的weekStartsOn: 0周日、firstWeekContainsDate: 1见 index.ts。2019-01-01输出第 1 周parse归一化为2018-12-30周日起点2019-12-01输出第 49 周。ISO week of yearIo按 ISO 8601 周规则周一起始2019-01-01是第 1 周回解析为2018-12-312019-12-01是第 48 周回解析为2019-11-25。两类周数遵循不同起点混用时需注意。Day of monthdo输出1、11、28组合模板do MMMM输出「1 فېۋىرال」这类「日 月名」的自然语序且可完整往返解析。Day of yearDo2019-02-11是第 42 天2019-12-31是第 365 天。Day of weekE/EE/EEE/EEEE/EEEEE/EEEEEE完整形式EEEE输出 يەكشەنبە周日、دۈشەنبە周一、سەيشەنبە周二、چارشەنبە周三、پەيشەنبە周四、جۈمە周五、شەنبە周六。窄式/短式E/EE/EEE、EEEEE、EEEEEE只输出首字符或缩写且快照显示 1–3 个字母的形式在parse中返回Invalid Date只有EEEE及窄式单字符可回解析——这与 match 实现 的匹配模式有关。ISO day of weekio/iii/iiii/iiiii/iiiiii与Local day of weekeo/eee/eeee/…数字形式输出 1–7文本形式与星期几类似完整 4 字符形式可解析短形式Invalid Date。co/ccc/cccc…独立形式与格式化形式等价。2.4 上下午与时段AM/PMa/aa/aaa/aaaa/aaaaa上午输出「ئە」下午输出「چ」五种宽度结果一致。parse中「ئە」归一化为当天00:00「چ」归一化为当天12:00。Flexible day periodB系列输出带方位格的时段词ئەتىگەندە早晨、چۈشتىن كىيىن午后、ئاخشامدا傍晚、كىچىدە夜间。这组词在parse中均为Invalid Datematch 实现 的dayPeriod模式只覆盖 ئە/چ/ك 与不带方位格的词干同样只宜展示、不宜回解析。2.5 小时、分钟与秒ho1–12 小时制23:13输出11Ho0–23输出23Ko0–1123:13输出11ko1–24输出23。四种制式均能精确回解析到对应时刻。mo分钟、so秒纯数字parse归一化到对应分钟/秒秒级精度保留。2.6 长本地化日期与时间P/p系列ug的长格式模板定义在 formatLong/index.ts日期short: MM/dd/yyyy、medium: MMM d, y、long: MMMM do, y、full: EEEE, MMMM do, y时间short: h:mm a、medium/long: h:mm:ss a、full: h:mm:ss a zzzz日期时间组合{{date}} دە {{time}}或{{date}}, {{time}}其中「دە」是维吾尔语中连接日期与时间的格助词。快照实测P→01/11/1987MM/dd/yyyy 顺序注意是月/日/年PP/PPP→يانۋار 11, 1987月名 日 年空格分隔无逗号在月名后PPPP→يەكشەنبە, يانۋار 11, 1987星期 月日年p→12:13 چ12 小时制 下午标记pp→12:13:14 چppp/pppp→12:13:14 چ GMT0带时区后缀注意快照显示带时区后缀的ppp/pppp、PPPppp、PPPPpppp在parse中均为Errored——这是当前uglocale 的已知解析缺口格式化展示没有问题但不要用它做往返解析。组合形式Pp→01/11/1987, 12:13 چPPpp→يانۋار 11, 1987, 12:13:14 چ。三、formatDistance相对时间措辞快照以现在是 2000-01-01 00:00为基准覆盖了过去与未来两个方向。维吾尔语的距离表达在 formatDistance/index.ts 中定义分为onecount1与othercount≥2用{{count}}占位两种形态语义oneother示例少于 X 秒بىر سىكۇنت ئىچىدەسىكۇنت ئىچىدە 10X 秒بىر سىكۇنتسىكۇنت 5半分钟يىرىم مىنۇت—少于 X 分钟بىر مىنۇت ئىچىدەمىنۇت ئىچىدە 30约 X 小时تەخمىنەن بىر سائەتسائەت 6 تەخمىنەنX 天بىر كۈنكۈن 14约 X 月تەخمىنەن بىر ئايئاي 5 تەخمىنەن约 X 年تەخمىنەن بىر يىليىل 6 تەخمىنەن超过 X 年بىر يىلدىن ئارتۇقيىلدىن ئارتۇق 2几乎 X 年ئاساسەن بىر يىليىل 2 ئاساسەن快照中三个列分别对应默认输出、includeSeconds: true与addSuffix: true默认2006-01-01→ 「يىل 6 تەخمىنەن」约 6 年2000-01-02→ 「بىر كۈن」2000-01-01T00:00:25→ 「بىر مىنۇت ئىچىدە」1 分钟内。includeSeconds: true不足 1 分钟时改用秒/半分钟粒度如00:00:25→ 「سىكۇنت ئىچىدە 10」10 秒内、00:00:35→ 「يىرىم مىنۇت」半分钟。addSuffix: true过去方向在结果后追加「بولدى」相当于…之前如「سائەت 6 تەخمىنەن بولدى」未来方向comparison 0不加后缀直接返回原结果见 formatDistance/index.ts#L101-L107 的实现逻辑。四、formatDistanceStrict精确距离formatDistanceStrict不做约/少于等模糊处理直接按选定单位输出精确数值。快照第三列演示了强制单位unit: hour的效果无论差值是年、月、天还是分钟全部折算成小时数输出如2006-01-01约 6 年→ 「سائەت 52608」2000-01-1514 天→ 「سائەت 336」不足 1 小时的小差值 → 「سائەت 0」。默认不指定单位时输出最自然的单位يىل 6、بىر يىل、ئاي 5、كۈن 14、سائەت 6、مىنۇت 45、سىكۇنت 25 等同样支持「بولدى」后缀。五、formatRelative上下文日期formatRelative根据目标日期相对基准日期的位置选择模板ug的模板在 formatRelative/index.ts 中lastWeek: ئۆتكەن eeee دە p yesterday: تۈنۈگۈن دە p today: بۈگۈن دە p tomorrow: ئەتە دە p nextWeek: eeee دە p other: P快照实测基准 2000-01-01 00:00今天 → 「بۈگۈن دە 12:00 ئە」今天 12:00 上午明天 → 「ئەتە دە 12:00 ئە」昨天 → 「تۈنۈگۈن دە 12:00 ئە」上周1999-12-27周一→ 「ئۆتكەن دۈشەنبە دە 12:00 ئە」上周一更早或更晚超出本周/下周窗口→ 退回P长日期如2000-01-10→ 「01/10/2000」、1999-12-21→ 「12/21/1999」。六、formatDuration时长格式化formatDuration接受Duration对象years/months/weeks/days/hours/minutes/secondsug的词条同样区分one与other{years:0}→ يىل 0{years:1}→ بىر يىل{years:2}→ يىل 2{weeks:1}→ بىرھەپتە单数形态无空格{weeks:2}→ ھەپتە 2{days:1}→ بىر كۈن{hours:1}→ بىر سائەت{minutes:1}→ بىر مىنۇت{seconds:1}→ بىر سىكۇنت。注意单数1使用「بىر 单位」的独立词形其余数字含 0使用「单位 数字」的语序与formatDistance中的词形规则保持一致。七、底层机制Locale 对象与本地化辅助函数ug是 date-fnsLocale接口的一个实例index.ts由六个部分组成codeugformatDistance相对距离词条与addSuffix/comparison处理formatLongP/p系列长格式模板formatRelative上下文日期模板localize通过buildLocalizeFn构建的 era/quarter/month/day/dayPeriod 本地化函数localize/index.ts。ordinalNumber直接返回String(dirtyNumber)第 146-148 行所以序数 tokenyo、Qo、Mo、do等不产生th/st之类的英文后缀而是纯数字matchparse反查使用的正则匹配器match/index.ts包含序数、era、季度、月份、星期、时段的正则与解析回调。其中options.weekStartsOn: 0一周从周日开始与firstWeekContainsDate: 1决定本地周编号年Yo、本地周数wo以及startOfWeek等周相关函数的行为这两个字段在 pkgs/core/src/types.ts#L211 与 pkgs/core/src/types.ts#L219 有类型定义可供其他 locale 参照。八、在项目中使用uglocaleug与其他语言环境一样通过date-fns/locale导入并在调用format、formatDistance、formatDistanceToNow、parse等函数时作为locale选项传入import { format, formatDistance, formatRelative } from date-fns; import { ug } from date-fns/locale; const date new Date(2019-02-11T12:13:14.015Z); format(date, EEEE, MMMM do, y, { locale: ug }); // دۈشەنبە, فېۋىرال 11, 2019 format(date, PPPP, { locale: ug }); // چەيشەنبە, فېۋىرال 11, 2019依据快照 PPPP 行为 formatDistance(new Date(2000-01-02), new Date(2000-01-01), { locale: ug }); // بىر كۈن formatRelative(new Date(2000-01-02), new Date(2000-01-01), { locale: ug }); // ئەتە دە 12:00 ئە使用建议依据快照实测展示优先MMM/MMMM月名、EEEE星期全称、P–PPPP长日期、p/pp时间均能稳定输出维吾尔语文本往返解析注意宽式季度「بىرىنجى چارەك」、E/EEE等 1–3 字母星期、B系列时段词、以及带GMT时区后缀的ppp/pppp/PPPppp/PPPPpppp在parse中会返回Invalid Date或Errored不应作为 parse 输入窄式月份有歧义MMMMM中「م」「ى」「ا」对应多个月份回解析会命中数组首项或失败仅适合 UI 缩写展示本地周规则ug的weekStartsOn为周日、firstWeekContainsDate为 1涉及周编号的计算如wo、Yo以此为准与 ISO 周Io不同。相关资源快照文档pkgs/core/src/locale/ug/snapshot.mdLocale 入口pkgs/core/src/locale/ug/index.ts词条实现pkgs/core/src/locale/ug/_lib/formatDistance/index.ts、pkgs/core/src/locale/ug/_lib/formatLong/index.ts、pkgs/core/src/locale/ug/_lib/formatRelative/index.ts、pkgs/core/src/locale/ug/_lib/localize/index.ts、pkgs/core/src/locale/ug/_lib/match/index.ts快照生成脚本pkgs/core/scripts/build/localeSnapshots/index.tsLocale 类型定义pkgs/core/src/types.ts全部 locale 导出pkgs/core/src/locale/index.ts【免费下载链接】date-fns⏳ Modern JavaScript date utility library ⌛️项目地址: https://gitcode.com/gh_mirrors/da/date-fns创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考