Humanizer 的 Tense 枚举深度解析：过去与未来时态如何驱动本地化相对时间表达

开发工具【免费下载链接】HumanizerHumanizer meets all your .NET needs for manipulating and displaying strings, enums, dates, times, timespans, numbers and quantities项目地址https://gitcode.com/gh_mirrors/hu/Humanizer点击查看免费下载导读Tense 是 Humanizer 中用于标记相对时间参考方向的枚举类型仅有Past过去与Future未来两个成员却是整个日期/时间本地化体系DateTime.Humanize()、DateOnly.Humanize()、TimeOnly.Humanize()等的方向盘。本篇以 v2.14.1 文档中对该枚举的 API 描述为主体结合当前仓库源码讲解 Tense 的定义与语义、它在相对时间计算链路中的判定规则、如何在 Formatter 本地化短语表中选择过去/未来短语以及多语言如中文、英语、斯拉夫语系中该枚举背后所牵动的语法变体机制。读完你将理解 Humanizer 相对时间输出的完整决策链并能在自定义 Formatter、Precision 策略或新语言接入时准确使用这一枚举。Tense 枚举只有两个成员的时间方向在 v2.14.1 的 API 参考文档website/versioned_docs/version-2.14.1/api/Humanizer.Localisation.Tense.md中Humanizer.Localisation.Tense被定义为枚举所有可能的时间参考过去或未来Enumerates the possible time references; past or future。其定义如下public enum Tense它包含两个字段字段值语义依据文档Future0表示未来Indicates the futurePast1表示过去Indicates the past对应到仓库源码 src/Humanizer/Localisation/Tense.csnamespace Humanizer; /// summary /// Indicates whether a relative time reference is in the past or the future. /// /summary public enum Tense { /// summary /// A future reference such as in 2 days. /// /summary Future, /// summary /// A past reference such as 2 days ago. /// /summary Past }需要注意两点成员顺序源码中Future在前、Past在后因此底层数值恰好为Future 0、Past 1与文档表格中的字段值一致。由于这是普通非[Flags]枚举两个成员在逻辑上是互斥的一个时间点要么属于过去、要么属于未来。语义示例源码注释给出了最直观的对照——Future对应 in 2 days 这类未来表述Past对应 2 days ago 这类过去表述。该枚举位于Humanizer.Localisation命名空间与TimeUnitsrc/Humanizer/Localisation/TimeUnit.cs等本地化支撑类型并列是 Formatter 接口的公共签名成员见下文因此它出现在 Humanizer 的公开 API 批准测试文件中例如 tests/Humanizer.Tests/ApiApprover/PublicApiApprovalTest.Approve_Public_Api.DotNet8_0.verified.txt。Tense 在日期 Humanize 链路中的判定input comparisonBaseTense 本身不携带多久的信息它只回答方向问题。方向由相对时间计算的核心算法决定将待人文化的输入时间与基准时间比较输入晚于基准即未来否则即过去。在 src/Humanizer/DateTimeHumanizeStrategy/DateTimeHumanizeAlgorithms.cs 中这一判定被反复使用。以DateTime的默认策略为例public static string DefaultHumanize(DateTime input, DateTime comparisonBase, CultureInfo? culture) { var tense input comparisonBase ? Tense.Future : Tense.Past; var ts new TimeSpan(Math.Abs(comparisonBase.Ticks - input.Ticks)); var sameMonth comparisonBase.Date.AddMonths(tense Tense.Future ? 1 : -1) input.Date; var days Math.Abs((input.Date - comparisonBase.Date).Days); return DefaultHumanize(ts, sameMonth, days, tense, culture); }关键点方向判定input comparisonBase ? Tense.Future : Tense.Past。注意这里运算符比较的是完整时间含时刻并非仅日期。距离与方向分离时间差ts取绝对值只保留大小方向单独交给tense。之后在DefaultHumanize(TimeSpan ts, bool sameMonth, int days, Tense tense, CultureInfo? culture)内部依据时间差落到Millisecond、Second、Minute、Hour、Day、Week、Month、Year等时间单位并携带tense调用 Formatter 输出。sameMonth的计算也依赖 tense当判断 2830 天的时间差是否应表述为一个月时代码用tense Tense.Future ? 1 : -1决定基准日期是加一个月还是减一个月未来是下个月过去是上个月。同样的input comparisonBase ? Tense.Future : Tense.Past判定模式还出现在PrecisionHumanize(DateTime, ...)、PrecisionHumanize(DateOnly, ...)、PrecisionHumanize(TimeOnly, ...)、DefaultHumanize(DateOnly, ...)、DefaultHumanize(TimeOnly, ...)等重载中——也就是说无论是DateTime、DateTimeOffset、DateOnly还是TimeOnlyTense 的推导规则是一致的。这些算法的调用方是公开的扩展方法链。例如 src/Humanizer/DateHumanizeExtensions.cs 中public static string Humanize(this DateTime input, bool? utcDate null, DateTime? dateToCompareAgainst null, CultureInfo? culture null) { var comparisonBase dateToCompareAgainst ?? DateTime.UtcNow; utcDate ?? input.Kind ! DateTimeKind.Local; comparisonBase utcDate.Value ? comparisonBase.ToUniversalTime() : comparisonBase.ToLocalTime(); return Configurator.DateTimeHumanizeStrategy.Humanize(input, comparisonBase, culture); }即未显式传入比较基准时默认以当前时刻为基准DateOnly默认以当天为基准TimeOnly默认以当前时间并按useUtc决定 UTC/本地然后由注册的 Humanize 策略默认策略或 Precision 策略完成上述 tense 判定与单位归约。日常调用DateTime.UtcNow.AddHours(-2).Humanize()得到 2 hours ago、DateTime.UtcNow.AddDays(1).Humanize()得到 tomorrow其方向决策全部来自 Tense。测试如何验证 Past/Future 两条分支仓库测试对 Tense 的两个方向做了系统性验证。在 tests/Humanizer.Tests/DateHumanizeDefaultStrategyTests.cs 中同一数量级的用例总是成对出现分别以Tense.Past与Tense.Future驱动[Theory] [InlineData(1, one second ago)] [InlineData(10, 10 seconds ago)] [InlineData(59, 59 seconds ago)] [InlineData(60, a minute ago)] public void SecondsAgo(int seconds, string expected) DateHumanize.Verify(expected, seconds, TimeUnit.Second, Tense.Past); [Theory] [InlineData(1, one second from now)] [InlineData(10, 10 seconds from now)] [InlineData(59, 59 seconds from now)] [InlineData(60, a minute from now)] public void SecondsFromNow(int seconds, string expected) DateHumanize.Verify(expected, seconds, TimeUnit.Second, Tense.Future);测试基础设施 tests/Humanizer.Tests/DateHumanize.cs 中的Verify方法展示了 Tense 的另一种用法——直接以枚举驱动时间偏移方向unit Math.Abs(unit); if (tense Tense.Past) { unit -unit; } var deltaFromNow timeUnit switch { TimeUnit.Millisecond TimeSpan.FromMilliseconds(unit), TimeUnit.Second TimeSpan.FromSeconds(unit), TimeUnit.Minute TimeSpan.FromMinutes(unit), TimeUnit.Hour TimeSpan.FromHours(unit), TimeUnit.Day TimeSpan.FromDays(unit), TimeUnit.Week TimeSpan.FromDays(unit * 7), TimeUnit.Month TimeSpan.FromDays(unit * 31), TimeUnit.Year TimeSpan.FromDays(unit * 366), _ new() };也就是说测试先根据tense Tense.Past把单位数量取负再构造相对基准时间的时间差从而把过去/未来翻译成早于/晚于基准的具体时间点最后断言 Humanize 输出与期望短语一致。测试用例覆盖了秒、分钟、小时、天、周、月、年各档位例如[InlineData(7, one week ago)]/[InlineData(7, one week from now)]、[InlineData(1, one month ago)]/[InlineData(1, one month from now)]、[InlineData(2, 2 years ago)]等证明 Past/Future 在默认策略下对每个时间单位都生效。Tense 如何路由到本地化短语表Formatter 的第二个索引Tense 的实际落地发生在 Formatter 层。公开接口 src/Humanizer/Localisation/Formatters/IFormatter.cs 中DateHumanize方法以Tense为参数/// summary /// Returns the localized representation of a relative date phrase. /// /summary /// param nametimeUnitThe unit being described./param /// param nametimeUnitTenseWhether the reference is in the past or the future./param /// param nameunitThe number of units being described./param /// returnsThe localized relative date phrase./returns string DateHumanize(TimeUnit timeUnit, Tense timeUnitTense, int unit);在 src/Humanizer/Localisation/Formatters/LocalePhraseTable.cs 中每个语言的短语表内部维护了两套相对日期短语数组——datePast与dateFuture二者分别以TimeUnit为下标public bool TryGetDatePhrase(TimeUnit unit, Tense tense, out LocalizedDatePhrase phrase) { var value (tense Tense.Future ? dateFuture : datePast)[(int)unit]; if (value is { } found) { phrase found; return true; } phrase default; return false; }因此Tense 是短语表查询的第二个索引维度先由TimeUnit确定描述的是秒、分、时、天、周、月还是年再由Tense确定该单位的过去形还是未来形。例如英语中天这一单位的短语未来方向是 tomorrow、过去方向是 yesterday单数复数时则分别是 N days from now 与 N days ago。而 src/Humanizer/Localisation/Formatters/DefaultFormatter.cs 的DateHumanize则把单位 方向 数量组装为最终文本public virtual string DateHumanize(TimeUnit timeUnit, Tense timeUnitTense, int unit) TryFormatDateFromPhraseTable(timeUnit, timeUnitTense, unit, out var result) ? result : throw new InvalidOperationException($Missing generated relative-date phrase for {Culture.Name} and unit {timeUnit}.);TryFormatDateFromPhraseTable内部的处理顺序值得一提count 0时直接返回dateNownow 类短语count 1且短语表存在Single形时返回单数形态如 yesterday/tomorrow否则取Multiple形态并通过GetDatePhraseForm(unit, tense, count)决定使用零形、单数形、双数形、复数形等FormatterNumberForm之一再渲染成 N {unit} ago / from now 结构src/Humanizer/Localisation/Formatters/DefaultFormatter.cs。由于短语表由源码生成器Humanizer.SourceGenerators见 src/Humanizer.SourceGenerators/HumanizerSourceGenerator.cs从src/Humanizer/Locales/*.yml生成因此每种语言都可以为同一(TimeUnit, Tense)组合提供完全不同的过去/未来措辞与词序。结合语言差异Tense 在多语言与语法变体中的作用Tense 的方向选择在所有语言中一致但不同语言对过去/未来的表达方式差异巨大这正体现了 Humanizer 将方向抽象为枚举的价值——算法层只负责判定方向措辞交给语言层。英语等分析语过去/未来通过词序与介词区分如 2 days ago 与 in 2 days在英文短语表中体现为不同的BeforeCountText/AfterCountText或模板{prep}占位符。斯拉夫语系、中文等部分语言的过去/未来甚至需要不同的语法格或量词。例如中文src/Humanizer/Locales/zh-CN.yml用天前/天后、个月前/个月后这类后置方向词而波兰语等语言在复数形态上还有Dual/Paucal等额外变体见 tests/Humanizer.Tests/Localisation/pl/PolishPaucalTests.cs。LocalizedPhraseForms.Resolvesrc/Humanizer/Localisation/Formatters/LocalePhraseTable.cs会根据FormatterNumberForm从Zero/Singular/Dual/Paucal/Plural/Many中按语言能力逐级回退到Default从而保证不同语言都能在统一枚举驱动下输出语法正确的短语。另外仓库中还有一层更细粒度的按 tense 选择规则机制在 src/Humanizer/Localisation/Formatters/ProfiledFormatter.cs 中FormatterDateFormRule通过FormatterTenseMaskPast 1 0、Future 1 1的标志位掩码描述一条规则适用于哪种方向public bool AppliesTo(TimeUnit unit, Tense tense, int number) number Number (Units GetTimeUnitMask(unit)) ! 0 (Tenses GetTenseMask(tense)) ! 0; static FormatterTenseMask GetTenseMask(Tense tense) tense Tense.Future ? FormatterTenseMask.Future : FormatterTenseMask.Past;这类规则用于处理特定数量 特定单位 特定方向需要走专门短语的语言例如某些语言中昨天/明天这类词汇化表达可以推断它是为高保真本地化输出服务的扩展机制普通语言回退到通用短语表即可。如何在自定义 Formatter 中使用 Tense由于IFormatter.DateHumanize(TimeUnit, Tense, int)是公开接口如果你需要接入一种短语表未覆盖的方言可以继承DefaultFormattersrc/Humanizer/Localisation/Formatters/DefaultFormatter.cs并重写相关虚方法。可重写的挂点包括DateHumanize(TimeUnit, Tense, int)整体输出入口可完全自定义GetDatePhraseForm(TimeUnit, Tense, int)根据数量与方向决定选用Singular还是Default形态默认规则为Math.Abs(number) 1时取单数ShouldUseDatePhraseTable(TimeUnit, Tense, int, LocalizedDatePhrase)决定是否使用生成的短语表返回false可让短语表查询短路进入自定义逻辑。并通过Configuratorsrc/Humanizer/Configuration/Configurator.cs的 Formatter 注册机制将自定义 Formatter 绑定到目标文化例如使用Configurator.Formatters的注册方法按 locale 覆盖默认实现。这样方向判定Tense 的推导仍由算法层负责而你只需聚焦于目标语言在每种(TimeUnit, Tense, count)组合下的措辞。小结Humanizer.Localisation.Tense是 Humanizer 相对时间功能的最小但最关键的方向标记定义上只有Future0与Past1两个互斥成员语义为未来参考in 2 days/ 过去参考2 days ago运行时由算法以input comparisonBase统一推导DateTimeHumanizeAlgorithms.cs与具体时间单位无关在 Formatter 层作为短语表的第二索引从dateFuture/datePast两组数组中选取对应短语LocalePhraseTable.cs测试通过Tense.Past/Tense.Future成对覆盖每个时间单位的输出DateHumanizeDefaultStrategyTests.cs。理解了这个枚举你也就掌握了 Humanizer 相对日期输出的方向决策链路扩展方法 → 策略算法推导 Tense→ Formatter按 Tense 与 TimeUnit 查短语表→ 本地化短语。无论是要排查为什么某个时间点输出成了 ago 而非 from now还是要为自定义语言接入相对时间表达都可以从这一链路入手定位。赞分享开发工具【免费下载链接】HumanizerHumanizer meets all your .NET needs for manipulating and displaying strings, enums, dates, times, timespans, numbers and quantities项目地址https://gitcode.com/gh_mirrors/hu/Humanizer点击查看免费下载相关推荐Humanizer 的 Tense 枚举相对时间表达中过去与未来的语义枢纽Humanizer 的 Tense 枚举相对时间表达中过去与未来的语义枢纽 本文围绕 Humanizer 2.11.10 版本 API 文档中的 Humani开发工具Humanizer 的 Tense 枚举过去与未来相对时间引用背后的实现机制Humanizer 的 Tense 枚举过去与未来相对时间引用背后的实现机制 本篇技术指南聚焦 Humanizer 项目中的 Tense 枚举 Humani开发工具Humanizer.Tense 枚举解析过去与未来的相对时间表达在 Humanizer 中的完整机制Humanizer.Tense 枚举解析过去与未来的相对时间表达在 Humanizer 中的完整机制 本篇技术指南聚焦 Humanizer 中 Tense 枚开发工具上一篇RLPR-Qwen2.5无需验证器推理性能大跃升下一篇如何免费微调IBM 32B Granite-4.0大模型创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考