Humanizer 中的 GrammaticalGender：面向语法性别的多语言数字与序数本地化

开发工具【免费下载链接】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点击查看免费下载GrammaticalGender 是 Humanizer 库中用于指定输出词语法性别的核心枚举它让同一数字在不同语言如俄语、西班牙语、德语、波兰语等中能够生成符合名词性别的正确词形。本文围绕 GrammaticalGender.cs 的源码定义结合 NumberToWordsExtension.cs、OrdinalizeExtensions.cs 等扩展方法及多语言测试用例讲解枚举的三个成员、它在数字转词与序数化 API 中的传递链路以及它在性别无关语言中的静默退化行为帮助你写出真正本地化的 .NET 文案代码。一、为什么需要语法性别枚举从语言差异说起英语几乎不需要语法性别one、first无论修饰什么名词都是同一个词。但许多语言并非如此俄语中1的阳性是один阴性是одна见 NumberToWordsExtension.cs 中的文档示例希伯来语中1的阳性是אחד阴性是אחת同上西班牙语中1的序数阳性为primero、阴性为primera缩写阳性为primer见 CoverageGapTests.cs 的测试断言巴西葡萄牙语中1º阳性与1ª阴性是两种不同的序数写法见 OrdinalizeExtensions.cs。当文案需要描述一个人阳性或一本书阴性时单纯传入数字无法让库知道该用哪个词形。GrammaticalGender就是为此提供的显式选项由调用方根据实际名词的性别传入。二、枚举定义与三个成员GrammaticalGender.cs 的完整定义如下namespace Humanizer; /// summary /// Options for specifying the desired grammatical gender for the output words /// /summary public enum GrammaticalGender { /// summary /// Indicates masculine grammatical gender /// /summary Masculine, /// summary /// Indicates feminine grammatical gender /// /summary Feminine, /// summary /// Indicates neuter grammatical gender /// /summary Neuter }三个成员的语义与底层数值如下成员数值语义典型语言场景Masculine0阳性俄语、希伯来语、西班牙语的阳性名词作为多数性别感知转换器的默认性别Feminine1阴性俄语одна、希伯来语אחת、西班牙语una/primera等阴性词形Neuter2中性德语、俄语等拥有中性词形的语言无中性词形的语言会自动退化为默认词形注意枚举数值是隐式赋值的0、1、2并非由源码显式声明——这是 C# 枚举的默认行为。测试中甚至通过(GrammaticalGender)999验证非法值会抛出ArgumentOutOfRangeException见 CoverageGapTests.cs说明底层实现是按数值做校验的调用方不应依赖超出三个成员的取值。三、性别参数如何流入转换器调用链解析GrammaticalGender本身只是一个选项容器真正的工作由各语言的INumberToWordsConverter实现完成。调用链如下扩展方法层NumberToWordsExtension.cs 提供ToWords(this int/long number, GrammaticalGender gender, CultureInfo? culture null)等重载内部调用Configurator.GetNumberToWordsConverter(culture).Convert(number, gender)接口层INumberToWordsConverter.cs 声明Convert(long number, GrammaticalGender gender, bool addAnd true)与ConvertToOrdinal(int number, GrammaticalGender gender)等性别感知方法文档注释明确当语言区分性别词形时使用指定的语法性别基类层GenderedNumberToWordsConverter.cs 是性别感知语言的抽象基类构造函数接受默认性别默认GrammaticalGender.Masculine。它把所有不传性别的重载都路由到默认性别Convert(long number)等价于Convert(number, defaultGender)ConvertToOrdinal(int number)等价于ConvertToOrdinal(number, defaultGender)派生类型只需覆写真正随性别变化的成员。从源码结构看Humanizer 采用的是默认性别路由 子类覆写策略调用方不指定性别时库使用该语言配置的默认性别多为阳性从而保证所有 API 重载对调用方而言是一致、可预测的。四、实际用法数字转词ToWords中的性别选择最典型的用法是基数词。以俄语和西班牙语为例示例来自 NumberToWordsExtension.cs 的文档注释// 俄语阳性与阴性词形不同 1.ToWords(GrammaticalGender.Masculine, new CultureInfo(ru)) // - один 1.ToWords(GrammaticalGender.Feminine, new CultureInfo(ru)) // - одна // 希伯来语 1.ToWords(GrammaticalGender.Masculine, new CultureInfo(he)) // - אחד 1.ToWords(GrammaticalGender.Feminine, new CultureInfo(he)) // - אחת // 西班牙语结合 WordForm 使用 21.ToWords(WordForm.Normal, GrammaticalGender.Masculine, new CultureInfo(es)) // - veintiuno 21.ToWords(WordForm.Abbreviation, GrammaticalGender.Masculine, new CultureInfo(es)) // - veintiún 21.ToWords(WordForm.Normal, GrammaticalGender.Feminine, new CultureInfo(es)) // - veintiuna测试侧同样印证了这些行为NumberWordOverloadTests.cs 对多个 locale 逐一断言number.ToWords(GrammaticalGender.Feminine, culture)的输出CoverageGapTests.cs 断言西班牙语1.ToWords(WordForm.Abbreviation, GrammaticalGender.Masculine)为un、1.ToWords(GrammaticalGender.Feminine)为una。五、实际用法序数词ToOrdinalWords / Ordinalize中的性别选择序数词是性别区分最明显的一类输出。Humanizer 在两条 API 路径上都支持性别参数5.1 数字转序数词ToOrdinalWords// 巴西葡萄牙语见 NumberToWordsExtension.cs 文档注释 1.ToOrdinalWords(GrammaticalGender.Masculine, new CultureInfo(pt-BR)) // - primeiro 1.ToOrdinalWords(GrammaticalGender.Feminine, new CultureInfo(pt-BR)) // - primeira // 西班牙语结合 WordForm 区分完整形与缩写形 3.ToOrdinalWords(GrammaticalGender.Masculine, WordForm.Normal, new CultureInfo(es)) // - tercero 3.ToOrdinalWords(GrammaticalGender.Masculine, WordForm.Abbreviation, new CultureInfo(es)) // - tercer 3.ToOrdinalWords(GrammaticalGender.Feminine, WordForm.Normal, new CultureInfo(es)) // - terceraCoverageGapTests.cs 用理论数据验证了西班牙语序数的性别行为1.ToOrdinalWords(Masculine, Abbreviation, es)为primer而1.ToOrdinalWords(Feminine, es)为primera。5.2 字符串序数化Ordinalize对int、long或数字字符串可以使用Ordinalize重载。以巴西葡萄牙语和西班牙语为例见 OrdinalizeExtensions.cs 的文档注释1.Ordinalize(GrammaticalGender.Masculine) // - 1º 1.Ordinalize(GrammaticalGender.Feminine) // - 1ª // 西班牙语正常形/缩写形 × 性别 1.Ordinalize(GrammaticalGender.Masculine, WordForm.Abbreviation) // - 1.er如 Vivo en el 1.er piso 1.Ordinalize(GrammaticalGender.Masculine, WordForm.Normal) // - 1.º 1.Ordinalize(GrammaticalGender.Feminine, WordForm.Normal) // - 1.ª另外从 OrdinalizeExtensions.cs 和 OrdinalizeTests.cs 可以看到对于超出int范围的long数字库会回退到数字转词 语言后缀的策略此时同样需要传入性别例如印地语2_147_483_648L.Ordinalize(GrammaticalGender.Masculine, hi-IN)等于number.ToWords(GrammaticalGender.Masculine, hi-IN) वाँ。六、性别无关语言的静默退化并非所有语言都区分语法性别。对于英语、中文等性别无关语言传入GrammaticalGender不会报错而是被静默忽略、始终输出同一个词形。这类语言对应的转换器通常继承自 GenderlessNumberToWordsConverter.cs其性别感知重载与无性别重载产出相同结果。测试用例明确覆盖了这种退化行为GermanGenderedOrdinalTests.cs德语序数1.、2.、23.在三种性别下输出完全一致并用Ordinalize_GenderInvariant_AllGendersMatch断言三种性别与阳性结果相同PolishGenderedOrdinalTests.cs波兰语序数同样是1.风格性别不影响结果。值得注意的是德语本身拥有中性名词其序数后缀统一为1.是语言惯例使然——有中性词形与序数随性别变化是两回事具体行为取决于各语言转换器的实现。同理OrdinalizeTests.cs 显示en-US下2147483651L.Ordinalize(GrammaticalGender.Masculine)与不带性别参数的调用输出均为2147483651st证明性别参数在英语中完全不起作用。七、最佳实践与注意事项只对性别感知语言显式传性别对ru、he、es、pt-BR、pl、cs、sr等语言务必根据实际名词性别传入Masculine/Feminine必要时Neuter否则会落到默认性别多为阳性产生语法错误的文案对en、zh等语言可以不传或统一传值以保持代码路径一致。结合 WordForm 使用西班牙语等语言中性别与词形正常形/缩写形共同决定输出如tercerovstercer两者需要同时指定相关重载可见 NumberToWordsExtension.cs。不要依赖底层数值枚举的 0/1/2 数值是 C# 默认赋值属于实现细节测试用(GrammaticalGender)999验证了未定义值会触发ArgumentOutOfRangeException业务代码应始终使用具名成员。culture 参数可选所有性别感知重载都支持CultureInfo? culture null默认使用当前线程文化跨语言输出时建议显式传入避免受运行环境文化影响。语义边界GrammaticalGender只负责输出词形词法/形态层与性别中性文案无关——Humanizer 不会做性别中立改写它只是在既有语言规则内生成正确性别形式。八、小结GrammaticalGender是 Humanizer 多语言本地化能力中词形正确性的关键开关通过 GrammaticalGender.cs 定义的三个成员配合 INumberToWordsConverter.cs 的性别感知接口、GenderedNumberToWordsConverter.cs 的默认性别路由以及 NumberToWordsExtension.cs 和 OrdinalizeExtensions.cs 提供的一组重载开发者可以在俄语、希伯来语、西班牙语、巴西葡萄牙语等语言中生成与名词性别严格一致的数字和序数文案而在英语等性别无关语言中无需任何额外处理。写多语言文案时请根据实际名词性别显式传入该枚举即可获得语法正确的本地化输出。赞分享开发工具【免费下载链接】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 语法性别GrammaticalGender枚举深度解析让多语言数字与序数输出更地道Humanizer 语法性别GrammaticalGender枚举深度解析让多语言数字与序数输出更地道 本篇技术指南围绕 Humanizer 的 Gram开发工具Humanizer数字转文字面向开发者的终极多语言解决方案Humanizer数字转文字面向开发者的终极多语言解决方案 在当今全球化的软件开发环境中处理多语言数字和文字转换已成为每个开发者的必备技能。 Humaniz开发工具Humanizer 中 GrammaticalGender 枚举详解跨文化控制数字词性与序数词性形的机制Humanizer 中 GrammaticalGender 枚举详解跨文化控制数字词性与序数词性形的机制 本篇围绕 Humanizer 仓库文档 Humani开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考