开发工具【免费下载链接】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点击查看免费下载ResourceKeys.TimeSpanHumanize是 Humanizer 2.10.1 版本中负责为TimeSpan.Humanize()系列扩展方法生成本地化资源键Resource Key的核心静态类。本文以其 API 参考文档为主体结合本仓库源码中TimeUnit枚举、IFormatter/DefaultFormatter实现、en.yml语言资源以及版本迁移文档系统讲解该类的设计意图、GetResourceKey方法的参数约定、资源键命名规则以及它在多语言时间跨度人性化输出链路中的实际位置帮助开发者理解并正确使用或迁移这一 API。一、类概览为 TimeSpan.Humanize 生成资源键在 Humanizer 2.x 时代本地化文案通过 .NET 资源.resx按文化加载。为了让TimeSpanHumanizeExtensions.TimeSpanHumanize(...)在任意文化下都能定位到正确的翻译字符串Humanizer 需要一个约定式键生成器把「时间单位 数量 是否转文字」三元组映射为一个唯一的资源键名。这正是ResourceKeys.TimeSpanHumanize的职责。参考文档对其定义如下public static class ResourceKeys.TimeSpanHumanize它是static class无需实例化直接通过类型名调用继承关系为System.Object→TimeSpanHumanize文档原话将其职责概括为Encapsulates the logic required to get the resource keys for TimeSpan.Humanize封装为TimeSpan.Humanize获取资源键所需的全部逻辑。需要说明的是ResourceKeys类在文档中的完整 API 参考见 Humanizer.Localisation.ResourceKeys.md其兄弟类ResourceKeys.DateHumanize相对日期人性化同样遵循这套键生成约定相关参考见 Humanizer.Localisation.ResourceKeys.DateHumanize.md。二、GetResourceKey 方法签名与参数语义ResourceKeys.TimeSpanHumanize对外暴露的核心 API 只有一个静态方法GetResourceKey文档中的完整签名如下public static string GetResourceKey(Humanizer.Localisation.TimeUnit unit, int count1, bool toWordsfalse);三个参数的语义与默认值如下表参数类型默认值含义unitHumanizer.Localisation.TimeUnit无必填时间单位决定资源键中的单位部分countSystem.Int321单位数量决定使用单数Single还是复数Multiple键文档注释为 Number of units, default is OnetoWordsSystem.Booleanfalse结果是否以单词形式呈现如 one minute 而非 1 minute默认false返回值类型为System.String文档给出的示例键为TimeSpanHumanize_SingleMinute例如GetResourceKey(TimeUnit.Minute)count 默认 1即可得到该键。参数取值范围的源码依据TimeUnit 枚举unit参数的类型定义于 src/Humanizer/Localisation/TimeUnit.cs共 8 个成员按从短到长排列public enum TimeUnit { Millisecond, // 1 毫秒 Second, // 1 秒 Minute, // 1 分钟 Hour, // 1 小时 Day, // 1 天 Week, // 1 周 Month, // 1 个月 Year // 1 年 }这意味着GetResourceKey可生成 8 个时间单位 × 单复数 × 数字/文字共 32 种组合的资源键。三、资源键命名约定Convention拆解文档将该方法的行为描述为Generates Resource Keys according to convention按约定生成资源键结合示例键TimeSpanHumanize_SingleMinute可以归纳出这套约定的三个组成部分固定前缀TimeSpanHumanize_标识该键服务于时间跨度人性化区别于DateHumanize_*前缀的日期人性化键数量段Single/Multiplecount 1时取Single否则取Multiple——这正是count默认值为 1 的原因也解释了文档注释 Number of units, default is One单位段由TimeUnit枚举成员名直接拼入如Minute、Hour因此GetResourceKey(TimeUnit.Minute)产出TimeSpanHumanize_SingleMinuteGetResourceKey(TimeUnit.Minute, 5)产出TimeSpanHumanize_MultipleMinutes。此外toWords为true时键会追加Words后缀用于区分纯数字计数5 minutes与文字计数five minutes两种本地化短语。从文档参数说明 Result to words, default is false 可以推断默认生成的键对应数字计数形态而toWordstrue对应文字计数形态。键名与语言资源中短语形态的对应关系虽然 2.10.1 时代的具体文案存放在.resx资源文件中但当前仓库的en.ymlsrc/Humanizer/Locales/en.yml以结构化的方式揭示了这套 Single/Multiple 约定的等价语义。其duration段对每个单位都定义了minute: single: numeric: 1 minute words: one minute multiple: forms: singular: minute default: minutes可以看到single.numeric/single.words恰好对应count 1时的数字形态TimeSpanHumanize_SingleMinute与文字形态TimeSpanHumanize_SingleMinuteWordsmultiple则对应count ! 1时的复数键。也就是说资源键命名约定与语言数据模型中的「单数/复数、数字/文字」维度完全一一对应GetResourceKey本质上是在为这些维度生成稳定的查找标识。四、GetResourceKey 在 TimeSpan.Humanize 调用链中的位置要理解该类的价值需要把它放回完整的调用链中。在 2.x 架构下TimeSpan.Humanize()的本地化流程大致为TimeSpanHumanizeExtensions.TimeSpanHumanize(timeSpan) │ ① 把 TimeSpan 拆解为 (TimeUnit, count, toWords) ▼ IFormatter.TimeSpanHumanize(TimeUnit, int, bool) │ ② 通过 ResourceKeys.TimeSpanHumanize.GetResourceKey 生成键 ▼ ResourceManager / 本地化表 按键取出短语 │ ③ 结合 count 渲染最终文案如 5 minutes / five minutes ▼ 输出人性化字符串其中第 ② 步正是GetResourceKey的核心职责——它是「语义参数」与「资源存储键」之间的翻译器。上游调用方TimeSpanHumanizeExtensions作为实际入口src/Humanizer/TimeSpanHumanizeExtensions.cs 展示了最终格式化时如何把解析出的三元组交给本地化层cultureFormatter.TimeSpanHumanize(timeUnit, amount, toWords)而格式化接口的契约定义在 src/Humanizer/Localisation/Formatters/IFormatter.cs/// param nametimeUnitThe unit being described./param /// param nameunitThe number of units being described./param /// param nametoWordsWhether the number should be rendered as words./param string TimeSpanHumanize(TimeUnit timeUnit, int unit, bool toWords false);注意IFormatter.TimeSpanHumanize的形参顺序timeUnit, unit, toWords与GetResourceKey(unit, count, toWords)的参数语义一一对应这正是 2.x 内部实现中键生成器与格式化器协作的基础——格式化器拿到参数后先用键生成器定位资源再按count决定渲染单数还是复数形态。下游消费方DefaultFormatter 与短语表当前主分支中DefaultFormattersrc/Humanizer/Localisation/Formatters/DefaultFormatter.cs已将资源查找升级为编译期生成的LocalePhraseTablepublic virtual string TimeSpanHumanize(TimeUnit timeUnit, int unit, bool toWords false) TryFormatTimeSpanFromPhraseTable(timeUnit, unit, toWords, out var result) ? result : throw new InvalidOperationException($Missing generated time-span phrase for {Culture.Name} and unit {timeUnit}.);其内部FormatTimeSpanPhrase同文件 L503-L534仍严格遵循与资源键相同的判定逻辑count 1时优先取phrase.Single且toWords为真时优先取SingleWordsVariant否则取phrase.Multiple/MultipleWordsVariant再按GetTimeSpanPhraseForm|count| 1 ? Singular : Default解析复数形态。可以看到「数量是否为 1」与「是否转文字」这两个维度贯穿了 2.x 的资源键命名与 3.x 的短语表解析GetResourceKey所编码的约定在演进后的实现中依然成立。五、版本演进该 API 的保留与迁移边界ResourceKeys属于 2.x 时代的本地化内部实现细节理解它的演进路径对升级项目很重要。仓库内的迁移文档 website/versioned_docs/version-2.10.1/upgrading/version-3-migration.mdx 明确说明ResourcesorResourceKeys— These remain in stable Humanizer 3 releases through3.0.10; their removal is a futuremain/previewmigration boundary.即ResourceKeys在稳定版 Humanizer 3.x直至3.0.10中仍然保留其移除是未来main/preview分支的迁移边界。因此在 Humanizer 2.10.1 及 3.0.10 之前的版本中ResourceKeys.TimeSpanHumanize.GetResourceKey可用于自行按约定生成资源键例如自定义IFormatter时定位自定义资源从 3.x 起官方推荐直接依赖IFormatter.TimeSpanHumanize与内置短语表如DefaultFormatter不再需要手写资源键文档还提醒自定义IFormatter实现必须实现TimeSpanHumanize_Age()方法见同迁移文档 L61这同样是IFormatter契约 src/Humanizer/Localisation/Formatters/IFormatter.cs 中的强制成员。六、总结ResourceKeys.TimeSpanHumanize.GetResourceKey(TimeUnit unit, int count 1, bool toWords false)是 Humanizer 2.x 本地化体系中的键生成器它通过「TimeSpanHumanize_前缀 Single/Multiple数量段 TimeUnit单位名 可选Words后缀」的约定把时间单位、数量与文字形态映射为可检索的资源键如TimeSpanHumanize_SingleMinute。理解这套约定既能帮助你在 2.x/3.0.10 时代正确使用或扩展本地化资源也能让你在阅读 3.x 的DefaultFormatter与语言 YAML 数据时快速识别单复数与数字/文字两条正交维度的演进脉络。赞分享开发工具【免费下载链接】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 资源键机制解析深入 ResourceKeys.TimeSpanHumanize 与 TimeSpan.Humanize 的本地化约定Humanizer 资源键机制解析深入 ResourceKeys.TimeSpanHumanize 与 TimeSpan.Humanize 的本地化约定 本篇开发工具Humanizer 资源键机制解析TimeUnitSymbol 与 TimeUnit.ToSymbol 的本地化原理Humanizer 资源键机制解析TimeUnitSymbol 与 TimeUnit.ToSymbol 的本地化原理 ResourceKeys.TimeUni开发工具Humanizer 资源键ResourceKeys机制解析TimeSpan.Humanize 本地化资源定位原理Humanizer 资源键ResourceKeys机制解析TimeSpan.Humanize 本地化资源定位原理 导读 Humanizer 的 TimeS开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考