开发工具【免费下载链接】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.Localisation.NumberToWords命名空间承载着 Humanizer 中“把数字变成当地语言单词”这一核心能力的抽象层。本文将以该命名空间唯一公开接口INumberToWordsConverter为主线完整梳理其方法签名、参数语义、扩展方法调用链、注册表配置机制并结合仓库内 40 个具体转换器实现与测试用例说明如何将该能力本地化到任意语言。读完本文你将能够理解ToWords/ToOrdinalWords/ToTuple等扩展方法背后的完整执行路径并掌握接入自定义语言转换器的全部接口契约。命名空间概览面向数字本地化的唯一公开接口在 version-2.11.10 的 API 文档中该命名空间下仅列出一个公开接口接口说明INumberToWordsConverter需要实现以本地化ToWords和ToOrdinalWords方法的接口这意味着Humanizer 将“数字 → 单词”的规则完全抽象为单一契约所有语言的转换器英文、中文、俄语、印度语、希伯来语等都通过实现该接口接入系统而面向用户的扩展方法如123.ToWords()只与该接口打交道不感知具体语言实现。接口的完整定义位于 src/Humanizer/Localisation/NumberToWords/INumberToWordsConverter.cs其 XML 注释概括了职责“将数字转换为区域相关的单词、序数词与元组名称”Converts numbers into locale-specific words, ordinals, and tuple names。接口方法全景基数词、序数词与元组转换2.11.10 版本的接口文档Humanizer.Localisation.NumberToWords.INumberToWordsConverter.md定义了 5 个方法而当前仓库源码中的接口已扩展为 10 个重载覆盖了基数词、序数词和元组三类转换能力。以下以当前源码为准并标注与旧版文档的对应关系。基数词转换Convert(long) 系列string Convert(long number);说明使用区域默认的语法性别grammatical gender将数字转换为字符串。参数numberSystem.Int64。返回System.String本地化的基数词。string Convert(long number, bool addAnd);说明使用区域默认语法性别并决定是否在复合数字中插入区域特定的连接词conjunction。参数addAndSystem.Boolean指定是否添加 And。string Convert(long number, GrammaticalGender gender, bool addAnd true);说明使用指定的语法性别进行转换addAnd默认值为true。参数genderGrammaticalGender在区域区分性别形式时使用。当前源码在此基础上新增了三个重载用于组合WordForm词形与上述选项string Convert(long number, WordForm wordForm); string Convert(long number, bool addAnd, WordForm wordForm); string Convert(long number, WordForm wordForm, GrammaticalGender gender, bool addAnd true);这些重载解决的是同一语言内“同一数字在不同句法位置存在不同拼写”的问题例如西班牙语中21在句尾写veintiuno在名词前修饰时写veintiún详见下文WordForm一节。序数词转换ConvertToOrdinal(int) 系列string ConvertToOrdinal(int number);说明使用区域默认语法性别将数字转换为序数词字符串。注意参数类型是System.Int32与基数词的long不同。string ConvertToOrdinal(int number, GrammaticalGender gender);说明使用指定的语法性别转换序数词。当前源码又补充了带WordForm的两个重载string ConvertToOrdinal(int number, WordForm wordForm); string ConvertToOrdinal(int number, GrammaticalGender gender, WordForm wordForm);序数词转换的价值在于输出如first、primero西语“第一”这类词形与Ordinalize输出1st这类后缀式序数化是两条不同的路径。元组名称转换ConvertToTuple(int)string ConvertToTuple(int number);说明将整数转换为区域特定的命名元组如英文的single、double当区域未定义对应名称时返回数字回退形式。这是1.ToTuple()扩展方法的底层实现入口。关键参数类型语法性别与词形要正确使用接口需要理解两个参数枚举GrammaticalGendersrc/Humanizer/GrammaticalGender.cs取值Masculine阳性、Feminine阴性、Neuter中性。俄语、希伯来语、葡萄牙语等语言中数字会随性别变形例如俄语1的阳性为один、阴性为одна巴西葡萄牙语1.ToOrdinalWords(GrammaticalGender.Masculine)输出primeiro阴性输出primeira。WordFormsrc/Humanizer/WordForm.cs取值Normal正常词形、Abbreviation缩略词形、Eifeler卢森堡语 Eifeler 规则词形依据后随辅音/元音决定是否省音。西班牙语是典型场景21.ToWords(WordForm.Normal)→veintiuno而21.ToWords(WordForm.Abbreviation)→veintiún序数词同样适用如3.ToOrdinalWords(WordForm.Normal)→tercero3.ToOrdinalWords(WordForm.Abbreviation)→tercer。扩展方法调用链从 ToWords 到接口用户日常使用的并不是接口方法而是 src/Humanizer/NumberToWordsExtension.cs 中的一组扩展方法。它们的共同特征是全部委托给Configurator.GetNumberToWordsConverter(culture)解析出的转换器实例。典型调用链如下public static string ToWords(this long number, CultureInfo? culture null, bool addAnd true) Configurator.GetNumberToWordsConverter(culture).Convert(number, addAnd);即123.ToWords()→Configurator.GetNumberToWordsConverter(null)→INumberToWordsConverter.Convert(123, true)。其他重载依此类推ToOrdinalWords(this int, ...)→ConvertToOrdinal(...)其中1.ToOrdinalWords()还带有特殊处理对丹麦语første、印尼语/马来语pertama、斯洛伐克语按性别返回prvý/prvá/prvé、祖鲁语okokuqala等文化直接返回原生“第一”词见扩展方法内部的TryGetNativeFirstOrdinalWordToTuple(this int, CultureInfo?)→ConvertToTuple(number)ToIndianWords(this long, IndianScaleStyle)则绕开当前文化配置强制解析en-IN转换器并按NamedScales印度命名刻度或CroreBased基于 crore 的口语表达如lakh crore、shankh两套刻度表转换。culture参数为null时使用当前线程文化显式传入CultureInfo即可实现跨文化转换这正是本地化测试的基础。注册表与配置转换器如何被解析接口实例由 src/Humanizer/Configuration/NumberToWordsConverterRegistry.cs 管理class NumberToWordsConverterRegistry : LocaliserRegistryINumberToWordsConverter { public NumberToWordsConverterRegistry() : base(_ NumberToWordsProfileCatalog.Resolve(en, CultureInfo.InvariantCulture)) NumberToWordsConverterRegistryRegistrations.Register(this); }两点值得注意默认回退到英文当某个文化没有注册专用转换器时ResolveForCulture会落到基类默认工厂即解析en不区分区域性的转换器保证任何文化下ToWords都不会抛异常注册表由源生成器填充NumberToWordsConverterRegistryRegistrations与NumberToWordsProfileCatalog均来自 src/Humanizer.SourceGenerators 根据 Locales 目录下的 YAML 数据 生成的代码因此新增语言只需提供 YAML 数据与转换器实现即可自动纳入注册。对外暴露的入口在 src/Humanizer/Configuration/Configurator.cspublic static LocaliserRegistryINumberToWordsConverter NumberToWordsConverters { get; } new NumberToWordsConverterRegistry();内部通过GetNumberToWordsConverter(CultureInfo?)完成按文化的解析。LocaliserRegistry的语义是优先查找完全匹配的CultureInfo匹配失败时逐级向上回退如zh-CN→zh→ 默认英文。默认回退实现与 40 个语言转换器当区域确实没有专用转换器时src/Humanizer/Localisation/NumberToWords/DefaultNumberToWordsConverter.cs 承担兜底职责它直接调用number.ToString(culture)即输出文化感知的数字格式化字符串而非单词——例如123.ToString(fr-FR)得到123。这是一个刻意保持最小化的实现正如其注释所述“仅在区域未提供专用数字转单词渲染器时使用”。在 src/Humanizer/Localisation/NumberToWords 目录下实际存在约 40 个具体转换器实现从文件名即可窥见多语言形态的工程分治语言专属MacedonianNumberToWordsConverter、IndianGroupingNumberToWordsConverter含IndianGroupingGenderedNumberToWordsConverter体现印度 3-2-2 分组法词形变化GenderedNumberToWordsConverter性别化基类、GenderlessNumberToWordsConverter无性别基类、EastSlavicNumberToWordsConverter东斯拉夫语族、WestSlavicGenderedNumberToWordsConverter、SouthSlavicCardinalNumberToWordsConverter结构策略TriadScaleNumberToWordsConverter三位一组、JoinedScaleNumberToWordsConverter、ConjunctionalScaleNumberToWordsConverter、ConjoinedGenderedScaleNumberToWordsConverter支持and连接词且区分性别的复合刻度、LinkedVigesimalNumberToWordsConverter二十进制序数策略HyphenatedOrdinalNumberToWordsConverter连字符序数、StemmedScaleNumberToWordsConverter词干变化、TerminalOrdinalScaleNumberToWordsConverter、LongScaleStemOrdinalNumberToWordsConverter等。可以推断这些类构成了一个“基类抽取共性 子类定制差异”的继承体系例如GenderlessNumberToWordsConverter提供Convert(long, GrammaticalGender, bool)的默认转发实现性别化语言的子类再覆盖性别分支。这种设计让每种语言只需实现自己独特的语法片段而将三位分组、刻度表、连接词等通用逻辑收敛到各抽象基类中。测试与契约验证仓库测试从多个角度锁定该接口的行为tests/Humanizer.Tests/Localisation/LocaleTheoryMatrixCompletenessTests.cs 断言每个已注册区域都至少有一个INumberToWordsConverter可用回退到英文也算满足防止语言矩阵出现“漏注册”tests/Humanizer.Tests/Localisation/NumberWordPhraseTests.cs 直接调用Configurator.NumberToWordsConverters.ResolveForCulture(...)并按区域断言输出tests/Humanizer.Tests/ApiApprover/PublicApiApprovalTest.Approve_Public_Api.*.verified.txt 通过 API 快照确认INumberToWordsConverter的公开签名、Configurator.NumberToWordsConverters属性以及ToTuple/ToIndianWords等扩展方法在各目标框架.NET 8、.NET 10/11、.NET Framework 4.8下保持一致tests/Humanizer.Tests/Localisation/ur/UrduOrdinalTests.cs 专门验证乌尔都语经由该接口路径输出的带性别序数词一致性。这些测试共同保证只要实现接口并注册ToWords/ToOrdinalWords/ToTuple就能被所有上层调用方透明使用。小结Humanizer.Localisation.NumberToWords是 Humanizer 本地化能力的枢纽之一INumberToWordsConverter以 10 个重载定义了基数词、序数词、元组三类转换契约NumberToWordsExtension将契约包装为对开发者友好的扩展方法NumberToWordsConverterRegistry与Configurator.NumberToWordsConverters提供按文化解析与英文兜底约 40 个具体转换器则承载各语言的语法细节。若需为自定义语言接入数字转单词能力只需实现该接口并通过注册机制登记即可复用整套扩展方法与测试体系。赞分享开发工具【免费下载链接】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 序数词本地化解析从 IOrdinalizer 接口到多语言 Ordinalize 实现Humanizer 序数词本地化解析从 IOrdinalizer 接口到多语言 Ordinalize 实现 本篇技术指南以 Humanizer 仓库中 Hum开发工具Humanizer 数字转文字核心接口 INumberToWordsConverter 完全指南本地化基数词、序数词与元组名的统一抽象Humanizer 数字转文字核心接口 INumberToWordsConverter 完全指南本地化基数词、序数词与元组名的统一抽象 Humanizer 是开发工具Humanizer 的 INumberToWordsConverter深入解析数字转单词的多语言转换接口Humanizer 的 INumberToWordsConverter深入解析数字转单词的多语言转换接口 导读 INumberToWordsConverter开发工具上一篇Chinese-BERT-wwm 项目常见问题解决方案下一篇【免费下载】 Chinese-BERT-wwm 安装和配置指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考