Skip to main content
Version: 4.0 (next)

Customize localization

Orientation​

Prefer a per-call culture or transformer first. Use a custom localiser only when an application needs process-wide behavior that the selected locale does not provide.

Public registries cover collection formatters, general formatters, number-to-words converters, ordinalizers, date-ordinal converters, and, on supported targets, DateOnly and clock-notation converters. Date/time humanization strategies are separate process-wide properties.

Example​

In Humanizer 4, register before any code resolves the formatter registry:

using System.Globalization;
using Humanizer;

Configurator.Formatters.Register(
    "en-US",
    culture => new ProductFormatter(culture));

var culture = CultureInfo.GetCultureInfo("en-US");
var formatter = Configurator.Formatters.ResolveForCulture(culture);
Console.WriteLine(formatter.DateHumanize_Now());

sealed class ProductFormatter(CultureInfo culture)
    : DefaultFormatter(culture)
{
    public override string DateHumanize_Now() => "just now";
}

The result is just now. Register the narrowest component that owns the behavior; do not replace a formatter merely to change number words.

In Humanizer 4, a custom formatter used by HumanizeWithCase must also implement IGrammaticalCaseTimeSpanFormatter. A custom global time-span strategy must implement IGrammaticalCaseTimeSpanHumanizeStrategy. Existing IFormatter and ITimeSpanHumanizeStrategy implementations continue to work for the existing duration APIs, but case-aware calls fail with NotSupportedException instead of silently using another locale.

Pitfall​

In Humanizer 3.x and Humanizer 4, a LocaliserRegistry freezes on first resolution. A later Register call throws. Configure registries once during startup, before hosted services, request handlers, or static initializers can call Humanizer.

Custom global components affect every caller that resolves that culture. For request-specific text transformation, implement IStringTransformer or ICulturedStringTransformer and pass it to Transform instead.

If the built-in locale is wrong rather than product-specific, follow the language correction guide or open a prefilled locale issue.

Version notes​

Humanizer 2.x registries remain mutable; 3.x and Humanizer 4 freeze them after first use. Constructor shapes and available registries are version-specific public API. Compile against the selected package and follow that snapshot's API reference rather than copying a Humanizer 4 extension into a historical application.