Repository navigation
Description
Purpose
Replace/correct the localized inflection API introduced by #1888 so Humanizer's established Pluralize/Singularize family works directly on arbitrary caller strings in every supported culture.
This issue is the canonical scope, API/data contract, 102-culture ownership ledger, research-evidence policy, review ledger, and merge gate. It revisits and supersedes the unreleased #1888 PluralizationForms.TryPluralize / TrySingularize implementation that closed #197, replacing its ordinary-caller direction with familiar string APIs.
Approved commons-first delivery amendment — 2026-10-03
The user approved the first cohort: “we can get those in but I want to know how we get the rest. I thought we had online sources... ways to encode them for space”. This changes delivery sequencing and first-release acceptance; it does not cancel the remaining-language goal.
The first activation is one atomic cohort: English, German, French, Spanish, Italian, Portuguese. Each language has100 predeclared core noun concepts (50 software/UI,50 everyday), selected before new inflected forms. All600 core concept bindings must satisfy independently reviewed common-profile gold, including source-certified ambiguous/invariant identity, in both directions and every reachable quantity/display slot. Reuse source-backed facts only for matching frozen concepts/meanings; historical census and approval records remain intact.
An independent reviewer freezes exactly200 distinct noun-type holdout items per language before candidate measurement. Keep original source occurrence weights and complete category gold. Partition gold into T(transformation required), A(source-certified intrinsic ambiguity), I(attested no-change), P(unresolved). Report all type counts and occurrence masses; P must be zero. For each language and direction, sum(correct transformed T weights)/sum(all T weights) must be at least95%, with positive T. Identity abstention earns no T credit. Every frozen A/I/unsafe case must preserve the exact original reference. Every enabled productive direction additionally requires at least100 independent attempted matches and99% correctness, with fixed rule-family coverage and hostile nonmatches. Supplemental attempts fill only the shortfall to100; no dilution, reseeding, holdout memorization or exception embedding.
This replaces the original all91-owner activation and full-corpus95% irregular-occurrence requirements for this first release only. It does not claim original whole-language completion. Keep issue#1892 open for the remaining85 atomic owners and their aliases/descendants, delivered through subsequent explicitly frozen rolling cohorts with the same safety and independent-review bars. Preserve all raw historical census evidence.
Library culture support remains independent of documented inflection feature coverage. Structurally unsafe/unsupported inputs and source-certified conflicts among ordinary COMMON noun readings preserve the exact original reference; no English fallback or false invariant attestation. This is an ordinary-noun profile, without POS/sense detection or universal safety for every privately intended rare/slang/archaic reading. Every locally common conflicting reading remains relevant even beyond the100 seed; seed definitions cannot waive ordinary mass/count conflicts. Genuine aliases use the authored same-language/script-compatible graph; Portuguese owns its pt-PT category override. Included words keep complete, source-backed categories/refinements and unique-reverse arbitration. No caller sense API is added.
Legacy English retains established customization/compound behavior and documented intentional modern preferred-output changes. Its explicit performance baseline is d8568a9: no complete-operation B/op regression and latency regression within max(10%,15ns) on core32/full existing Inflector workloads, both flags/default/custom/compound/quantities, across applicable TFMs. New-engine strict original budgets and original approved baseline remain unchanged; that original baseline's exact reference still requires recovery, never reset.
Production activation waits for independently approved source/core/holdout custody, corrected shared findings, API/reviewer approval, exact-head supported-platform/TFM checks, formatting, pack/package verification, performance/size, trimming/AOT, clean consumer installation and accurate docs. Day-one pilot measures throughput; SourceRecovery stops after day2 with exact gap reporting. Two-working-day English/German demo and one-to-two-week cohort launch are conditional planning targets, not verified estimates or permission to skip checks.
Core frequency-source correction: the fixed English ranking uses authenticated UD English EWT r2.18 commit b7711cce01cdd4f5fcc0a8199b8a50d951b16c0c, train SHA256 d68e06122a702464c613076523d56740f047e5bbe89dd90ec32737e04d952143. Preserve selected IDs, ranks and weights. The separate independent r2.16 test protocol remains fixed; exclude actual training lemma/form overlaps across editions. Tag differences alone do not establish independence.
Later cohorts may use source-certified invariant/N/A evidence only with a genuine positive noun census, positive/hostile attestations and independent review. Missing transformation gold or missing sources never qualify as invariant/N/A.
Original full-language contract retained for follow-on completion
The amendment above controls the first commons-first milestone where its explicit deltas differ. The original contract, evidence and language inventory below remain preserved for the broader follow-on work.
Hard product contract
- Existing
word.Pluralize()andword.Singularize()themselves use the localized engine and invocation-time ambient culture. - Ordinary callers do not supply authored forms, dictionaries, options, services, or
outparameters. - Normal operation always returns a string (or preserves the existing nullable
Pluralizecontract). Unknown, unsafe, unsupported, or ambiguous input returns the exact original value; it does not returnfalseand does not throw as normal control flow. - Every
CultureInfofor whichConfigurator.IsCultureSupportedis true supports every public inflection operation at activation. The 102 generated locale files are data-owner roots, not the exhaustive set of supported descendants.Configurator.IsCultureSupportedand inflection must share one deterministic resolver; same-language, script-compatible descendant ownership is allowed, while English, cross-language, platform-dependent, and partial fallback are forbidden. - English is one locale implementation, never the global fallback.
- Implement as much productive noun-number grammar as can meet the safety gates, then exact exceptions.
- For every locale and direction, the exception lexicon must cover irregular nouns responsible for 95% of observed irregular-noun occurrences under the frozen methodology below. This is token/occurrence coverage, not 95% of dictionary types.
- Quantity-free pluralization selects the locale's conventional dictionary plural. Quantity-aware pluralization selects a number-governed bare display form. Singularization resolves a plural/display form to its preferred lemma.
ToQuantityroutes through the same engine automatically.- Reuse Humanizer's locale YAML, generator, registries, and existing API-specific tests. Do not add a second parity/meta-test framework.
Public API
Keep the existing signatures, parameter names, and nullable-flow annotation, and route them through CultureInfo.CurrentCulture:
[return: NotNullIfNotNull(nameof(word))]
public static string? Pluralize(
this string? word,
bool inputIsKnownToBeSingular = true);
public static string Singularize(
this string word,
bool inputIsKnownToBePlural = true,
bool skipSimpleWords = false);Add culture-last deterministic forms:
[return: NotNullIfNotNull(nameof(word))]
public static string? Pluralize(
this string? word,
bool inputIsKnownToBeSingular,
CultureInfo culture);
public static string Singularize(
this string word,
bool inputIsKnownToBePlural,
bool skipSimpleWords,
CultureInfo culture);Add exactly one public quantity type:
[return: NotNullIfNotNull(nameof(word))]
public static string? Pluralize(
this string? word,
decimal quantity);
[return: NotNullIfNotNull(nameof(word))]
public static string? Pluralize(
this string? word,
decimal quantity,
CultureInfo culture);Examples:
"person".Pluralize();
"person".Pluralize(2m);
"person".Pluralize(2.0m, CultureInfo.GetCultureInfo("en"));
"person".Pluralize(
inputIsKnownToBeSingular: true,
culture: CultureInfo.GetCultureInfo("en"));decimal is deliberate: stored scale preserves CLDR visible-fraction operands, so 1m, 1.0m, and 1.00m may select different categories. Existing ToQuantity(int|long|double, ...) overloads keep their numeric types and use an internal operand representation.
The required terse overload creates an accepted, API-review-blocking v4 source ambiguity:
word.Pluralize(default); // bool or decimal
word.Pluralize(default, culture); // bool or decimalCallers use default(bool), default(decimal), or named inputIsKnownToBeSingular: / quantity: arguments. Added overloads also affect reflection and some untyped method-group binding. These impacts require explicit API approval.
Null and ambient semantics
- No-culture calls read
CultureInfo.CurrentCultureonce at invocation time. Do not useCurrentUICultureand do not capture ambient culture in static state or a cache. - Explicit null
CultureInfothrowsArgumentNullException. Explicit overloads validate culture first, so a null word plus null culture throws forculture. Pluralize(null, ...)with a non-null culture returns null.- Preserve the existing runtime/nullability behavior of
Singularize. - Identity/no-op outcomes return the exact original string reference.
Linguistic semantics
The API accepts any string safely. V1 claims transformations only for:
- A standalone lexical noun.
- A locale-authored exact phrase.
- English compound/token behavior already frozen by existing tests.
Anything else is returned unchanged. No operation translates text or claims POS/sense detection.
- Quantity-free
Pluralizerequests the locale's preferred dictionary plural. - Quantity-aware
Pluralizerequests the preferred bare display form for the selected cardinal category. It never emits the number, article, classifier, preposition, or surrounding agreement. inputIsKnownToBeSingular: trueis the caller's noun/lemma assertion and permits eligible productive forward rules.- With that flag false, only a uniquely recognized singular lexeme changes, except for frozen English compatibility behavior.
- Default
Singularize(inputIsKnownToBePlural: true)permits approved productive reverse rules. With the flag false, require a uniquely recognized form. skipSimpleWordsuses the selected locale's generated skip/exclusion data, not an English suffix assumption.- Homographs, incompatible senses, multiple reverse candidates, unsafe rules, and unknown inputs return the original.
- Every lexeme has a stable ID, noun POS, countability, optional required sense, accepted variants, and one policy-preferred output per slot.
- Countability values are
count,mass,collective, andplural-only.
CLDR is used only to select an authored display slot. It is not evidence for noun case, countability, phrase grammar, or the spelling of a form.
Maintainer-approved amendment (2026-10-02): a selected display category may have bounded, owner-authored, source-backed refinements using the existing exact cardinal operands. Predicates within that category must be disjoint and exhaustive; every reachable refinement has a stable identity, independently reviewed preferred/accepted bare form, and source evidence. This permits quantity-governed forms that CLDR intentionally groups into one category, such as Slovenian integer versus visible-fraction few. Refinements stay within the same selected category and atomic owner; they never retry another category, dictionary plural, language, or bundle. Incomplete refinement data fails closed.
Every refined accepted form participates in the same quantity-free reverse index and collision arbitration. Singularize has no quantity and cannot use a refinement to disambiguate. A covered lexeme must supply every required category and reachable refined output with the original completeness and unique-reverse guarantees. All frozen-denominator, 95% exception-coverage, 100-attempt/99% productive-precision, standalone, platform, performance, independent-review, and global atomic-activation gates remain unchanged. This amendment approves representation expressiveness only; it does not approve any owner packet or partial activation.
A public-complete bundle is either:
invariant: the operation is linguistically attested to preserve the form, with positive and hostile examples; ordisplay-by-category: every reachable CLDR category has an authored preferred bare display form.
A dictionary-only or missing-category bundle may exist only as inert development data. It cannot activate for a supported culture. Runtime never substitutes other, dictionary plural, another category, another word, or a different bundle after owner selection.
Quantity semantics and ToQuantity
- Cardinal operands use absolute quantity;
-1mand1mselect the same category. - Decimal scale is retained exactly.
intandlonguse exact internal operands withv = 0, includinglong.MinValue.- Finite
doubleuses invariant round-trip digits with exponent expansion. Source trailing zeros are unrecoverable (1dand1.0dare identical). NaNand infinities produce internalUnsupported; the noun remains unchanged.- If
formatProvider is CultureInfo culture, that culture owns inflection. Otherwise inflection uses the once-capturedCurrentCulture, while the original provider continues to format the number. ShowQuantityAs.Nonestill uses the actual quantity for noun selection.- Formatting the number must not change category operands.
Unicode, casing, scripts, compounds, and phrases
- Compare transient NFC values; store preferred forms in NFC.
- Well-formed NFC inputs take the allocation-free comparison path.
- Ill-formed UTF-16 returns the exact original without normalization.
- Do not use NFKC, compatibility folding, mark removal, transliteration, or punctuation stripping.
- Changed output uses the preferred stored form plus the locale's declared casing projection.
- If projected output is ordinally identical to input, return the original reference.
- Casing mode is
exact,lower-title-upper, ornone; mixed casing is exact-only. - Exact phrases are allowed. Productive phrase processing is off outside English in v1.
- English keeps only compound behavior frozen by current tests; do not add a general phrase parser.
- Productive rules require a declared compatible script. Common/inherited combining marks are allowed; mixed-script productive matching is not.
Deterministic culture ownership
Generate one reviewed owner graph:
- Canonicalize the requested culture/alias without retaining arbitrary culture objects or misses.
- Select its exact complete bundle when present.
- Invariant culture terminates at identity.
- Otherwise follow only an exact generated alias/owner edge with the same primary language and compatible effective script. The graph explicitly lists every accepted culture name and compatibility alias, plus exclusions and regional overrides; it has no implicit platform-derived descendant set.
- If no complete owner exists, terminate at identity.
Do not discover ownership through platform CultureInfo.Parent. ICU, NLS, and .NET Framework must select the same owner. At activation, Configurator.IsCultureSupported(culture) delegates to this same resolver and returns true exactly when a complete owner exists; it must no longer promise a culture that inflection cannot serve.
A bundle is atomic: category evaluator, capability, scripts, casing, lexemes, rules, exclusions, and source references all come from one owner. There is no per-word/category/rule retry after selection.
Only the en bundle may consult mutable Vocabularies.Default, and only for compatibility after localized exact handling returns Unknown—never Ambiguous or Unsupported. No non-English owner can reach it.
Internal diagnostic status:
internal enum InflectionStatus
{
Exact,
Productive,
Invariant,
Ambiguous,
Unsupported,
Unknown
}Ambiguous, Unsupported, and Unknown map to the exact original public input.
Locale YAML contract
Extend the existing locale YAML rather than introducing another data subsystem:
# Grammar fragment only. Activation also requires the complete evidence described below.
inflection:
capability: display-by-category
scripts: [Latn]
casing: lower-title-upper
phrase-mode: exact-only
lexemes:
- id: en.noun.cactus.plant
pos: noun
countability: count
sense: plant
forms:
singular:
preferred: cactus
accepted: [cactus]
dictionary-plural:
preferred: cactuses
accepted: [cactuses, cacti]
display:
one:
preferred: cactus
accepted: [cactus]
other:
preferred: cactuses
accepted: [cactuses, cacti]
sources: [humanizer-existing-en]
rules:
- id: en.forward.consonant-y
direction: forward
priority: 100
scope:
pos: noun
countability: [count]
token: standalone
scripts: [Latn]
match:
suffix: y
preceding-not: [a, e, i, o, u]
output:
dictionary-plural: "{stem}ies"
display:
one: "{stem}y"
other: "{stem}ies"
hostile-exclusions:
lexemes: []
surfaces: []
reverse:
enabled: true
requires-existing-lexeme: false
sources: [humanizer-existing-en]
sources:
humanizer-existing-en:
kind: project-history
locator: tests/Humanizer.Tests/InflectorTests.cs
revision: repository-commit
credit: Humanizer contributors
Productive-rule DSL is bounded prefix/suffix replacement, not runtime regex. A reverse rule may set requires-existing-lexeme: false only when its morphotactic constraints, exclusions, ambiguity checks, round trip, and frozen held-out precision support safe arbitrary-lexeme use.
The generator rejects duplicate IDs; ill-formed/non-NFC forms; preferred forms outside the accepted set; missing reachable categories; unsupported POS/countability; dangling source references; invalid evidence arithmetic; unmet activation thresholds; empty/unbounded/duplicate rule matches; conflicting priority/specificity; language/script ownership conflicts; and undeclared reverse collisions.
Forward and reverse resolution
Forward precedence:
- Exact accepted whole-string phrase.
- Exact accepted standalone surface / invariant lexeme.
- Exact lexeme preferred output.
- Highest-priority eligible productive rule; specificity/longest affix breaks an otherwise declared ordering.
Unknown.
The generator rejects unresolved ties. There is no global invariant rule layer.
Exact reverse indexes map normalized surface to sets of lexeme IDs. One ID resolves; zero is unknown; more than one is ambiguous unless the records explicitly identify the same lexeme/sense and one preferred reverse. Collision groups are generated, never silently resolved by insertion/sort order.
Productive reverse is an explicitly precision-gated heuristic. It is allowed only when:
- Locale and rule enable reverse.
- Surface is absent from negative/exclusion data.
- Exactly one candidate is generated.
- Forward application of the same rule reproduces the surface.
- Candidate satisfies the rule's script/scope and, when required by that rule, maps to a compatible known lexeme.
- The locale/direction passes its frozen held-out precision gate.
Only canonical/preferred forms are promised to round-trip. Ambiguous accepted alternatives return identity.
Generated runtime representation
Generate one file and one internal data type per locale plus a tiny direct registry:
GeneratedInflection_en.g.cs
GeneratedInflection_fr.g.cs
GeneratedInflection_ru.g.cs
...
GeneratedInflectionRegistry.g.cs
Each locale type owns private arrays, offsets, exact indexes, reverse collision groups, rules, exclusions, and any required comparer in a nested static holder. Selecting one data-bearing owner must not initialize another owner type. Alias/descendant records contain metadata only: accessing an alias initializes exactly its one selected owner bundle, not a second locale-data holder.
Use each string once in private LexemeEntry[] data plus forward/reverse ushort[] indexes (int only if a locale exceeds 65,535 entries). Case-sensitive NFC keys may use ordinal generated sorting. Any locale-ignore-case index must be built/compared under the same runtime comparer; never binary-search build-time ordering under a different platform comparer.
Do not use a central all-locale initializer, Lazy<T>, immutable/frozen collections, runtime reflection, new generated runtime regex, result caches, dynamic owner caches, or runtime collision discovery. The frozen en compatibility path may invoke the existing regex-based Vocabularies.Default; no other owner may do so.
The generator is incremental per locale. Changing one YAML file regenerates that locale's file/type; the registry regenerates only when ownership metadata changes.
All generated metadata still ships in the monolithic assembly. The lazy guarantee is only that unselected runtime indexes/string objects are not initialized. Satellite packs are a later option only if measured deployment footprint requires them; they are not v1.
#1888 migration
Remote verification against current main 42b876dd85a882e3ebee377d36be388b2fbb0b34 and merged PR #1888 confirms that the unreleased public surface is PluralizationForms, including its constructor, Singular/category properties, Invariant, TryPluralize(decimal, CultureInfo, out string?), and TrySingularize(string, out string?). #1888 did not ship a built-in exact string lexicon.
This design replaces that advanced caller-authored-forms surface for the ordinary use case because callers of arbitrary-string Pluralize / Singularize normally do not possess a complete paradigm. Before public activation:
- Remove the unreleased public
PluralizationFormstype and its constructor, properties,Invariant,TryPluralize, andTrySingularizemethods, along with their API approvals and public docs. - Retain the generated CLDR operand/category evaluators internally.
- Move behavior coverage to ordinary
Pluralize,Singularize, andToQuantitycalls; keep focused internal operand/category tests. - Remove caller-authored-form success/failure expectations from
LocalizedInflectionTests. - Add an unreleased changelog note. The latest tagged release at review time is v3.0.10, which predates feat: expose localized pluralization forms #1888; exact-head API review must re-check that no package containing this surface shipped before removal.
This migration does not claim that arbitrary morphology is universally knowable. The familiar methods transform exact lexemes and demonstrably safe locale-owned productive cases; all other inputs preserve identity.
Research evidence and 95% occurrence coverage
Humanizer is self-contained. The NuGet package, source generator, build, tests, and runtime never download or query a corpus, dictionary, language model, or service. Every runtime rule, exception form, exclusion, and owner edge needed by this feature is committed as project-authored locale data and generated into Humanizer. Independently authored expectations remain in the existing API-specific test suites.
External materials are ordinary research inputs only. Maintainers may consult frequency lists, annotated corpora, morphological datasets, national dictionaries, and grammar references to learn factual forms and rules and to measure observed usage. Humanizer does not copy or redistribute definitions, sentences, corpora, models, or wholesale source tables. It commits only project-authored rules/forms, stable citations, and compact exception-level and aggregate evidence counts. This issue requires no pre-access approval, legal-decision ID, source-license manifest, clean-room record, escrow, or external download for activation.
Frozen occurrence methodology
Define the locale grammar, productive rules, API eligibility, token/POS filtering, frequency source, and query/release date before selecting the final exception set. “Irregular” is determined by reviewed locale grammar, not merely by what the current engine misses. Productive-rule defects are fixed as rule defects; invariant lexemes that must block a productive rule count as exceptions.
For locale owner l and direction d, let M(l,d) contain the independently reviewed, API-eligible irregular noun occurrences in the frozen evidence:
- For
Pluralize, weight each eligible dictionary-singular/lemma noun by its observed lemma occurrences. A covered lexeme must contain every preferred dictionary/display slot required by that locale's reachable CLDR categories and every reachable quantity refinement. - For
Singularize, weight each eligible plural/display surface by its observed surface occurrences. A covered surface must resolve uniquely to an accepted preferred lemma. - Exclude proper names, abbreviations, foreign/code-switched material, malformed tokens, and grammatical forms outside the standalone-noun v1 claim. Record the excluded occurrence mass.
Let c(i) be the observed occurrence count and x(i) = 1 only when the embedded exact lexicon returns an accepted result:
ExceptionCoverage(l,d) = Σ(c(i) × x(i)) / Σ(c(i)), i ∈ M(l,d)
When M(l,d) is nonempty, ExceptionCoverage(l,d) must be at least 0.95. This is occurrence coverage, not dictionary-type coverage, and locales are never pooled to pass. When no exception is observed after a positive eligible-noun census/audit, report coverage N/A and activate only with cited evidence that the operation is invariant or productively regular. Identity where gold requires a change is wrong.
Occurrence counts use a census of the frozen frequency source. Manual sampling may be used only to audit the residual regular population for candidate-generation misses; record that selection rule, but it neither substitutes for nor reweights the occurrence denominator. Use separate authoring and final-frequency evidence where available; otherwise freeze a deterministic holdout before tuning.
Each locale YAML commits only:
- methodology version, locale owner, census definition, residual-audit selection rule, and source URL/release or query date, locator, and credit;
- per direction: eligible and excluded occurrence counts, uncovered-irregular occurrence count, and the observed occurrence count/source ID attached to each embedded exception lexeme or surface;
- for an activated productive direction: attempted and correct occurrence counts from the frozen evidence;
- project-authored forms, rules, exclusions, and the source IDs supporting them.
The generator derives coveredIrregularOccurrences by summing occurrence counts only for embedded entries that supply every required output and unique reverse. It derives irregularOccurrences = coveredIrregularOccurrences + uncoveredIrregularOccurrences; these are not caller-authored aggregate claims. The source reviewer checks that the frozen census, residual audit, exclusions, and uncovered count are complete. The generator cannot prove that an external observation was not omitted without importing that external payload, which this design deliberately does not do.
For an activated productive direction:
ProductivePrecision(l,d) = correctOccurrences / attemptedOccurrences
Require at least 100 frozen attempted occurrences and correctOccurrences * 100 >= attemptedOccurrences * 99. A direction with less evidence or lower precision may still activate exact/invariant handling, but not productive rules.
The generator validates nonnegative counts, covered <= irregular <= eligible, correct <= attempted, source references, derived totals, covered * 100 >= irregular * 95 for every nonzero irregular denominator, and the 100-attempt/99%-precision gate for every activated productive direction. Evidence and citations participate in deterministic input validation but are not emitted into runtime locale tables. Review happens in the ordinary pull request; there is no second evidence database, signed audit bundle, or parity framework.
Research source plan
- Leipzig Corpora Collection supplies comparable occurrence frequency across all 87 language roots represented by the 102 locale files. Its automated annotations nominate candidates; they are not the grammar authority.
- Universal Dependencies supplies attested forms, lemmas, noun POS, and number features for roughly 74 roots. UniMorph supplies noun paradigms for roughly 45 roots.
- Current roots with neither a UD treebank nor UniMorph noun data are
bs,ig,km,kok,lo,mn,ms,my,so, andsw. Use cited national dictionaries/corpora or grammar references plus direct linguistic review for those roots; never infer them silently from a related language. - CLDR plural rules select numeric categories only. They are not evidence for noun spellings, cases, countability, or arbitrary-string morphology.
Normal builds and tests use only the committed Humanizer data. Research refreshes are explicit maintainer work and cannot change a build merely because an external source changes.
Canonical 102 generated-locale-root ownership ledger
Rows are fixed and disjoint and enumerate the 102 YAML/generated data roots. They do not replace the generated exact alias/owner ledger used by the shared resolver. The owner/reviewer columns are filled before a batch starts; no ordinal repartitioning. Regional aliases and descendants are accepted only when their exact names appear in the reviewed graph described above.
| Batch | Exact culture IDs | Canonical author | Independent reviewer | Status |
|---|---|---|---|---|
| B1 English | en, en-GB, en-IN, en-US |
Sol | TBD | Unassigned |
| B2 Core Germanic | af, da, de, de-CH, de-LI, lb, nb, nn, nl, sv |
TBD | TBD | Unassigned |
| B3 Icelandic | is |
TBD | TBD | Unassigned |
| B4 Romance | ca, es, fr, fr-BE, fr-CH, gl, it, pt, pt-BR, ro |
TBD | TBD | Unassigned |
| B5 Celtic | cy, ga |
TBD | TBD | Unassigned |
| B6 Hellenic/Balkan analytic | el, sq |
TBD | TBD | Unassigned |
| B7 East Slavic/Baltic | be, lt, lv, ru, uk |
Sol | TBD | Unassigned |
| B8 West Slavic | cs, pl, sk |
Sol | TBD | Unassigned |
| B9 South Slavic | bg, bs, hr, mk, sl, sr, sr-Latn |
Sol | TBD | Unassigned |
| B10 Uralic | et, fi, hu |
TBD | TBD | Unassigned |
| B11 Turkic/Mongolic | az, kk, ky, mn, tk, tr, uz-Cyrl-UZ, uz-Latn-UZ |
Sol | TBD | Unassigned |
| B12 Semitic | ar, he, mt |
Sol | TBD | Unassigned |
| B13 Iranian/Urdu | fa, ku, ps, ur, ur-IN, ur-PK |
Sol | TBD | Unassigned |
| B14 Indo-Aryan | as, bn, gu, hi, kok, mr, ne, or, pa, pa-Arab, si |
Sol | TBD | Unassigned |
| B15 Dravidian | kn, ml, ta, te |
TBD | TBD | Unassigned |
| B16 CJK/mainland Southeast Asia | ja, ko, km, lo, my, th, vi, zh-CN, zh-Hans, zh-Hant |
TBD | TBD | Unassigned |
| B17 Malay/Austronesian | fil, id, ms |
TBD | TBD | Unassigned |
| B18 African | am, ha, ig, so, sw, yo, zu-ZA |
TBD | TBD | Unassigned |
| B19 Isolates/Caucasian | eu, hy, ka |
TBD | TBD | Unassigned |
Reviewed owner aliases include: English variants → en; de-CH/de-LI → de; French variants → fr; pt-BR → pt; Urdu variants → ur; zh-CN → zh-Hans. nn owns its inflection despite any generic locale variantOf metadata. Script-bearing Serbian, Uzbek, Punjabi, and Chinese edges require explicit compatible-script review. pt-PT is already supported through pt parent resolution and already has a direct regional CLDR rule in pt.yml; preserve it as an explicit deterministic regional override of the atomic pt owner. The shared resolver must cover it without platform-parent discovery.
Model and contribution ownership
- Sol owns most implementation and complex analysis: shared runtime, source generator/schema, public API/overload compatibility, reverse ambiguity, difficult locale families, integration, debugging, hostile-finding resolution, and final exact-head reviews.
- Terra may perform bounded substantive locale research/review and straightforward locale batches under a written Sol-authored contract.
- Luna is limited to mechanical inventory, evidence/coverage tables, simple transcription, schema validation, and deterministic checks.
- Sol reviews and integrates every Terra/Luna contribution.
- Locale batch authors cannot approve their own batch. Use disjoint reviewers/cross-review; Sol-authored work also requires another maintainer/domain reviewer.
Staged implementation and merge order
- Freeze/approve this contract: API review, research methodology, runtime layout, budgets, exact owner graph, and canonical owner/reviewer assignment.
- Shared internals (Sol): internal engine, schema validation, per-locale generator, owner graph, diagnostic status, deterministic/fuzz harness integration. Registration remains inert.
- English compatibility (Sol + independent reviewer): route existing English behavior through the
enbundle while preservingVocabularies.Defaultcustomization and frozen compound tests. - Disjoint locale batches: merge inert locale data in the ledger order/declared dependencies; a locale PR may not change shared runtime. Shared defects return to Sol and reset affected approvals/final-test freezes.
- Evidence gate: all 102 root bundles plus every descendant accepted by the shared resolver, per-locale 95% evidence counts and source-citation review, locale cross-review, and generated-data audit.
- Public activation (Sol): existing overload routing, new decimal/culture overloads,
ToQuantity, removal of feat: expose localized pluralization forms #1888 public forms/Try*surface, XML/docs/changelog. - Exact-head release gate: all adversarial reviews, API approval, package/performance/AOT comparison, fuzz/property tests, and full supported-TFM validation.
No production PR opens until stage 1 blockers are resolved. No implementation merges until its exact-head gates pass.
Existing-suite test plan
Extend, replace, or reorganize coverage inside the existing suites:
tests/Humanizer.Tests/InflectorTests.cstests/Humanizer.Tests/LocalizedInflectionTests.cstests/Humanizer.Tests/ToQuantityTests.cs- Existing culture-specific localization folders, generator tests, API approval tests, benchmark/package suites
Do not create a second generated parity/meta-test framework.
Required existing-suite coverage:
- Exact or invariant-appropriate
Pluralize,Pluralize(quantity), andSingularizerows for every one of the 102 generated roots. In the same existing suite, enumerate runtime cultures and assert that every culture for whichConfigurator.IsCultureSupportedis true resolves to a complete expected owner; include exact descendant cases such asfr-FRandpt-PT. - Existing English bool flags, custom
Vocabularies.Default, casing, and compound behavior. - Ambient
CurrentCultureversus explicit override and proof thatCurrentUICulturedoes not select inflection. - Named arguments, typed/default literals, reflection/method groups, nulls, and API-approval baselines.
- Every capability/category; decimal scale; negatives/fractions;
long.MinValue; double exponents;NaN/infinity. ToQuantitywith implicit/explicit culture, non-culture format providers, andShowQuantityAs.None.- Accepted/preferred forms, senses, countability, invariant nouns, exclusions, rule boundaries, and reverse collision/ambiguity.
- Lower/title/upper/mixed case; NFC/NFD; ill-formed UTF-16; combining marks; punctuation; compatible/incompatible/mixed scripts; exact-reference identity.
- Exact phrases and proof that non-English productive phrase processing does not occur.
- Exact owner, aliases, descendant opt-in, same-language/script rejection, terminal identity, platform-independent graph, atomic bundle behavior, and English isolation.
- Unsupported cultures return exact identity and never English.
- Property/fuzz testing for reverse ambiguity, forward/reverse canonical round trips, hostile nonmatches, common-prefix/long input, invalid UTF-16, deterministic generation, and cache bounds.
Performance and package gates
Pin base SHA, SDK/configuration, runner/CPU policy, OS culture engine, and corpus. Measure fresh-process cold paths separately from warmed paths and report ns/op, B/op, Gen0, p50/p95, retained heap, RSS, JIT code, PE/metadata, nupkg, and AOT.
- Warm identity/unknown: exact-reference return, 0 B/op, and no more than
max(10%, 15 ns)slower than pinned baseline. - Warm exact: at most 2× pinned English exact and 1 µs.
- Warm productive forward: at most 2.5× and 2 µs.
- Warm productive reverse: at most 3× and 3 µs at rule ceiling.
- Changed output: result plus at most one normalization/casing temporary; bytes bounded by normalized input plus output.
- Unsupported cold: at most 8 KiB additional allocation and 25% wall-time regression over identity baseline.
- English first use: p95 ≤ 2 ms and ≤ 128 KiB allocated/retained.
- Largest locale first use: p95 ≤ 5 ms and ≤
2 × encoded locale payload + 64 KiBallocated/retained. - One locale access initializes only that locale plus its documented owner; library load initializes none.
- Repeated unknown cultures retain 0 bytes; owner/cache cardinality is bounded by generated bundle IDs.
- Input scaling from 4 KiB through 1 MiB remains below 2.5× time when input doubles and approximately 2× allocated bytes; no superlinear common-prefix behavior.
- Generated source ≤ 5 MiB total and ≤ 256 KiB per syntax tree.
- Clean build median ≤ 20% or 2 seconds regression (whichever is greater); no-op/edit build separately reported; peak compiler RSS ≤ +150 MiB.
- Release
Humanizer.dll≤ +4 MiB; compressed nupkg ≤ +1.5 MiB; NativeAOT verification app ≤ +5 MiB and publish time ≤ +20%. - Trimmed build has no related warnings.
- Test net8/net10/net11, Windows net48, Linux ICU, Windows NLS, JIT, ReadyToRun, trimming, and NativeAOT.
A budget change requires recorded performance-owner and maintainer approval.
Pre-issue hostile-review resolution ledger
Public API / compatibility
- HAPI-001 — Accepted v4: required decimal overload makes untyped
defaultambiguous; typed/named fixes documented and API-gated. - HAPI-002 — Resolved in design: arbitrary input is accepted safely; productive rules are scoped/precision-gated and true unknowns remain identity.
- HAPI-003 — Accepted product contract: quantity call is caller noun intent and returns only a bare display form.
- HAPI-004 — Accepted v4: ambient existing methods change from unconditional English to
CurrentCulture. - HAPI-005 — Resolved: mutable
Vocabularies.Defaultisen-only. - HAPI-006 — Resolved: multi-category and multiple accepted/preferred forms are modeled.
- HAPI-007 — Accepted: public quantity type is deliberately decimal; existing numeric types remain internal through
ToQuantity. - HAPI-008 — Resolved: receiver/culture null behavior is explicit and tested.
- HAPI-009 — Open acceptance gate: reflection/method-group changes need exact-head API approval.
- HAPI-010 — Accepted v4 (2026-07-30): custom
Vocabularies.Defaultentries no longer override newly recognized localized English entries; theenbundle's exact/localized handling takes precedence, and the mutable vocabulary runs only on an EnglishUnknownmiss. Additive custom rules for otherwise unknown English words remain compatible.
Linguistic model
- H-01: universal arbitrary-noun transformation claim narrowed to standalone noun/exact phrase/identity.
- H-02: CLDR limited to category selection.
- H-03: reverse round-trip is not proof; ambiguity/exclusion/precision controls added.
- H-04: 95% metric is frozen per locale/direction under independent gold.
- H-05: dictionary plural non-uniqueness modeled as accepted forms plus one preferred policy form.
- H-06: unsafe head rules removed; exact phrases only outside frozen English behavior.
- H-07: NFC, casing modes, mixed-case behavior, and exact-reference identity specified.
- H-08: quantity result explicitly scoped to bare display form.
- H-09: culture insufficiency resolved by exact owner graph and script guards.
- H-10: decimal/internal numeric semantics specified.
Supported-culture fallback
- HF-01: variant ownership selects one atomic bundle; no leakage.
- HF-02: effective-script compatibility required.
- HF-03: generated edges replace platform parent discovery.
- HF-04: parent owner must opt into each descendant.
- HF-05: identity terminates; no English/global/per-category fallback.
- HF-06: mutable vocabulary remains English-only.
- HF-07:
CurrentCulturecaptured exactly once per operation;CurrentUICultureignored. - HF-08:
ToQuantityseparates numeric provider from inflection owner. - HF-09: identity bypasses normalization/legacy processing and preserves the original reference.
Research evidence and claims
-
EVID-01: Humanizer ships all required data; build, tests, and runtime have no corpus, model, service, or download dependency.
-
EVID-02: “95%” means the per-locale, per-direction
ExceptionCoveragemetric above; locales cannot be pooled. -
EVID-03: independently reviewed locale grammar defines exception-required nouns; the source reviewer validates the frozen denominator rather than allowing the engine to choose it.
-
EVID-04: the generator derives the covered numerator from per-entry counts and validates arithmetic; positive eligible evidence, residual auditing, and source review guard against an omitted or candidate-biased denominator.
-
EVID-05: a zero irregular denominator is reported
N/Aand requires cited invariant/productively-regular evidence. -
EVID-06: only project-authored rules/forms, citations, and compact exception-level and aggregate counts are committed; no external payload or separate audit system ships.
Package/runtime performance
- PERF-001: one generated file/type per locale; no central initializer.
- PERF-002: claim narrowed to selected runtime-index initialization; all metadata still ships and is measured.
- PERF-003: comparer/sorting semantics made platform-consistent.
- PERF-004: normalize at most once; invalid UTF-16/identity behavior and proportional allocation stated.
- PERF-005: bounded rules, max lengths, common-prefix/large-input scaling gates.
- PERF-006: generated explicit reverse collision groups; no unstable insertion-order choice.
- PERF-007: fixed precedence and generation-time tie rejection.
- PERF-008: only fixed generated bundle IDs may be retained; no arbitrary culture/miss/result cache.
- PERF-009: per-locale holders and parallel cold-start tests prevent global serialization.
- PERF-010: trimming, AOT, net48, and direct-reference behavior gated.
- PERF-011: locale-granular incremental output/build measurements.
- PERF-012: DLL metadata/PE, nupkg, heap/RSS/JIT/AOT measured independently.
- PERF-013: 95% and size reported per locale/direction, never hidden by aggregate.
- PERF-014: fresh-process cold branches and absolute/relative warmed ceilings pinned.
- PERF-015: empty/duplicate/unbounded rules rejected; deterministic ordering and hostile nonmatches tested.
Pre-merge adversarial blockers
- Exact-head public API/compatibility approval.
- Exact-head Sol/code-owner review plus an independent reviewer for Sol-authored work.
- Generated-data audit; deterministic diff; no hand-edited output.
- Every locale batch cross-reviewed by someone other than its author; difficult families receive Sol review.
- Ambiguity/reverse-inflection fuzz/property tests and hostile nonmatch review.
- Supported-culture/no-English-fallback audit across all 102 root IDs and every runtime descendant accepted by
Configurator.IsCultureSupported. - Per-locale 95% occurrence evidence and source citations reviewed; no external payload or runtime/build download.
- Package-size, cold/warm performance, cache, trimming, and NativeAOT comparisons.
- Full supported-TFM validation at the exact head.
-
dotnet format Humanizer.slnx --verify-no-changes --verbosity diagnostic. - Release pack plus existing package verification.
No locale batch author may self-approve. No PR merges while any applicable blocker remains open.
Acceptance criteria
- Exact public signatures and intentional v4 compatibility impacts are approved.
- Existing no-culture methods use invocation-time
CurrentCulture. - All 102 generated locale roots have one complete accepted atomic bundle and exact existing-suite assertions for quantity-free plural, quantity-aware plural, and singularization; every descendant accepted by
Configurator.IsCultureSupportedresolves through the same deterministic owner graph and is covered in the existing suite. - No supported culture returns/throws NotImplemented/NotSupported for these operations, falls back to English, or activates partial/dictionary-only data.
- Unsupported cultures, unsafe inputs, and ambiguity return the exact original reference.
- Productive forward rules handle arbitrary asserted noun lemmas where safe; productive reverse rules handle arbitrary plural forms where their locale-specific precision gate permits it.
- Every locale/direction passes the 95% occurrence-weighted exception-coverage gate; every activated productive direction passes the productive precision gate; invariant behavior has linguistic attestation.
-
ToQuantityuses actual quantity and inferred/explicit culture through the same engine. - Existing English behavior and
Vocabularies.Defaultcustomization remain compatible except for approved ambient v4 behavior. - feat: expose localized pluralization forms #1888 public
PluralizationForms,TryPluralize, andTrySingularizesurface/tests/docs are absent before activation; internal CLDR evaluators remain. - XML docs/readme/changelog describe scope, ambiguity, quantity operands, identity, and no-English fallback.
- All API, generated-data, research-evidence, locale review, fuzz, package, performance, AOT, formatting, and TFM gates pass on the exact head.
Explicit non-goals
- General POS or sense detection.
- Full grammatical count phrases.
- Articles, adjectives, verbs, classifiers, case/gender selection, or surrounding agreement.
- General sentence or productive phrase inflection.
- Ordinal categories.
- Translation or transliteration.
- Public caller-authored dictionaries/forms or service objects.
- Exhaustive dictionaries.
- Public CLDR category evaluators.
- Runtime/build-time external data, corpora, models, services, or downloads.
Implementation plan
The canonical implementation-ready plan is maintained in this issue's plan comment. It is intentionally preserved as planning evidence outside the repository and is not committed to main.
Execution is staged from pinned current-main baseline 42b876dd85a882e3ebee377d36be388b2fbb0b34:
- Reconcile the preserved pre-fix(localization): complete supported culture APIs #1893 patch manually; do not transplant or rebase it over current main.
- Extend the existing locale YAML/source-generator pipeline with atomic active/inert bundles and one deterministic accepted-culture resolution record used by culture support, built-in localization, and inflection.
- Emit lazy per-owner data and implement exact/ambiguous/unsupported terminals, bounded productive rules, Unicode/script/casing safety, and exact numeric operands.
- Complete and independently review all B1–B19 locale/evidence batches before routing the familiar string APIs and
ToQuantity. - Rewrite the existing API-specific suites to enumerate all 102 roots and every accepted runtime culture, then update API approvals, docs, examples, and language coverage.
- Run exact-head TFM/platform, format, docs, pack, package, performance, size, trimming, ReadyToRun, NativeAOT, and adversarial review gates before publication.
The 95% per-locale/per-direction irregular-occurrence mandate remains hard. Humanizer ships no corpus, model, service, extra package, or runtime/build download. Ordinary generated tables are the semantic reference; more than 500 KiB of raw morphology in any assembly triggers a MorphPack investigation, while the compressed nupkg increase must remain at or below 1.5 MiB. No second parity framework is introduced.
Activity
clairernovotny commentedon Jul 30, 2026
#1892 implementation plan — planning evidence, not a repository file
Pinned baseline:
42b876dd85a882e3ebee377d36be388b2fbb0b34Plan SHA-256:
c1a74e32989c06d0678470ba8dc0f5242cce859714b10d50bdd0eea1ae6971d5Exact source size: 45,394 bytes
This comment preserves the full implementation plan as planning evidence. The issue's “Implementation plan” section designates this comment as the canonical plan location; the plan is intentionally not committed to the repository.
Revised 2026-07-30 (plan review): recorded the approved
Vocabularies.Defaultrecognized-entry precedence change as user-approved (issue ledger HAPI-010), settled the plan location as this comment per the amended issue, acknowledged the deliberate U5-before-U4 deviation from the issue's staged merge order, specified locale-ownedskipSimpleWordsskip data (R8/U2/U4), aligned status naming to the issue'sInflectionStatusenum, addedShowQuantityAs.Nonetest coverage, and named the unreleased-changelog-note location.title: Localized Inflection for 102 Locale Roots
type: feat
date: 2026-07-29
deepened: 2026-07-29
revised: 2026-07-30
artifact_contract: ce-unified-plan/v1
artifact_readiness: implementation-ready
product_contract_source: ce-plan-bootstrap
execution: code
Localized Inflection for 102 Locale Roots
Goal Capsule
Deliver issue #1892: make Humanizer's familiar string
PluralizeandSingularizeAPIs locale-owned, quantity-aware, safe for arbitrary input, and complete for all 102 generated locale roots plus every supported descendant, while keeping Humanizer standalone and within the approved package budgets.The issue is the product authority. This plan is its implementation map. If they conflict, stop and reconcile the issue before changing code. Implement from pinned current-main baseline
42b876dd85a882e3ebee377d36be388b2fbb0b34; the preserved 116-file5f60worktree patch is salvage input, not an accepted design or transplant candidate.Execution is deliberately staged. Locale data may be reviewed while inert, but the public API cannot activate until the shared resolver, all accepted cultures, evidence gates, API approvals, existing-suite coverage, performance/package measurements, and exact-head reviews pass together. The task owns publication through merge, issue close/credit, and cleanup of only its own worktree/topic references.
Stop rather than weaken any of these gates:
Unknownmay take the R4 legacy-vocabulary path first;Humanizernupkg increase no greater than 1.5 MiB, with the other exact performance and package limits in R18.Product Contract
Summary
Humanizer currently exposes established English-oriented
string.Pluralize()andstring.Singularize()methods, while the unreleased #1888 surface asks callers to constructPluralizationFormsand callTryPluralize/TrySingularize. #1892 removes that caller-authored model. Ordinary strings become the public surface for localized noun-number inflection. Humanizer embeds the compact authored grammar and exceptions it needs; research corpora remain generator-time evidence only and are never shipped.Requirements
Public API and compatibility
Pluralize(string?, bool)andSingularize(string, bool, bool)signatures, parameter names, nullable flow, and existing runtime null behavior. No-culture calls captureCultureInfo.CurrentCultureonce per invocation.decimalquantity overloads from Localized arbitrary-string Pluralize/Singularize with locale-owned grammar #1892. Explicit null culture throws forculturebefore null-receiver handling.PluralizationForms,TryPluralize, andTrySingularizeplus their tests/docs/API entries. Retain internal cardinal plural operands, rules, and categories.skipSimpleWords, and released outputs.Unknownis an internal engine miss, not a final public outcome.Vocabularies.Defaultis English-only and may handle that miss; it must never run afterAmbiguous,Unsupported, or another safety rejection, or for non-English owners. Additive custom rules for otherwise unknown English words remain compatible; overriding newly recognized localized entries is an approved v4 precedence change.ToQuantity(int|long|double, ...)overloads keep their signatures and number formatting behavior but select noun forms through the same internal engine. ACultureInfoformat provider owns inflection; any other provider formats only the number.Linguistic and safety behavior
Unknowncompatibility handling.skipSimpleWordsconsults the selected locale's generated skip/exclusion data, never an English suffix assumption; frozen Englishenbehavior is preserved. Known already-target forms remain identical.Ambiguousterminals; runtime never chooses by insertion order.Culture ownership and coverage
Configurator.IsCultureSupported, and built-in localizer lookup use the same generated resolution decision. Remove platformCultureInfo.Parentdiscovery from built-in resolution without changing caller-created custom registry behavior.Configurator.IsCultureSupportedis true has a complete inflection owner. The existing localized inflection suite itself enumerates all 102 roots and every accepted runtime culture; do not add a separate parity/meta-test framework.Evidence and embedded data
N/Airregular coverage requires a positive eligible census plus cited invariant/productively regular evidence.Quality, size, and delivery
Humanizer.dll+4 MiB, compressed nupkg +1.5 MiB, NativeAOT app +5 MiB, and publish-time +20%. An ordinary generated representation is the reference. More than 500 KiB of raw morphology in any assembly triggers investigation of MorphPack; it does not automatically select it.Acceptance Examples
"person".Pluralize()underen"person".Pluralize(2m, en)otherdisplay form"person".Pluralize(1.0m, en)inputIsKnownToBeSingular: falseSingularizeArgumentNullExceptionforculturePluralize(null, ..., validCulture)nulldecimal.MinValueorlong.MinValuedoublethroughToQuantityNaNor infinity throughToQuantityde-CH,fr-FR,pt-PT, orzh-CNScope Boundaries
This work does not implement POS/sense detection, translation, transliteration, general sentence/phrase grammar, articles, classifiers, surrounding agreement, ordinal categories, exhaustive dictionaries, public CLDR evaluators, caller-authored locale dictionaries, or a runtime morphology service. Exact authored phrases are allowed; productive non-English phrase parsing is not.
Dependencies
origin/mainat42b876dd85a882e3ebee377d36be388b2fbb0b34, which includes fix(localization): complete supported culture APIs #1893.91d524468aa03285f497d79e9e87cf67b06625f44b941fd10261a06bbc6a337b.Success Criteria
All R1–R20 are evidenced at one exact head. In particular, all accepted cultures share one deterministic complete owner resolver, every locale/direction meets the hard 95% gate or its explicitly valid
N/Acondition, arbitrary unsafe input is exact identity, no external artifact ships or downloads, and all package/performance limits pass without hiding locale-level failures in aggregates.Sources
ARCHITECTURE.md— source-generator and locale-profile conventionsPRODUCT.md— familiar APIs and all-or-nothing localization posturesrc/Humanizer/InflectorExtensions.cs— released string API entry pointssrc/Humanizer/ToQuantityExtensions.cs— existing numeric and formatting flowssrc/Humanizer/Inflections/LocalizedInflectionCatalog.cs— current cardinal-category resolversrc/Humanizer.SourceGenerators/Generators/ProfileCatalogs/InflectionCatalogInput.cs— current inflection generationsrc/Humanizer.SourceGenerators/Generators/LocaleRegistryInput.cs— current supported-culture generationsrc/Humanizer/Configuration/LocaliserRegistry.cs— built-in and custom localizer fallback behaviortests/Humanizer.Tests/LocalizedInflectionTests.cs— existing API-specific localized suitePlanning Contract
Key Technical Decisions
Configurator.IsCultureSupported, and built-in registries. CustomLocaliserRegistry<T>instances keep their existing caller-controlled fallback semantics.FrozenDictionaryand runtime collision discovery.ToQuantitycaptures owner/operands before any provider callback and routes all numeric overloads through the same selection seam.KTD6, the 1.5 MiB compressed package cap, and R4's recognized-entry precedence change (custom
Vocabularies.Defaultentries no longer overriding newly recognized localized English entries) are user-approved (session-settled: user-directed — confirmed 2026-07-30); record that precedence change in the issue's HAPI accepted-v4 ledger at exact-head API review. R15's 95% mandate, R17's standalone requirement, R6's exact identity, and the no-second-framework constraint are user-directed and are not implementation tuning knobs.High-Level Technical Design
flowchart LR Y["102 locale YAML roots<br/>forms, rules, evidence, owners"] --> P["Canonical parser + validators"] P --> H["One lazy generated holder<br/>per atomic data owner"] P --> G["Exact accepted-name → owner graph"] G --> C["Configurator.IsCultureSupported"] G --> L["Built-in localizer resolution"] G --> E["Localized inflection engine"] H --> E O["Exact numeric operands"] --> E E --> A["Pluralize / Singularize / ToQuantity"] A --> I["Changed result or exact original reference"]The owner graph is generated data, not a platform query. Requested culture names resolve to a fixed owner ID or terminal identity. Only the selected holder initializes. That holder exposes complete capability metadata plus exact indexes and bounded rules; no other locale is consulted.
flowchart TD S["Capture culture once; validate explicit culture"] --> R{"Generated owner?"} R -- "No / invariant / excluded" --> ID["Return original reference"] R -- "Yes" --> X{"Valid UTF-16 and eligible exact token/phrase?"} X -- "Exact terminal" --> T{"Unique output differs ordinally?"} T -- "No" --> ID T -- "Yes" --> OUT["Project casing and return output"] X -- "Ambiguous / unsupported" --> ID X -- "No exact terminal" --> Q{"Direction flag allows productive rule?"} Q -- "No" --> EN{"Owner is en and status is Unknown?"} Q -- "Yes" --> U{"Productive evaluation result?"} U -- "Unique" --> OUT U -- "Unknown" --> EN U -- "Unsafe / ambiguous / unsupported" --> ID EN -- "Yes" --> V["Vocabularies.Default compatibility path"] EN -- "No" --> IDFor quantity-aware calls, exact recognition may start from any unique accepted surface and project the quantity-selected display slot. Productive forward rules require caller lemma intent; productive reverse rules require the approved singularization flag. This keeps
"man"and"men"usable throughToQuantitywithout treating arbitrary plural text as a lemma.Representation Decision Gate
flowchart TD B["Emit ordinary per-owner tables"] --> M["Measure every target assembly and package"] M --> K{"Raw morphology > 500 KiB<br/>in any assembly?"} K -- "No" --> KEEP["Keep ordinary tables"] K -- "Yes" --> MP["Prototype MorphPack from same logical model"] MP --> D{"All inputs/statuses differential-equal<br/>and exact-head savings material?"} D -- "No" --> KEEP D -- "Yes" --> P["Select MorphPack; rerun all gates"]The 500 KiB value is an investigation threshold, not a budget substitution. DLL, nupkg, generated source, cold allocation, trimming, AOT, and build-time gates remain independent.
System-Wide Impact
default, reflection, and method groups.ToQuantitynoun selection changes from±1heuristics to exact cardinal operands while number formatting stays source-compatible.Risks and Mitigations
Sequencing
flowchart LR U1["U1 Baseline + compatibility"] --> U2["U2 Schema + owner graph"] U2 --> U3["U3 Generator + runtime"] U3 --> U5["U5 Locale/evidence batches"] U5 --> U4["U4 English reconciliation + public integration"] U4 --> U6["U6 Existing suites + docs"] U6 --> U7["U7 Size/perf + exact-head delivery"]Shared runtime/schema defects found during locale work return to U2/U3 and invalidate affected reviews. Do not patch shared behavior inside a locale-only batch. English-bundle preparation may begin during U5, but it remains inert; public routing starts only in U4 after every U5 owner and evidence gate is complete. This deliberately deviates from the issue's staged merge order (stage 3 English compatibility before stage 4 locale batches) by consolidating issue stages 3 and 6 into U4 and running locale batches first; confirm this accepted reordering at the stage-1 contract freeze.
Implementation Units
U1. Establish the current-main baseline and compatibility ledger
Goal: Create a clean canonical implementation state without losing useful preserved work or treating it as architecture.
Requirements: R1–R5, R19, R20; KTD1, KTD9.
Files:
src/Humanizer/InflectorExtensions.cs,src/Humanizer/ToQuantityExtensions.cs,src/Humanizer/PluralizationForms.cs,tests/Humanizer.Tests/InflectorTests.cs,tests/Humanizer.Tests/LocalizedInflectionTests.cs,tests/Humanizer.Tests/ToQuantityTests.cs,tests/Humanizer.Tests/ApiApprover/.Approach:
42b876dd; do not rewrite the existing dirty branch/worktree.ToQuantity.Test scenarios: Existing English suite unchanged; null runtime behavior; additive and overriding custom vocabulary cases; typed/named/default overload source probes;
PluralizationFormsabsent from the intended API.Verification: A baseline characterization commit is green before localized routing changes. The preserved patch hash remains recorded and no #1893 file is replaced wholesale.
U2. Extend the locale schema and generate one exact atomic owner graph
Goal: Make culture support deterministic and ensure a supported name can select only one complete owner.
Requirements: R9, R12–R17; KTD2, KTD3, KTD7.
Files:
src/Humanizer.SourceGenerators/Common/LocaleYamlCatalog.cs,src/Humanizer.SourceGenerators/Generators/LocaleRegistryInput.cs,src/Humanizer.SourceGenerators/Generators/ProfileCatalogs/InflectionCatalogInput.cs,src/Humanizer.SourceGenerators/Models/,src/Humanizer/Configuration/Configurator.cs,src/Humanizer/Configuration/LocaliserRegistry.cs,tests/Humanizer.SourceGenerators.Tests/SourceGenerators/CanonicalLocaleSchemaTests.cs,tests/Humanizer.SourceGenerators.Tests/SourceGenerators/HumanizerSourceGeneratorTests*.cs.Approach:
skipSimpleWordsskip data), casing, phrase mode, lexemes, stable IDs, countability/sense, forms, bounded rules, and source/evidence summaries.pt-PT), and special script owners (Serbian, Uzbek, Punjabi, Chinese). Emit a fixed accepted-name resolver with noCultureInfo.Parent.Configurator.IsCultureSupportedand built-in localizer resolution through that resolver. Preserve caller-created registry semantics.N/A, productive aggregate thresholds, and cited sources. Inert bundles parse but cannot resolve; changing them to active applies every gate.Test scenarios: All exact aliases and representative descendants; case variants; unknown same-language descendants; invariant/custom cultures;
nn,de-CH,fr-CH,pt-PT,zh-CN; Serbian/Uzbek/Punjabi scripts; cycles/cross-language edges; partial inert succeeds and active fails; exact 95% boundary; zero denominator; two-rule aggregate evidence; inline-sequence rejection or support.Verification: Generator snapshots are deterministic. The same owner ledger drives support, built-in localization, and inflection. No built-in path discovers a parent at runtime.
U3. Emit locale-granular data and implement the bounded inflection engine
Goal: Provide a lazy, allocation-conscious engine whose uncertainty terminals are exact identity.
Requirements: R6–R11, R18; KTD4–KTD8.
Files:
src/Humanizer.SourceGenerators/HumanizerSourceGenerator.cs,src/Humanizer.SourceGenerators/Generators/ProfileCatalogs/InflectionCatalogInput.cs,src/Humanizer/Inflections/LocalizedInflectionCatalog.cs,src/Humanizer/Localisation/GrammaticalNumber/CardinalPluralOperands.cs,src/Humanizer/Localisation/GrammaticalNumber/CardinalPluralRules.cs, new narrowly scoped internal inflection types undersrc/Humanizer/Inflections/, source-generator tests, andtests/Humanizer.Tests/LocalizedInflectionTests.cs.Approach:
.Collect()pipeline. Emit one lazy holder and syntax tree per atomic data owner plus a small registry.InflectionStatusenum (Exact,Productive,Invariant,Ambiguous,Unsupported,Unknown); “unique” in the design flowcharts maps to theExact/Productivestatuses. Generate normalized stored forms, collision groups, fixed rule precedence, and minimal script/casing data.NaN/infinity as internalUnsupported.Test scenarios: Every status/direction/flag; preferred and accepted forms; reverse collisions; rule precedence/ties;
decimal.MinValue,long.MinValue, scale, negatives, fractions, exponent doubles,NaN/infinity; NFC/NFD, invalid UTF-16, combining marks, supplementary characters, Turkish I, Greek sigma, German ß, apostrophes/hyphens, long common-prefix input, mixed script; exact-reference outcomes; parallel one-owner cold start.Verification: Generated output is deterministic and below source-tree ceilings. Runtime differential tests are platform-independent, unknown culture retention is zero, and only the selected owner initializes.
U4. Reconcile English and activate the familiar public APIs
Goal: Route released string APIs and
ToQuantitythrough the localized engine while preserving approved English behavior and removing #1888.Requirements: R1–R8; KTD8, KTD9.
Files:
src/Humanizer/InflectorExtensions.cs,src/Humanizer/ToQuantityExtensions.cs,src/Humanizer/Inflections/Vocabulary.cs,src/Humanizer/PluralizationForms.cs(delete),src/Humanizer/Locales/en*.yml,tests/Humanizer.Tests/InflectorTests.cs,tests/Humanizer.Tests/ToQuantityTests.cs,tests/Humanizer.Tests/LocalizedInflectionTests.cs,tests/Humanizer.Tests/ApiApprover/*.verified.txt.Approach:
CurrentCultureonce.ToQuantityto capture owner and operands before formatting/provider callbacks, keeping all public numeric overloads and formatting output intact.Vocabularies.Defaultonly for EnglishUnknown. Treat localized exact/ambiguous/unsupported results as terminal.PluralizationFormsand update all TFM API approvals. Explicitly reviewdefault, named arguments, method groups, and reflection.Test scenarios: Byte-for-byte released English rows;
"cactus","cactuses", and"cacti"across flags, quantities, andToQuantity; null/culture validation ordering; ambient versus UI culture; provider mutation of ambient culture; custom unknown English rule; recognized override decision;skipSimpleWordsunder a non-English owner uses locale-generated skip data, not English suffix heuristics;ToQuantitywithShowQuantityAs.Nonestill selects the noun form from the actual quantity; non-English never enters vocabulary; API compile/reflection baselines.Verification: API review explicitly accepts the v4 overload ambiguities. #1888 surface is absent. Existing English outputs remain exact except approved ambient-culture and recognized-entry precedence changes.
U5. Author and cross-review all locale bundles and evidence
Goal: Supply complete, compact, reviewed grammar for all 102 required roots and every accepted owner edge.
Requirements: R9–R17, R20; KTD2, KTD3, KTD7.
Files:
src/Humanizer/Locales/*.yml, existing culture-specific tests undertests/Humanizer.Tests/Localisation/, and generator-derived evidence/coverage assertions in the existing localized inflection suite.Approach:
Test scenarios: Exact or invariant-appropriate quantity-free plural, quantity-aware plural, and singular rows for all 102 roots; all accepted aliases/descendants; capability categories; exclusions; senses/countability; hostile nonmatches; each locale's residual irregular audit; author/reviewer separation.
Verification: Every root and accepted runtime culture resolves to exactly one active atomic owner, each locale/direction reports ≥95% or valid
N/A, every productive direction reports ≥100 attempts and ≥99%, and no external payload appears in source, build artifacts, or package.U6. Complete existing-suite, documentation, and API proof
Goal: Make the new behavior reviewable without creating a second testing or documentation system.
Requirements: R1–R20.
Files:
tests/Humanizer.Tests/LocalizedInflectionTests.cs,tests/Humanizer.Tests/InflectorTests.cs,tests/Humanizer.Tests/ToQuantityTests.cs,tests/Humanizer.Tests/Localisation/SupportedCultureTests.cs,tests/Humanizer.SourceGenerators.Tests/,tests/Humanizer.Tests/ApiApprover/,readme.md,website/docs/scenarios/inflection-and-quantities.mdx,website/docs/_examples/scenarios-inflection/Program.cs,website/docs/contributing/adding-or-updating-a-locale.mdx,website/docs/languages/,website/docs/languages/using-cultures.mdx,website/docs/upgrading/main-preview.mdx,website/scenario-api-contract.json,tools/docs/generate-language-coverage.ps1.Approach:
website/docs/upgrading/main-preview.mdx(the repository has no standalone changelog file). Explain standalone embedded data, exact identity, no-English fallback, quantity operands, flags, culture capture, accepteddefaultambiguity, 95% evidence methodology, owner roots versus accepted descendants, and how contributors add/review evidence.Test scenarios: All examples compile; docs scenario/API manifests agree; all-culture rows remain in the API-specific suite; language coverage exposes roots and accepted owners accurately; no public docs expose internal statuses or packing.
Verification: Docs tooling, examples, API approvals, and existing suites agree on one public contract. Repository search finds no surviving public
PluralizationForms/Try*reference.U7. Measure representation, run exact-head gates, and deliver
Goal: Prove the selected representation and exact head satisfy every functional, package, performance, platform, review, and publication gate.
Requirements: R18–R20; KTD6, KTD9.
Files:
src/Benchmarks/InflectorBenchmarks.cs,src/Benchmarks/ToQuantityBenchmarks.cs, existing package/AOT/docs verification scripts, CI definitions only where required for repeatability, and PR/issue metadata.Approach:
Test scenarios: 500 KiB boundary; clear-versus-packed differential if applicable; all performance branches; clean/no-op/edit build; five target assemblies; compressed package; PE/metadata; cold first use; repeated unknown cultures; long input; trimmed/AOT/R2R; exact-head rerun after final change.
Verification: Every command and measurement in the Verification Contract is recorded against the merged head. Issue #1892 is closed with credit, and task-owned cleanup leaves no useful or unrelated work deleted.
Verification Contract
Run focused commands while units are active, then rerun the complete matrix at the exact publication head. Microsoft Testing Platform filters use
--filter-class,--filter-method, or--filter-namespace.Focused development
Adjust exact generated test project/namespace names to the current solution after U1 investigation; do not substitute legacy VSTest filter syntax.
Exact-head functional and formatting matrix
Run
net48on Windows only:Run the same owner/inflection differential corpus on Linux ICU, Windows NLS, and .NET Framework. No accepted culture may select a different owner or result.
Docs, examples, package, and deployment shapes
Confirm script parameters from their current help/source before execution. The package verification script primarily covers analyzers, so record DLL/nupkg/NativeAOT sizes separately.
Mandatory measurements
max(10%, 15 ns)slower than baseline.2 × payload + 64 KiB.Humanizer.dll≤+4 MiB; compressed nupkg ≤+1.5 MiB; NativeAOT app ≤+5 MiB and publish time ≤+20%.Review gates
default, reflection, method groups, nullability, and published-package evidence.Definition of Done
ToQuantityAPIs use the engine; English approved behavior holds; feat: expose localized pluralization forms #1888 public surface is removed and API review is approved.N/A, and productive directions meet their evidence gate.clairernovotny commentedon Aug 3, 2026
Status update — 2026-08-03
All ten evidence lanes (B1, B7, B8, B9, B11–B14, U5 schema, and U5 source) now have terminal Sol-approved/clean handoffs that were independently custody-verified. B8 r8 is the accepted corrective handoff (archive SHA-256 7784e24682ba1e674188c6006566a096ff0c41b3e6ae9a030a39ea7f15f912e1); cs/pl/sk remain inert.
The authenticated live main is cc337be. Read-only current-main revalidation found no locale YAML changes from the reviewed baseline; the applicable source-generator/schema checks passed on net10/net11, and the localization/runtime/cardinal-operand checks passed on net8/net10/net11.
The canonical ledger remains 91 atomic owners, 11 aliases, 53 authoring-ready, and 38 inactive. The all-owner activation gate is therefore not authorized: no YAML projection, partial activation, or English fallback was made. The remaining owners stay fail-closed pending authoritative row-level evidence, collision/arbitration closure, and a subsequent all-owner atomic review. Issue #1892 remains open.
clairernovotny commentedon Aug 3, 2026
Status update — capped source refresh complete (2026-08-03)
Three independent read-only Luna audits (South Asian, Slavic/Turkic, and Complex/U5) finished against authenticated live main
cc337be1937868ca5311f0a628c19b08ba34d4a1. They found no new activation-grade row-level evidence: newly observed dictionary portals lack complete reproducible sense/countability/display/collision joins, and existing route blockers remain.The canonical disposition is unchanged: 91 atomic owners, 11 aliases, 53 ready, 38 inactive;
activationAuthorized=false. No locale YAML, partial projection, English fallback, repository write, or PR was made. #1892 remains open pending authoritative evidence for the inactive owners and a subsequent all-owner atomic review.clairernovotny commentedon Oct 2, 2026
Execution resumed through the explicitly authorized implementation, review, merge, release, documentation, consumer-verification and closeout endpoint. Current authenticated main at kickoff:
ffc2b77c0f30d2fb176875841424379319d0ae9b.Recovered byte-exact original coordinator ledger, four corrective lane archives, the July30 inactive matrix, and the original all42 R4 archive (SHA256
9cbab68e93a40c2e37f6f81ce27a5d30125d836abd6e12eee940296898cb0629). Full packets and source assignments for42 owners are now durably preserved outside temporary storage;49 original full packets and the latest v3 approved-owner manifest remain missing. All91 owners/102 roots/11 aliases/579 accepted names have explicit custody/source dispositions. July30 51/40 and August3 38/53 partitions are distinct historical snapshots; no historical readiness has been promoted.Independent source review found recovered B8 and Slovenian originals explicitly lack frozen irregular censuses and derived coverage approval. Morphological candidate rows, verifier passes and aggregate counts are not activation evidence. Current complete-owner approvals remain zero. The global activation gate remains closed; no partial activation or English fallback was made.
The maintainer-authorized bounded quantity-refinement amendment is recorded in this issue while preserving every original coverage, precision, performance, standalone and independent-review gate. Independent review of the derived-evidence schema repair is complete, with net10/net11 generator suites393/0/0 each; publication and integrated-head review remain pending. Public API/docs integration and final platform/performance/release/consumer gates remain incomplete. The issue stays open.
clairernovotny commentedon Oct 3, 2026
Approved commons-first delivery amendment — 2026-10-03
The user approved the first cohort: “we can get those in but I want to know how we get the rest. I thought we had online sources... ways to encode them for space”. This changes delivery sequencing and first-release acceptance; it does not cancel the remaining-language goal.
The first activation is one atomic cohort: English, German, French, Spanish, Italian, Portuguese. Each language has100 predeclared core noun concepts (50 software/UI,50 everyday), selected before new inflected forms. All600 core concept bindings must satisfy independently reviewed common-profile gold, including source-certified ambiguous/invariant identity, in both directions and every reachable quantity/display slot. Reuse source-backed facts only for matching frozen concepts/meanings; historical census and approval records remain intact.
An independent reviewer freezes exactly200 distinct noun-type holdout items per language before candidate measurement. Keep original source occurrence weights and complete category gold. Partition gold into T(transformation required), A(source-certified intrinsic ambiguity), I(attested no-change), P(unresolved). Report all type counts and occurrence masses; P must be zero. For each language and direction, sum(correct transformed T weights)/sum(all T weights) must be at least95%, with positive T. Identity abstention earns no T credit. Every frozen A/I/unsafe case must preserve the exact original reference. Every enabled productive direction additionally requires at least100 independent attempted matches and99% correctness, with fixed rule-family coverage and hostile nonmatches. Supplemental attempts fill only the shortfall to100; no dilution, reseeding, holdout memorization or exception embedding.
This replaces the original all91-owner activation and full-corpus95% irregular-occurrence requirements for this first release only. It does not claim original whole-language completion. Keep issue#1892 open for the remaining85 atomic owners and their aliases/descendants, delivered through subsequent explicitly frozen rolling cohorts with the same safety and independent-review bars. Preserve all raw historical census evidence.
Library culture support remains independent of documented inflection feature coverage. Structurally unsafe/unsupported inputs and source-certified conflicts among ordinary COMMON noun readings preserve the exact original reference; no English fallback or false invariant attestation. This is an ordinary-noun profile, without POS/sense detection or universal safety for every privately intended rare/slang/archaic reading. Every locally common conflicting reading remains relevant even beyond the100 seed; seed definitions cannot waive ordinary mass/count conflicts. Genuine aliases use the authored same-language/script-compatible graph; Portuguese owns its pt-PT category override. Included words keep complete, source-backed categories/refinements and unique-reverse arbitration. No caller sense API is added.
Legacy English retains established customization/compound behavior and documented intentional modern preferred-output changes. Its explicit performance baseline is d8568a9: no complete-operation B/op regression and latency regression within max(10%,15ns) on core32/full existing Inflector workloads, both flags/default/custom/compound/quantities, across applicable TFMs. New-engine strict original budgets and original approved baseline remain unchanged; that original baseline's exact reference still requires recovery, never reset.
Production activation waits for independently approved source/core/holdout custody, corrected shared findings, API/reviewer approval, exact-head supported-platform/TFM checks, formatting, pack/package verification, performance/size, trimming/AOT, clean consumer installation and accurate docs. Day-one pilot measures throughput; SourceRecovery stops after day2 with exact gap reporting. Two-working-day English/German demo and one-to-two-week cohort launch are conditional planning targets, not verified estimates or permission to skip checks.
Core frequency-source correction: the fixed English ranking uses authenticated UD English EWT r2.18 commit b7711cce01cdd4f5fcc0a8199b8a50d951b16c0c, train SHA256 d68e06122a702464c613076523d56740f047e5bbe89dd90ec32737e04d952143. Preserve selected IDs, ranks and weights. The separate independent r2.16 test protocol remains fixed; exclude actual training lemma/form overlaps across editions. Tag differences alone do not establish independence.
Later cohorts may use source-certified invariant/N/A evidence only with a genuine positive noun census, positive/hostile attestations and independent review. Missing transformation gold or missing sources never qualify as invariant/N/A.