Skip to main content
Version: 4.0 (next)

Override platform globalization data

Orientation​

.NET Framework commonly reads Windows NLS data while modern .NET normally uses ICU. Month names and numeric punctuation can therefore differ by platform, target framework, or globalization-data version.

Add an override only when a probe demonstrates that platform data is wrong or inconsistent for the locale. Locale YAML does not mutate CultureInfo; it supplies narrow values at documented Humanizer call sites.

Probe before editing​

Run the same culture and values on the affected targets, including Windows net48 and a modern .NET target when the report concerns NLS/ICU drift. Record:

  • culture and Humanizer version
  • OS, target framework, and globalization mode
  • raw DateTimeFormat or NumberFormat values
  • complete Humanizer output
  • native-reviewed expected output

Keep the probe with the parity artifact and add exact-output regression tests.

Example​

Override month names​

Author all twelve nominative months:

surfaces:
  calendar:
    months:
      - '<January>'
      - '<February>'
      - '<March>'
      - '<April>'
      - '<May>'
      - '<June>'
      - '<July>'
      - '<August>'
      - '<September>'
      - '<October>'
      - '<November>'
      - '<December>'

Add monthsGenitive only when the language distinguishes genitive month forms, and hijriMonths only when Hijri ordinal-date output needs an override. Each authored array must be complete and native-reviewed.

Calendar overrides affect Humanizer ordinal-date rendering, including DateTime.ToOrdinalWords and, on supported package targets, DateOnly.ToOrdinalWords.

Override a decimal separator​

surfaces:
  number:
    formatting:
      decimalSeparator: ','

The decimal separator is used by culture-aware Humanizer numeric formatting. ByteSize.TryParse applies it only when the caller supplies an explicit CultureInfo.

Override a negative sign​

surfaces:
  number:
    formatting:
      negativeSign: '−'

Use the exact native-reviewed character. U+2212 minus sign and U+002D hyphen-minus are not interchangeable.

Override a group separator​

surfaces:
  number:
    formatting:
      groupSeparator: '.'

Number-formatting overrides are consumed by the documented culture-aware Ordinalize integer formatting, ByteSize.ToString, ByteSize.ToFullWords, and metric-numeral paths. ByteSize.TryParse does not apply the negative-sign or group-separator overrides.

After authoring an override:

  1. Add exact-output tests for every affected API and target-specific failure.
  2. Verify both the previously failing target and a modern target.
  3. Run the full locale validation matrix.
  4. Regenerate supported-culture coverage and review the ownership change.

Pitfall​

Do not copy platform data into YAML merely to make ownership explicit. Absence means Humanizer should use platform globalization data. An override becomes a maintained compatibility contract and must have a proving regression test.

Caller-supplied custom format providers remain authoritative. String Ordinalize overloads parse through the culture's native NumberFormatInfo; locale overrides do not rewrite arbitrary provider input.

Version notes​

The YAML-backed calendar and number.formatting surfaces describe main/preview. Historical versions can rely directly on platform data or have different call-site behavior. Probe the package and targets you actually ship before backporting an override.