Skip to main content
Version: 4.0 (next)

Configuration basics

Orientation​

Prefer per-call culture arguments when an overload provides one. Use CultureInfo.CurrentCulture and CurrentUICulture when a Humanizer API follows ambient application culture. Reserve Configurator for application-wide strategies, registries, or enum metadata rules.

Configure global behavior once during application startup, before any request or background worker can use Humanizer.

Example​

This verified example installs the built-in precision date strategy at startup and proves the resulting output with an injected comparison instant:

Program.cs
using System.Globalization;
using Humanizer;
#if HUMANIZER_V2
using Humanizer.Configuration;
using Humanizer.DateTimeHumanizeStrategy;
#endif

var culture = CultureInfo.GetCultureInfo("en-US");
var comparison = new DateTime(2025, 1, 20, 12, 0, 0, DateTimeKind.Utc);

Configurator.DateTimeHumanizeStrategy =
    new PrecisionDateTimeHumanizeStrategy(precision: 0.75);
Configurator.TimeSpanHumanizeStrategy =
    new SingleUnitTimeSpanHumanizeStrategy();

var result = comparison.AddMinutes(-45).Humanize(
    utcDate: true,
    dateToCompareAgainst: comparison,
    culture: culture);
var duration = TimeSpan.FromMinutes(62).Humanize(
    precision: 2,
    culture: culture);

if (result != "an hour ago")
    throw new InvalidOperationException($"Unexpected result: {result}");
if (duration != "1 hour")
    throw new InvalidOperationException($"Unexpected duration: {duration}");

Console.WriteLine($"{result}; {duration}");

sealed class SingleUnitTimeSpanHumanizeStrategy : ITimeSpanHumanizeStrategy
{
    readonly DefaultTimeSpanHumanizeStrategy defaultStrategy = new();

    public string Humanize(
        TimeSpan timeSpan,
        int precision,
        bool countEmptyUnits,
        CultureInfo? culture,
        TimeUnit maxUnit,
        TimeUnit minUnit,
        string? collectionSeparator,
        bool toWords,
        bool toSymbols) =>
        defaultStrategy.Humanize(
            timeSpan,
            Math.Min(precision, 1),
            countEmptyUnits,
            culture,
            maxUnit,
            minUnit,
            collectionSeparator,
            toWords,
            toSymbols);
}

For a global date strategy, assign Configurator.DateTimeHumanizeStrategy once at startup. For a custom localized component, call the relevant registry's Register method before the registry is resolved.

Pitfall​

In Humanizer 3.x and current builds, LocaliserRegistry<T> freezes its registrations on first use, so registering after resolution throws InvalidOperationException. Likewise, call Configurator.UseEnumDescriptionPropertyLocator before the first enum humanization.

Version notes​

Humanizer 2.x keeps registries mutable and exposes an assignable Configurator.EnumDescriptionPropertyLocator; 3.x introduces registry freezing and UseEnumDescriptionPropertyLocator. Date strategies exist across the supported corpus. Confirm the selected-version API before adopting another global extension point.