Skip to content

platform-globalization-overrides.mdx

Latest commit

 

History

History
137 lines (105 loc) · 4 KB

platform-globalization-overrides.mdx

File metadata and controls

137 lines (105 loc) · 4 KB
Raw
id platform-globalization-overrides
title Override platform globalization data
sidebar_position 6
diataxis how-to
persona language contributor
example illustrative

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.

Related guides and API