Skip to main content
Version: 4.0 (next)

Customize localization

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​

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 output is just now. Register the narrowest component that owns the behavior; do not replace a formatter merely to change number words.

Support case-aware durations​

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.

Configure before first use​

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.