Skip to content

Localized arbitrary-string Pluralize/Singularize with locale-owned grammar #1892

Description

@clairernovotny

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() and word.Singularize() themselves use the localized engine and invocation-time ambient culture.
  • Ordinary callers do not supply authored forms, dictionaries, options, services, or out parameters.
  • Normal operation always returns a string (or preserves the existing nullable Pluralize contract). Unknown, unsafe, unsupported, or ambiguous input returns the exact original value; it does not return false and does not throw as normal control flow.
  • Every CultureInfo for which Configurator.IsCultureSupported is 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.IsCultureSupported and 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.
  • ToQuantity routes 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 decimal

Callers 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.CurrentCulture once at invocation time. Do not use CurrentUICulture and do not capture ambient culture in static state or a cache.
  • Explicit null CultureInfo throws ArgumentNullException. Explicit overloads validate culture first, so a null word plus null culture throws for culture.
  • 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:

  1. A standalone lexical noun.
  2. A locale-authored exact phrase.
  3. 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 Pluralize requests the locale's preferred dictionary plural.
  • Quantity-aware Pluralize requests the preferred bare display form for the selected cardinal category. It never emits the number, article, classifier, preposition, or surrounding agreement.
  • inputIsKnownToBeSingular: true is 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.
  • skipSimpleWords uses 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, and plural-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; or
  • display-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; -1m and 1m select the same category.
  • Decimal scale is retained exactly.
  • int and long use exact internal operands with v = 0, including long.MinValue.
  • Finite double uses invariant round-trip digits with exponent expansion. Source trailing zeros are unrecoverable (1d and 1.0d are identical).
  • NaN and infinities produce internal Unsupported; the noun remains unchanged.
  • If formatProvider is CultureInfo culture, that culture owns inflection. Otherwise inflection uses the once-captured CurrentCulture, while the original provider continues to format the number.
  • ShowQuantityAs.None still 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, or none; 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:

  1. Canonicalize the requested culture/alias without retaining arbitrary culture objects or misses.
  2. Select its exact complete bundle when present.
  3. Invariant culture terminates at identity.
  4. 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.
  5. 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:

  1. Exact accepted whole-string phrase.
  2. Exact accepted standalone surface / invariant lexeme.
  3. Exact lexeme preferred output.
  4. Highest-priority eligible productive rule; specificity/longest affix breaks an otherwise declared ordering.
  5. 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:

  1. Locale and rule enable reverse.
  2. Surface is absent from negative/exclusion data.
  3. Exactly one candidate is generated.
  4. Forward application of the same rule reproduces the surface.
  5. Candidate satisfies the rule's script/scope and, when required by that rule, maps to a compatible known lexeme.
  6. 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 PluralizationForms type and its constructor, properties, Invariant, TryPluralize, and TrySingularize methods, along with their API approvals and public docs.
  • Retain the generated CLDR operand/category evaluators internally.
  • Move behavior coverage to ordinary Pluralize, Singularize, and ToQuantity calls; 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, and sw. 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

  1. Freeze/approve this contract: API review, research methodology, runtime layout, budgets, exact owner graph, and canonical owner/reviewer assignment.
  2. Shared internals (Sol): internal engine, schema validation, per-locale generator, owner graph, diagnostic status, deterministic/fuzz harness integration. Registration remains inert.
  3. English compatibility (Sol + independent reviewer): route existing English behavior through the en bundle while preserving Vocabularies.Default customization and frozen compound tests.
  4. 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.
  5. 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.
  6. 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.
  7. 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.cs
  • tests/Humanizer.Tests/LocalizedInflectionTests.cs
  • tests/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), and Singularize rows for every one of the 102 generated roots. In the same existing suite, enumerate runtime cultures and assert that every culture for which Configurator.IsCultureSupported is true resolves to a complete expected owner; include exact descendant cases such as fr-FR and pt-PT.
  • Existing English bool flags, custom Vocabularies.Default, casing, and compound behavior.
  • Ambient CurrentCulture versus explicit override and proof that CurrentUICulture does 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.
  • ToQuantity with implicit/explicit culture, non-culture format providers, and ShowQuantityAs.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 KiB allocated/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 default ambiguous; 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.Default is en-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.Default entries no longer override newly recognized localized English entries; the en bundle's exact/localized handling takes precedence, and the mutable vocabulary runs only on an English Unknown miss. 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: CurrentCulture captured exactly once per operation; CurrentUICulture ignored.
  • HF-08: ToQuantity separates 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 ExceptionCoverage metric 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/A and 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.IsCultureSupported resolves 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.
  • ToQuantity uses actual quantity and inferred/explicit culture through the same engine.
  • Existing English behavior and Vocabularies.Default customization remain compatible except for approved ambient v4 behavior.
  • feat: expose localized pluralization forms #1888 public PluralizationForms, TryPluralize, and TrySingularize surface/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:

  1. Reconcile the preserved pre-fix(localization): complete supported culture APIs #1893 patch manually; do not transplant or rebase it over current main.
  2. 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.
  3. Emit lazy per-owner data and implement exact/ambiguous/unsupported terminals, bounded productive rules, Unicode/script/casing safety, and exact numeric operands.
  4. Complete and independently review all B1–B19 locale/evidence batches before routing the familiar string APIs and ToQuantity.
  5. 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.
  6. 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

  1. added this to the v4.0 milestone on Jul 29, 2026
  2. added
    enhancementAdds or improves user-facing functionality
    localisationChanges translations, locale data, or culture-specific behavior
    on Jul 29, 2026
  3. clairernovotny commented on Jul 30, 2026

    @clairernovotny
    MemberAuthor

    #1892 implementation plan — planning evidence, not a repository file

    Pinned baseline: 42b876dd85a882e3ebee377d36be388b2fbb0b34

    Plan SHA-256: c1a74e32989c06d0678470ba8dc0f5242cce859714b10d50bdd0eea1ae6971d5

    Exact 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.Default recognized-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-owned skipSimpleWords skip data (R8/U2/U4), aligned status naming to the issue's InflectionStatus enum, added ShowQuantityAs.None test 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 Pluralize and Singularize APIs 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-file 5f60 worktree 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:

    • independently frozen 95% irregular-occurrence coverage for every locale and direction;
    • exact identity for final unresolved, unsafe, unsupported, or ambiguous input; an internal English-engine Unknown may take the R4 legacy-vocabulary path first;
    • one generated atomic owner graph, with no English, cross-language, platform-parent, partial, or category fallback;
    • no runtime/build download, external corpus, model, service, or extra package;
    • no second parity framework, runtime lexicon service, or speculative compression system;
    • compressed Humanizer nupkg 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() and string.Singularize() methods, while the unreleased #1888 surface asks callers to construct PluralizationForms and call TryPluralize/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

    • R1 — Familiar API. Preserve the released Pluralize(string?, bool) and Singularize(string, bool, bool) signatures, parameter names, nullable flow, and existing runtime null behavior. No-culture calls capture CultureInfo.CurrentCulture once per invocation.
    • R2 — Deterministic overloads. Add culture-last bool overloads and exactly the approved decimal quantity overloads from Localized arbitrary-string Pluralize/Singularize with locale-owned grammar #1892. Explicit null culture throws for culture before null-receiver handling.
    • R3 — Remove the unreleased surface. Remove public PluralizationForms, TryPluralize, and TrySingularize plus their tests/docs/API entries. Retain internal cardinal plural operands, rules, and categories.
    • R4 — English compatibility. Preserve frozen English compounds, flags, casing, skipSimpleWords, and released outputs. Unknown is an internal engine miss, not a final public outcome. Vocabularies.Default is English-only and may handle that miss; it must never run after Ambiguous, 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.
    • R5 — Quantity integration. Existing ToQuantity(int|long|double, ...) overloads keep their signatures and number formatting behavior but select noun forms through the same internal engine. A CultureInfo format provider owns inflection; any other provider formats only the number.

    Linguistic and safety behavior

    • R6 — Safe arbitrary input. Every normal operation returns a result or the existing nullable result. Unsafe, unsupported, ambiguous, ill-formed, ineligible, or finally unresolved input returns the exact original value and reference rather than throwing or falling through to English. The only intermediate miss path is R4's English-owner Unknown compatibility handling.
    • R7 — Defined directions. Quantity-free pluralization selects the preferred dictionary plural. Quantity-aware pluralization selects the preferred bare display form for the CLDR cardinal category. Singularization maps a uniquely recognized plural/display form to the preferred lemma.
    • R8 — Flag matrix. A true pluralization flag is the caller's lemma assertion and may use an approved forward rule; false permits only a uniquely recognized singular except frozen English behavior. A true singularization flag may use an approved reverse rule; false requires a unique exact form. skipSimpleWords consults the selected locale's generated skip/exclusion data, never an English suffix assumption; frozen English en behavior is preserved. Known already-target forms remain identical.
    • R9 — Atomic complete bundles. An active owner is either attested invariant or has every reachable category, exact forms, rules, exclusions, scripts, casing, evidence, and source references required by its capability. Dictionary-only or incomplete data can exist only as explicitly inert, unregistered development data.
    • R10 — Unicode and token safety. Use transient NFC comparison, stored NFC preferred forms, declared casing projection, and a pinned generated minimal Unicode script table. Invalid UTF-16, mixed script, unsafe casing expansion, punctuation/whitespace/digits outside authored exact forms, and non-English productive phrases are identity.
    • R11 — Deterministic ambiguity. Stable lexeme IDs, POS, countability, optional sense, accepted forms, and preferred outputs determine exact lookup. Reverse collisions and incompatible senses are generated explicit Ambiguous terminals; runtime never chooses by insertion order.

    Culture ownership and coverage

    • R12 — One exact owner graph. Check in and generate one reviewed accepted-culture-name to atomic-owner ledger. The 102 YAML IDs are required accepted roots, not necessarily 102 distinct data shards. Explicit same-language/script-compatible aliases and descendants may share an owner; invariant, excluded, cross-language, or unknown names terminate at identity.
    • R13 — Shared resolution. Inflection, Configurator.IsCultureSupported, and built-in localizer lookup use the same generated resolution decision. Remove platform CultureInfo.Parent discovery from built-in resolution without changing caller-created custom registry behavior.
    • R14 — Complete supported surface. Every culture for which Configurator.IsCultureSupported is 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

    • R15 — 95% exception coverage. For each locale and direction, exact embedded exceptions cover at least 95% of observed irregular-noun occurrences in an independently frozen, cited denominator. Select coverage by direction-specific surface observations before deduplicating physical lexeme storage. Do not count productive-rule matches in the exception numerator.
    • R16 — Productive precision. Each activated productive direction has at least 100 frozen attempts and at least 99% aggregate correctness for that locale/direction, with per-rule diagnostics retained. N/A irregular coverage requires a positive eligible census plus cited invariant/productively regular evidence.
    • R17 — Standalone artifact. Commit only project-authored compact forms/rules, counts, source references, and derived evidence totals. Normal builds, tests, packs, and runtime use no downloaded corpus, dataset, service, model, or additional NuGet package. UD, UniMorph, Leipzig, dictionaries, and grammars are evidence sources, not redistributable runtime payloads.

    Quality, size, and delivery

    • R18 — Exact budgets. Enforce the issue's cold/warm latency and allocation gates, locale-lazy initialization, bounded retention, long-input scaling, generated-source ceilings, build/RSS ceilings, 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.
    • R19 — Supported validation. Pass API approval, generator tests, existing runtime suites on net8/net10/net11, Windows net48, ICU/NLS differential coverage, formatting, docs checks, Release pack/package verification, JIT/ReadyToRun, trimming, and NativeAOT at the exact head.
    • R20 — Reviewed delivery. Every locale batch has a named independent reviewer, no author self-approves, shared defects reset affected approvals, and the final PR merges only after exact-head adversarial review. Close/update Localized arbitrary-string Pluralize/Singularize with locale-owned grammar #1892 with credit and remove only task-owned clean unused refs afterward.

    Acceptance Examples

    Situation Required result
    "person".Pluralize() under en Existing released English result and casing behavior
    "person".Pluralize(2m, en) Preferred bare other display form
    "person".Pluralize(1.0m, en) Category selected from preserved decimal scale
    Known already-plural input with inputIsKnownToBeSingular: false Original reference
    Unique plural/display surface passed to Singularize Preferred lemma
    Reverse collision, incompatible sense, or unsafe productive match Original reference
    Unsupported culture or invariant culture Original reference; no English processing
    Explicit null culture, even with null receiver ArgumentNullException for culture
    Pluralize(null, ..., validCulture) null
    decimal.MinValue or long.MinValue Absolute operands without overflowing
    Finite exponent-form double through ToQuantity Exact invariant round-trip operand expansion before formatting
    NaN or infinity through ToQuantity Noun remains identical
    Non-culture format provider mutates ambient culture while formatting Inflection still uses the once-captured original culture
    de-CH, fr-FR, pt-PT, or zh-CN Explicit generated owner/override; no platform parent walk
    Mixed-script or ill-formed UTF-16 token Original reference

    Scope 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

    • Start implementation from current origin/main at 42b876dd85a882e3ebee377d36be388b2fbb0b34, which includes fix(localization): complete supported culture APIs #1893.
    • Confirm against published stable and prerelease packages—not tags alone—that feat: expose localized pluralization forms #1888's public surface never shipped before deleting it.
    • Preserve the existing dirty 5f60 worktree until a clean current-main implementation branch exists and every useful hunk has been classified. Recorded tracked diff SHA-256: 91d524468aa03285f497d79e9e87cf67b06625f44b941fd10261a06bbc6a337b.
    • Locale authors and independent reviewers must be assigned before their B1–B19 batch begins.
    • Plan location settled (2026-07-30). The issue's “Implementation plan” section designates this issue comment as the canonical plan location; the plan is intentionally not committed to the repository.

    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/A condition, 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

    • Issue #1892 canonical contract
    • ARCHITECTURE.md — source-generator and locale-profile conventions
    • PRODUCT.md — familiar APIs and all-or-nothing localization posture
    • src/Humanizer/InflectorExtensions.cs — released string API entry points
    • src/Humanizer/ToQuantityExtensions.cs — existing numeric and formatting flows
    • src/Humanizer/Inflections/LocalizedInflectionCatalog.cs — current cardinal-category resolver
    • src/Humanizer.SourceGenerators/Generators/ProfileCatalogs/InflectionCatalogInput.cs — current inflection generation
    • src/Humanizer.SourceGenerators/Generators/LocaleRegistryInput.cs — current supported-culture generation
    • src/Humanizer/Configuration/LocaliserRegistry.cs — built-in and custom localizer fallback behavior
    • tests/Humanizer.Tests/LocalizedInflectionTests.cs — existing API-specific localized suite
    • CLDR cardinal plural rules, Universal Dependencies, UniMorph, and Leipzig Corpora Collection — generator-time evidence boundaries only

    Planning Contract

    Key Technical Decisions

    • KTD1 — Rebuild on current main; salvage manually. The preserved patch is feat: expose localized pluralization forms #1888-era work against pre-fix(localization): complete supported culture APIs #1893 code. Do not apply, merge, or rebase it wholesale. Salvage only behavior tests, cardinal operand/category cases, validation ideas such as reachable-category/NFC checks, and the inventory of obsolete API/docs. Reimplement against current main.
    • KTD2 — One authored owner ledger. Add accepted names, owner, effective script, exclusions, and regional overrides to the existing canonical locale model. Generate an ordinal direct resolver used by inflection, Configurator.IsCultureSupported, and built-in registries. Custom LocaliserRegistry<T> instances keep their existing caller-controlled fallback semantics.
    • KTD3 — Atomic replacement, not recursive inflection merge. An authored inflection bundle replaces inherited inflection data wholesale. Alias-only roots carry ownership metadata but do not duplicate or partially merge runtime tables. Inert data is structurally valid but absent from the public resolver; activation applies all completeness/evidence/review gates at once.
    • KTD4 — Locale-granular generation. Parse and validate locale definitions independently, emit one lazy generated inflection holder/syntax tree per data owner, and collect only compact owner metadata into the registry. Avoid the current all-locale central FrozenDictionary and runtime collision discovery.
    • KTD5 — Generated decisions, small runtime. The generator freezes exact forward/reverse terminals, ambiguity groups, rule ordering, exclusions, normalized stored forms, and minimal Unicode script/casing data. Runtime performs owner resolution, one bounded lookup/rule pass, and projection; it does not normalize data, discover collisions, walk cultures, or retain arbitrary misses.
    • KTD6 — Ordinary tables first; conditional MorphPack. This user-approved sequence keeps typed generated tables as the semantic reference. Measure raw morphology per assembly. Only when it exceeds 500 KiB investigate MorphPack and select it only after exact differential proof plus material exact-head savings. MorphPack, if needed, uses a UTF-16 pool, lemma-once records, single-splice form patches, packed categories, sorted exact indexes, explicit status/collision terminals, and fixed rule records. Do not add inner compression or an FST unless measurements cross the documented 25,000-surface or 16-bit-index ceiling and a separate review approves it.
    • KTD7 — Surface-weighted evidence. Compute the 95% cutoff on direction-specific observed surfaces, then deduplicate storage. Enforce the canonical issue's productive gate per locale/direction, retaining per-rule diagnostics without silently strengthening the threshold.
    • KTD8 — One operand seam. Widen internal cardinal operands to represent exact integers, scaled decimals, and expanded finite doubles without absolute-value overflow. ToQuantity captures owner/operands before any provider callback and routes all numeric overloads through the same selection seam.
    • KTD9 — Public activation last. Build and validate inert internals and locale batches first. Remove feat: expose localized pluralization forms #1888 and route familiar APIs only after all accepted cultures activate together and API, compatibility, evidence, package, and performance gates pass.

    KTD6, the 1.5 MiB compressed package cap, and R4's recognized-entry precedence change (custom Vocabularies.Default entries 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"]
    
    Loading

    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" --> ID
    
    Loading

    For 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 through ToQuantity without 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"]
    
    Loading

    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

    • The locale schema gains authored ownership, atomic activation, morphology, evidence, and minimal Unicode declarations.
    • Incremental generation changes from one collected inflection catalog to locale-granular output plus a compact registry.
    • Built-in culture support and localizer resolution stop relying on platform parents; custom registries remain untouched.
    • Public API overload resolution changes intentionally around untyped default, reflection, and method groups.
    • ToQuantity noun selection changes from ±1 heuristics to exact cardinal operands while number formatting stays source-compatible.
    • Documentation coverage must distinguish the 102 checked-in roots from accepted culture names and their selected owners.

    Risks and Mitigations

    Risk Mitigation
    102-locale research becomes an unreviewable data dump Use fixed B1–B19 batches, schema-derived evidence summaries, named disjoint reviewers, and inert merges
    Parent/alias behavior differs across ICU, NLS, and net48 Generate all accepted edges and test the same ledger on every platform
    Exact data silently hides ambiguity Emit explicit direction-specific collision terminals and reject generation-time precedence ties
    Productive rules overclaim arbitrary strings Precise token/script grammar, exclusions, frozen ≥99% evidence, bounded whole-token rules, identity on uncertainty
    English custom vocabulary compatibility is overstated Test additive unknown customization and document recognized-form precedence as an approved v4 change
    Central initialization or generated-source blow-up Per-owner holders and syntax trees, compact registry, exact size/build measurements
    Premature packing adds decoder complexity Ordinary tables remain the reference; MorphPack requires measured trigger and differential proof
    Preserved patch overwrites #1893 Create a clean current-main writer and copy only individually reviewed ideas/tests
    Evidence licensing leaks payloads into the package Store citations/counts/project-authored results only; no third-party corpora or generated corpus excerpts

    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"]
    
    Loading

    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:

    1. Create the canonical writer from pinned baseline 42b876dd; do not rewrite the existing dirty branch/worktree.
    2. Verify published stable and prerelease packages do not contain feat: expose localized pluralization forms #1888. Record the package/version evidence in the PR.
    3. Inventory every feat: expose localized pluralization forms #1888 API/test/doc/API-approval entry that must disappear.
    4. Characterize released string APIs byte-for-byte across existing English cases, flags, casing, compounds, nulls, customization, and ToQuantity.
    5. Review the preserved patch hunk by hunk. Port only tests/ideas that still express Localized arbitrary-string Pluralize/Singularize with locale-owned grammar #1892 behavior; leave its caller-authored API and central runtime behind.

    Test scenarios: Existing English suite unchanged; null runtime behavior; additive and overriding custom vocabulary cases; typed/named/default overload source probes; PluralizationForms absent 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:

    1. Extend the existing locale model for active/inert capability, accepted culture names, exact owner, effective scripts, exclusions/overrides (including skipSimpleWords skip data), casing, phrase mode, lexemes, stable IDs, countability/sense, forms, bounded rules, and source/evidence summaries.
    2. Author sequence values using the parser's existing block-list syntax unless inline-sequence support is deliberately added with canonical-schema tests.
    3. Change inflection inheritance so an authored bundle replaces its parent atomically; aliases carry only ownership metadata.
    4. Validate graph uniqueness, same-language/script compatibility, cycles, explicit regional overrides (pt-PT), and special script owners (Serbian, Uzbek, Punjabi, Chinese). Emit a fixed accepted-name resolver with no CultureInfo.Parent.
    5. Route Configurator.IsCultureSupported and built-in localizer resolution through that resolver. Preserve caller-created registry semantics.
    6. Validate stable IDs, NFC, complete reachable categories/invariant proof, collision groups, rule bounds/order, surface-weighted 95% arithmetic, positive-census 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 under src/Humanizer/Inflections/, source-generator tests, and tests/Humanizer.Tests/LocalizedInflectionTests.cs.

    Approach:

    1. Split locale inflection output from the all-locale .Collect() pipeline. Emit one lazy holder and syntax tree per atomic data owner plus a small registry.
    2. Generate sorted exact forward/reverse entries with explicit outcomes aligned to the issue's internal InflectionStatus enum (Exact, Productive, Invariant, Ambiguous, Unsupported, Unknown); “unique” in the design flowcharts maps to the Exact/Productive statuses. Generate normalized stored forms, collision groups, fixed rule precedence, and minimal script/casing data.
    3. Implement the runtime operation as: capture/resolve owner; reject invalid UTF-16; transient NFC comparison if needed; exact terminal; optional bounded productive rule; casing projection; return original reference whenever unchanged or uncertain.
    4. Pin the Unicode data version used for minimal script classification. Define whole-token eligibility for letters plus permitted Common/Inherited marks; punctuation, whitespace, digits, mixed script, unsafe expansions, and phrases are exact-only.
    5. Widen cardinal operands without negating minimum numeric values. Preserve decimal scale; expand finite double round-trip exponent digits; represent NaN/infinity as internal Unsupported.
    6. Keep caches bounded to generated owner IDs and lazy holders. Never retain arbitrary culture objects, misses, normalized input, or results.

    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 ToQuantity through 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:

    1. Build the English atomic bundle from behavior frozen by existing tests; preserve compounds and English-only compatibility rules.
    2. Add the approved culture-last and decimal overloads with exact XML docs and nullable annotations. Ambient calls capture CurrentCulture once.
    3. Define quantity projection from any uniquely recognized accepted surface; permit productive forward only with caller lemma intent.
    4. Refactor ToQuantity to capture owner and operands before formatting/provider callbacks, keeping all public numeric overloads and formatting output intact.
    5. Allow Vocabularies.Default only for English Unknown. Treat localized exact/ambiguous/unsupported results as terminal.
    6. Delete public PluralizationForms and update all TFM API approvals. Explicitly review default, named arguments, method groups, and reflection.

    Test scenarios: Byte-for-byte released English rows; "cactus", "cactuses", and "cacti" across flags, quantities, and ToQuantity; null/culture validation ordering; ambient versus UI culture; provider mutation of ambient culture; custom unknown English rule; recognized override decision; skipSimpleWords under a non-English owner uses locale-generated skip data, not English suffix heuristics; ToQuantity with ShowQuantityAs.None still 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 under tests/Humanizer.Tests/Localisation/, and generator-derived evidence/coverage assertions in the existing localized inflection suite.

    Approach:

    1. Assign author and independent reviewer for B1–B19 before work starts. A locale-only batch cannot change shared runtime/schema.
    2. For each direction, freeze the eligible census and irregular surface denominator from cited sources; author compact exceptions/rules; record aggregate counts and per-rule diagnostics without embedding source corpora.
    3. Prefer attested invariant bundles where grammar preserves noun number rather than manufacturing rules. Use dictionaries/grammars and direct review for roots without UD/UniMorph evidence.
    4. Activate a bundle only when every reachable category, rule precision gate, exception coverage gate, collision review, source citation, and accepted owner edge is complete.
    5. Run generated summaries per locale/direction so aggregate success cannot hide a failing locale.

    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:

    1. Rewrite the existing localized inflection suite around ordinary string APIs. It directly enumerates all roots and accepted runtime cultures and asserts expected owner/completeness; reuse fix(localization): complete supported culture APIs #1893 data patterns but do not introduce a new parity framework.
    2. Add focused source-generator/schema tests and property/fuzz cases inside existing projects for determinism, ambiguity, round trips, hostile nonmatches, invalid UTF-16, and cache bounds.
    3. Update all API approvals and scenario contract entries; remove all public feat: expose localized pluralization forms #1888 references.
    4. Record the issue-required unreleased changelog note in 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, accepted default ambiguity, 95% evidence methodology, owner roots versus accepted descendants, and how contributors add/review evidence.
    5. Regenerate language coverage and its explicit source fingerprint. Do not edit historical versioned docs.

    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:

    1. Pin SDK, configuration, runner/CPU policy, OS culture engine, corpus, and baseline SHA. Add only the minimum dedicated cold-start/size probe not already expressible in existing benchmarks/scripts.
    2. Measure ordinary per-owner tables across every target assembly/package. If no assembly exceeds 500 KiB raw morphology, skip MorphPack. If one does, prototype the specified compact layout from the same logical model, prove every authored input/status differential-equal, and select it only for material exact-head savings.
    3. Run targeted suites first, then full TFMs/platforms, docs, formatting, Release pack/package verification, ReadyToRun, trimming, NativeAOT, size, cold/warm performance, scaling, retained-heap, and initialization checks.
    4. Run exact-head API, linguistic/evidence, owner/fallback, ambiguity/fuzz, package/performance/AOT, and independent code-owner reviews. Resolve findings and rerun invalidated gates.
    5. Use the repository's compound-engineering commit/push/PR flow. Merge only the reviewed exact head; update/close Localized arbitrary-string Pluralize/Singularize with locale-owned grammar #1892 with contributors and evidence; remove only this task's clean unused worktree/topic refs.

    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

    dotnet test tests/Humanizer.SourceGenerators.Tests/Humanizer.SourceGenerators.Tests.csproj --framework net10.0
    dotnet test tests/Humanizer.SourceGenerators.Tests/Humanizer.SourceGenerators.Tests.csproj --framework net11.0
    dotnet test tests/Humanizer.Tests/Humanizer.Tests.csproj --framework net10.0 --filter-class Humanizer.Tests.LocalizedInflectionTests
    dotnet test tests/Humanizer.Tests/Humanizer.Tests.csproj --framework net10.0 --filter-class Humanizer.Tests.InflectorTests
    dotnet test tests/Humanizer.Tests/Humanizer.Tests.csproj --framework net10.0 --filter-class Humanizer.Tests.ToQuantityTests
    dotnet test tests/Humanizer.Tests/Humanizer.Tests.csproj --framework net10.0 --filter-class Humanizer.Tests.Localisation.SupportedCultureTests

    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

    dotnet test tests/Humanizer.Tests/Humanizer.Tests.csproj --framework net8.0
    dotnet test tests/Humanizer.Tests/Humanizer.Tests.csproj --framework net10.0
    dotnet test tests/Humanizer.Tests/Humanizer.Tests.csproj --framework net11.0
    dotnet format Humanizer.slnx --verify-no-changes --verbosity diagnostic

    Run net48 on Windows only:

    dotnet test tests/Humanizer.Tests/Humanizer.Tests.csproj --framework net48

    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

    pwsh tools/docs/generate-language-coverage.ps1
    pwsh tools/docs/test.ps1
    pwsh tools/docs/verify-api.ps1
    pwsh tools/docs/verify-examples.ps1
    pwsh tools/docs/verify-manifest.ps1
    pwsh tools/docs/verify-scenario-api.ps1
    dotnet pack src/Humanizer/Humanizer.csproj -c Release -o artifacts/packages
    $taskPackageVersion = "<version emitted by dotnet pack>"
    pwsh tests/verify-packages.ps1 -PackageVersion $taskPackageVersion -PackagesDirectory artifacts/packages
    pwsh tools/docs/verify-aot.ps1

    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

    • Warm identity/unknown: exact reference, 0 B/op, no more than max(10%, 15 ns) slower than baseline.
    • Warm exact: at most 2× baseline English exact and 1 µs.
    • Productive forward: at most 2.5× and 2 µs; productive reverse: at most 3× and 3 µs.
    • Unsupported cold: at most 8 KiB additional allocation and 25% wall-time regression.
    • English first use: p95 ≤2 ms and ≤128 KiB; largest locale: p95 ≤5 ms and ≤2 × payload + 64 KiB.
    • Library load initializes no locale; one locale initializes only its owner; repeated unknown cultures retain 0 bytes.
    • Input doubling from 4 KiB to 1 MiB remains <2.5× time and approximately 2× allocation.
    • Generated source ≤5 MiB total and ≤256 KiB per syntax tree.
    • Clean build median regression ≤20% or 2 seconds, whichever is greater; peak compiler RSS ≤+150 MiB.
    • Release Humanizer.dll ≤+4 MiB; compressed nupkg ≤+1.5 MiB; NativeAOT app ≤+5 MiB and publish time ≤+20%.
    • No related trimming warnings. JIT, ReadyToRun, trimming, and NativeAOT all retain direct-reference generated data.

    Review gates

    • Exact-head public API and compatibility approval, including default, reflection, method groups, nullability, and published-package evidence.
    • Independent code-owner review of Sol-authored shared work.
    • Independent reviewer for every locale batch; no self-approval.
    • Generated-data determinism and evidence arithmetic audit.
    • Hostile linguistic, ambiguity/reverse, Unicode/script, and no-English-fallback review.
    • Package/performance/cache/trimming/AOT review.
    • Full matrix rerun after the last material change.

    Definition of Done

    • U1: Current-main writer is cleanly based on the pinned SHA; published-package and compatibility ledgers exist; preserved work is individually classified without overwriting fix(localization): complete supported culture APIs #1893.
    • U2: The canonical schema validates atomic active/inert bundles and evidence; one generated owner graph drives support, built-in localization, and inflection without platform parents.
    • U3: Locale-granular holders and bounded runtime implement exact, productive, ambiguity, Unicode, casing, operand, identity, and lazy-initialization semantics deterministically.
    • U4: Familiar string and ToQuantity APIs use the engine; English approved behavior holds; feat: expose localized pluralization forms #1888 public surface is removed and API review is approved.
    • U5: All 102 roots and accepted descendants have complete reviewed owners, exact suite rows, ≥95% exception coverage or valid N/A, and productive directions meet their evidence gate.
    • U6: Existing suites, API approvals, readme, contributor docs, examples, language coverage, upgrade notes, and scenario contracts describe and prove one public design; no second parity framework exists.
    • U7: Exact-head TFM/platform/docs/pack/performance/size/trimming/AOT/adversarial gates pass; the PR merges; Localized arbitrary-string Pluralize/Singularize with locale-owned grammar #1892 closes with credit; only task-owned clean unused refs are removed.
    • No abandoned decoder, FST, central catalog, compatibility shim, duplicate corpus/evidence framework, generated artifact, debug probe, or other dead-end experiment remains in the final diff.
    • The merged implementation is standalone: no build/runtime download, external data file, optional morphology package, service, or model is required.
  4. clairernovotny commented on Aug 3, 2026

    @clairernovotny
    MemberAuthor

    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.

  5. clairernovotny commented on Aug 3, 2026

    @clairernovotny
    MemberAuthor

    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.

  6. clairernovotny commented on Oct 2, 2026

    @clairernovotny
    MemberAuthor

    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.

  7. clairernovotny commented on Oct 3, 2026

    @clairernovotny
    MemberAuthor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementAdds or improves user-facing functionalitylocalisationChanges translations, locale data, or culture-specific behavior

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions