Skip to main content
Version: 4.0 (next)

Localization and extensibility

Orientation​

Start with culture selection, then choose the narrowest extension point. Pass CultureInfo per call when possible. Establish CurrentCulture and CurrentUICulture at a request or job boundary for ambient APIs. Use a local interface implementation for one operation and reserve Configurator registries or strategies for process-wide application policy.

Example​

This verified example produces French number words and supplies a per-call culture-aware transformer:

Program.cs
using System.Globalization;
using Humanizer;

var french = CultureInfo.GetCultureInfo("fr-FR");
CultureInfo.CurrentCulture = french;
CultureInfo.CurrentUICulture = french;

AssertEqual("quarante-deux", 42.ToWords(french));
AssertEqual("BONJOUR", "bonjour".Transform(french, new LoudTransformer()));

Console.WriteLine("quarante-deux; BONJOUR");

static void AssertEqual(string expected, string actual)
{
    if (actual != expected)
        throw new InvalidOperationException($"Expected '{expected}', got '{actual}'.");
}

sealed class LoudTransformer : ICulturedStringTransformer
{
    public string Transform(string input) =>
        Transform(input, CultureInfo.CurrentCulture);

    public string Transform(string input, CultureInfo culture) =>
        culture.TextInfo.ToUpper(input);
}

The result is quarante-deux; BONJOUR. A per-call transformer is isolated and easy to test.

Choose an extension point​

NeedPreferred extension
One local string operationIStringTransformer or ICulturedStringTransformer
A custom truncation ruleITruncator passed to Truncate
Relative date thresholdsA date/time strategy assigned once
Application-wide locale componentThe matching LocaliserRegistry<T>
Case-aware duration policyIGrammaticalCaseTimeSpanHumanizeStrategy and IGrammaticalCaseTimeSpanFormatter
Enum metadata propertyUseEnumDescriptionPropertyLocator at startup

Registries cover collection formatters, general formatters, number-word converters, ordinalizers, date-ordinal converters, and clock-notation converters. Culture resolution checks the requested culture and its parents before using the registry default.

Set a global time-span policy​

On Humanizer 4, assign Configurator.TimeSpanHumanizeStrategy once during application startup to route every TimeSpan.Humanize and HumanizeToSymbols call through an application-wide policy. Fractional-second calls use IFractionalTimeSpanHumanizeStrategy when the configured strategy implements it; integral results remain compatible with legacy strategies. With the default strategy, genuinely fractional terminal values require IFractionalTimeSpanFormatter from a configured custom formatter. A custom IFractionalTimeSpanHumanizeStrategy may own its fractional formatting. Humanizer does not fall back to English. The fractional strategy receives the requested precision, empty-unit behavior, culture, unit range, separator, maximum fractional digits, rounding mode, and symbol mode.

This runnable configuration keeps the built-in date strategy example and adds a custom time-span strategy that delegates all behavior to DefaultTimeSpanHumanizeStrategy after limiting output to one part:

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);
}

HumanizeWithCase uses a separate optional capability so existing custom components remain source- and binary-compatible. A configured strategy must implement IGrammaticalCaseTimeSpanHumanizeStrategy, and its selected formatter must implement IGrammaticalCaseTimeSpanFormatter. Otherwise the case-aware call throws NotSupportedException, including when the requested case is Nominative. Existing Humanize and HumanizeToSymbols calls continue to use ITimeSpanHumanizeStrategy and IFormatter unchanged.

The case-aware formatter receives the duration unit, numeric count, and grammatical case. It returns a complete locale-authored unit-case phrase: singular output may contain a localized one-word or article, while a counted form may render the count explicitly or encode it in the unit form. It must not add a preposition. Install custom strategies and formatters during startup, before registry resolution freezes.

Pitfall​

In Humanizer 3.x and current, localizer registries freeze on first resolution. Register components before any Humanizer call can resolve that registry. Humanizer 2.x registries remain mutable, but startup registration still prevents request-to-request drift. Do not mutate global strategies per request; concurrent callers can observe the change.

Parent-culture fallback identifies where behavior was resolved. It does not prove that inherited wording is correct for every region.

Version notes​

The local transformer runs across the supported corpus. Registry immutability and enum metadata configuration change in Humanizer 3. TimeSpanHumanizeStrategy, ITimeSpanHumanizeStrategy, and DefaultTimeSpanHumanizeStrategy are Humanizer 4 APIs. Individual registries and supported-culture inventories are selected-version behavior; historical snapshots must not present current YAML/generator internals as old package behavior.