ZetCode

C# Humanizer

last modified October 18, 2026

In this article we use the Humanizer library to humanize strings, dates, time spans, numbers, enums, collections, and quantities. By humanizing we mean making information easier to understand for people.

$ dotnet add package Humanizer.Core

We add the library to our project. The examples were written with Humanizer 3.0.

The Humanizer.Core package contains the English resources only. To get the translations into other languages (many languages), install the Humanizer package instead; it includes Humanizer.Core and all the localization packages. The current UI culture decides which language is used, and most methods also accept an explicit CultureInfo.

Note: Humanizer is designed for display text. Do not parse its output or use it for data that other programs read; such data should keep the precise, culture-independent form.

Transforming text

The Transform method transforms a string using the provided transformers.

Program.cs
using Humanizer;

Console.OutputEncoding = System.Text.Encoding.UTF8;

var msg = "an old falcon in the sky";

Console.WriteLine(msg.Transform(To.LowerCase));
Console.WriteLine(msg.Transform(To.SentenceCase));
Console.WriteLine(msg.Transform(To.TitleCase));
Console.WriteLine(msg.Transform(To.UpperCase));

var msg2 = "старый сокол в небе";
Console.WriteLine(msg2.Transform(To.LowerCase));
Console.WriteLine(msg2.Transform(To.SentenceCase));
Console.WriteLine(msg2.Transform(To.TitleCase));
Console.WriteLine(msg2.Transform(To.UpperCase));

In the program, we transform the case of two strings, one in English and one in Russian.

$ dotnet run
an old falcon in the sky
An old falcon in the sky
An Old Falcon in the Sky
AN OLD FALCON IN THE SKY
старый сокол в небе
Старый сокол в небе
Старый Сокол В Небе
СТАРЫЙ СОКОЛ В НЕБЕ

The English title case leaves short words such as "in" and "the" in lower case. The transformers use the rules of the current culture.

Truncating strings

When we cannot show the whole string in the display, it is a common practice to shorten the string with a truncation suffix, usually an ellipsis.

Program.cs
using Humanizer;

var msg = "an old falcon in the sky";
Console.WriteLine(msg.Truncate(15));
Console.WriteLine(msg.Truncate(15, Truncator.FixedLength, TruncateFrom.Left));
Console.WriteLine(msg.Truncate(15, "...", TruncateFrom.Left));
Console.WriteLine(msg.Truncate(15, "..."));
Console.WriteLine(msg.Truncate(4, "...", Truncator.FixedNumberOfWords));
Console.WriteLine(msg.Truncate(15, "...", Truncator.FixedNumberOfCharacters));

We use the Truncate method to shorten a string. We can shorten strings based on characters or words, from the right or from the left, and choose the truncation string.

$ dotnet run
an old falcon …
…con in the sky
...n in the sky
an old falco...
an old falcon in...
an old falcon i...

The default truncator keeps the total length, including the suffix, within the limit. The default suffix is the single ellipsis character "…". The FixedNumberOfWords truncator counts words instead of characters, and FixedNumberOfCharacters counts the characters without the suffix.

Roman numerals

We can transform numbers from Arabic to Roman numerals and back.

Program.cs
using Humanizer;

int[] vals = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 20, 100, 125, 500, 1000, 1555];

var roman = vals.Select(v => v.ToRoman()).ToList();
var arabic = roman.Select(r => r.FromRoman()).ToList();

Console.WriteLine(string.Join(",", roman));
Console.WriteLine(string.Join(",", arabic));

try
{
    4000.ToRoman();
}
catch (ArgumentOutOfRangeException)
{
    Console.WriteLine("4000 cannot be written as a Roman numeral");
}

We define an array of numbers, transform them to Roman numerals and then back to Arabic numerals.

var roman = vals.Select(v => v.ToRoman()).ToList();
var arabic = roman.Select(r => r.FromRoman()).ToList();

The ToRoman method converts an integer to a Roman numeral, and FromRoman converts it back.

4000.ToRoman();

The classic Roman system has no symbol for numbers over 3999, so the conversion throws an ArgumentOutOfRangeException outside of the range 1 to 3999.

$ dotnet run
I,II,III,IV,V,VI,VII,VIII,IX,X,XI,XX,C,CXXV,D,M,MDLV
1,2,3,4,5,6,7,8,9,10,11,20,100,125,500,1000,1555
4000 cannot be written as a Roman numeral

Transforming numbers to words

The ToWords method transforms a number into words. The ToOrdinalWords method transforms a number into an ordinal word, and Ordinalize adds an ordinal suffix to the digits.

Program.cs
using Humanizer;

int[] vals = [1, 2, 3, 11, 20, 100, 125, 1000, 1555];

foreach (var e in vals)
{
    Console.WriteLine($"{e,5} {e.ToWords(),-45} {e.ToOrdinalWords()}");
}

Console.WriteLine(21.Ordinalize());
Console.WriteLine(22.Ordinalize());
Console.WriteLine(113.Ordinalize());
Console.WriteLine(1234567.ToWords());
Console.WriteLine((-5).ToWords());

We transform an array of integer values to words and ordinal words, and show ordinal suffixes for a few numbers.

$ dotnet run
    1 one                                           first
    2 two                                           second
    3 three                                         third
   11 eleven                                        eleventh
   20 twenty                                        twentieth
  100 one hundred                                   hundredth
  125 one hundred and twenty-five                   hundred and twenty-fifth
 1000 one thousand                                  thousandth
 1555 one thousand five hundred and fifty-five      thousand five hundred and fifty-fifth
21st
22nd
113th
one million two hundred and thirty-four thousand five hundred and sixty-seven
minus five

Note that "113th" is correct: the numbers 11, 12, and 13 take "th" despite their last digit.

Singularize and pluralize words

The Singularize method singularizes the provided input, considering irregular words, while the Pluralize method pluralizes it. The ToQuantity method combines a number with the correctly inflected word.

Program.cs
using Humanizer;

string[] plural = ["geese", "octopi", "mice", "passers-by", "men", "men-servants", "dormice", "lice", "teeth", "feet"];

foreach (var word in plural)
{
    Console.WriteLine($"{word,-14} {word.Singularize()}");
}

Console.WriteLine("--");

string[] singular = ["goose", "octopus", "mouse", "passer-by", "man", "man-servant", "dormouse", "louse", "tooth", "foot", "person", "city"];

foreach (var word in singular)
{
    Console.WriteLine($"{word,-14} {word.Pluralize()}");
}

Console.WriteLine("--");

Console.WriteLine("car".ToQuantity(1));
Console.WriteLine("car".ToQuantity(5));
Console.WriteLine("man".ToQuantity(3));
Console.WriteLine("car".ToQuantity(0));
Console.WriteLine("car".ToQuantity(1234, "N0"));
Console.WriteLine("car".ToQuantity(3, ShowQuantityAs.Words));
Console.WriteLine("car".ToQuantity(3, ShowQuantityAs.None));

We singularize and pluralize a number of English words, and then use quantities.

$ dotnet run
geese          goose
octopi         octopus
mice           mouse
passers-by     passers-by
men            man
men-servants   men-servant
dormice        dormice
lice           louse
teeth          tooth
feet           foot
--
goose          geese
octopus        octopi
mouse          mice
passer-by      passer-bies
man            men
man-servant    man-servants
dormouse       dormouses
louse          lice
tooth          teeth
foot           feet
person         people
city           cities
--
1 car
5 cars
3 men
0 cars
1,234 cars
three cars
cars

The inflection works by rules and a list of irregular words, so it is not perfect: "passers-by", "men-servants", "passer-by", and "dormouse" are handled wrongly. For text that must be right, check the result. The last three lines show the formatting options of ToQuantity: a number format, the number written as words, and no number at all.

Humanizing identifiers

Strings from code, such as property names or file names, are not meant for people. Humanize turns them into readable text, and a family of methods converts between naming conventions.

Program.cs
using Humanizer;

Console.WriteLine("Humanize_this_text-please".Humanize());
Console.WriteLine("PascalCaseSentence".Humanize());
Console.WriteLine("some HTTP request".Humanize(LetterCasing.Title));

Console.WriteLine("--");

string s = "an old falcon in the sky";
Console.WriteLine(s.Pascalize());
Console.WriteLine(s.Camelize());
Console.WriteLine(s.Underscore());
Console.WriteLine(s.Kebaberize());
Console.WriteLine("PascalCaseSentence".Underscore());

Console.WriteLine("--");

Console.WriteLine("Pascal case sentence".Dehumanize());
Console.WriteLine("some-kebab-text".Pascalize());

We humanize several identifiers and then convert a sentence between the common naming conventions.

$ dotnet run
Humanize this text please
Pascal case sentence
Some HTTP Request
--
AnOldFalconInTheSky
anOldFalconInTheSky
an_old_falcon_in_the_sky
an-old-falcon-in-the-sky
pascal_case_sentence
--
PascalCaseSentence
SomeKebabText

Pascalize and Camelize produce PascalCase and camelCase, Underscore produces snake_case, and Kebaberize produces kebab-case. Dehumanize is the reverse of Humanize. Passing a LetterCasing value to Humanize sets the case of the result.

Time spans and dates

We can humanize TimeSpan and DateTime values with Humanize.

Program.cs
using Humanizer;

Console.WriteLine(TimeSpan.FromDays(486).Humanize(maxUnit: TimeUnit.Year));
Console.WriteLine(TimeSpan.FromDays(486).Humanize(precision: 3, maxUnit: TimeUnit.Year));
Console.WriteLine(TimeSpan.FromMinutes(1600).Humanize(4));
Console.WriteLine(TimeSpan.FromMinutes(1600).Humanize());
Console.WriteLine(TimeSpan.FromMinutes(1600).Humanize(maxUnit: TimeUnit.Hour));
Console.WriteLine(TimeSpan.FromMilliseconds(5553005).Humanize(3));
Console.WriteLine(TimeSpan.FromSeconds(90).Humanize(2, minUnit: TimeUnit.Second));
Console.WriteLine(TimeSpan.FromSeconds(90).Humanize(2, collectionSeparator: " and "));
Console.WriteLine(TimeSpan.Zero.Humanize());
Console.WriteLine(TimeSpan.FromMilliseconds(250).Humanize());

Console.WriteLine("--");

Console.WriteLine(DateTime.UtcNow.AddHours(-30).Humanize());
Console.WriteLine(DateTime.UtcNow.AddHours(-2).Humanize());
Console.WriteLine(DateTime.UtcNow.AddDays(3).Humanize());
Console.WriteLine(DateTime.UtcNow.AddHours(2).Humanize());
Console.WriteLine(DateTime.UtcNow.AddSeconds(-10).Humanize());
Console.WriteLine(DateTime.UtcNow.AddDays(-400).Humanize());
Console.WriteLine(DateTime.UtcNow.AddMinutes(-45).Humanize());

var now = new DateTime(2026, 10, 18, 12, 0, 0);
Console.WriteLine(new DateTime(2026, 10, 15).Humanize(utcDate: false, dateToCompareAgainst: now));
Console.WriteLine(new DateTimeOffset(2026, 10, 18, 9, 0, 0, TimeSpan.Zero).Humanize(dateToCompareAgainst: new DateTimeOffset(2026, 10, 18, 12, 0, 0, TimeSpan.Zero)));

The program humanizes time spans and dates.

TimeSpan.FromDays(486).Humanize(precision: 3, maxUnit: TimeUnit.Year)

The precision option sets the maximum number of time units to return. The default is 1, which means that only the largest unit is returned. The maxUnit option sets the largest unit of time to output; without it, the largest unit is the week. The minUnit option sets the smallest one, and collectionSeparator changes the way the units are joined.

DateTime.UtcNow.AddHours(-2).Humanize()

For a DateTime, Humanize compares the value with the current UTC time and gives a relative description. We can pass the comparison date explicitly, which makes the output reproducible.

$ dotnet run
1 year
1 year, 3 months, 29 days
1 day, 2 hours, 40 minutes
1 day
26 hours
1 hour, 32 minutes, 33 seconds
1 minute, 30 seconds
1 minute and 30 seconds
0 milliseconds
250 milliseconds
--
yesterday
2 hours ago
2 days from now
an hour from now
10 seconds ago
one year ago
45 minutes ago
3 days ago
3 hours ago

Look at "2 days from now" for a date three days ahead and "an hour from now" for two hours ahead. Humanizer truncates, it does not round: by the time the method runs, a few milliseconds have passed, so the remaining time is just under three days or two hours. The same applies to the past. When rounding matters, pass a fixed comparison date or round the value before humanizing.

Enums and collections

Enum members are humanized by splitting the PascalCase name, or by using the Description attribute when one is present. Collections are joined into a readable list.

Program.cs
using System.ComponentModel;
using Humanizer;

Console.WriteLine(Status.WaitingForApproval.Humanize());
Console.WriteLine(Status.WaitingForApproval.Humanize(LetterCasing.Title));
Console.WriteLine(Status.Rejected.Humanize());
Console.WriteLine("Waiting for approval".DehumanizeTo<Status>());

Console.WriteLine("--");

string[] names = ["Anna", "Peter", "Lucia", "John"];
Console.WriteLine(names.Humanize());
Console.WriteLine(names.Humanize("or"));
Console.WriteLine(names.Take(2).Humanize());
Console.WriteLine(names.Take(1).Humanize());
Console.WriteLine(names.Humanize(n => n.ToUpper()));
Console.WriteLine(new[] { 1, 2, 3 }.Humanize());

enum Status
{
    Approved,

    [Description("Waiting for approval")]
    WaitingForApproval,

    Rejected
}

We humanize an enum and a few collections.

[Description("Waiting for approval")]
WaitingForApproval,

A Description attribute overrides the generated text. The DehumanizeTo method does the opposite: it finds the enum member for a human-readable string.

Console.WriteLine(names.Humanize("or"));
Console.WriteLine(names.Humanize(n => n.ToUpper()));

The separator word and a formatter for the items can be customized. The default is the Oxford comma style with "and".

$ dotnet run
Waiting for approval
Waiting for Approval
Rejected
WaitingForApproval
--
Anna, Peter, Lucia, and John
Anna, Peter, Lucia, or John
Anna and Peter
Anna
ANNA, PETER, LUCIA, and JOHN
1, 2, and 3

Metric numbers and time shortcuts

The ToMetric method writes a number using metric prefixes, and FromMetric parses it back. Numbers also get fluent extension methods to create time spans, such as 3.Days().

Program.cs
using Humanizer;

Console.WriteLine(1000.ToMetric());
Console.WriteLine(12345.678.ToMetric(decimals: 2));
Console.WriteLine(0.00042.ToMetric());
Console.WriteLine(1_500_000.ToMetric());
Console.WriteLine("1.5k".FromMetric());

Console.WriteLine("--");

Console.WriteLine(1500.Hours().Humanize(2));
Console.WriteLine(2.Weeks());
Console.WriteLine(3.Days() + 4.Hours());
Console.WriteLine(45.Minutes().Humanize());

Console.WriteLine("--");

Console.WriteLine(2.ToOrdinalWords());

The program shows both features.

$ dotnet run
1k
12.35k
420μ
1.5M
1500
--
8 weeks, 6 days
14.00:00:00
3.04:00:00
45 minutes
--
second

1500.Hours().Humanize(2) creates a time span of 1500 hours and describes it with two units. The expression 3.Days() + 4.Hours() is an ordinary TimeSpan addition. Formatting of byte sizes is provided by the separate ByteSize library.

Localization

With the full Humanizer package, the same calls produce text in other languages. The methods take a CultureInfo argument.

Program.cs
using System.Globalization;
using Humanizer;

foreach (var culture in new[] { "en", "de", "fr", "ru", "sk", "cs" })
{
    var ci = new CultureInfo(culture);

    Console.WriteLine($"{culture}: {5.ToWords(ci)} | {TimeSpan.FromDays(3).Humanize(culture: ci)} | {DateTime.UtcNow.AddHours(-3).Humanize(culture: ci)}");
}

We write the number five, a time span of three days, and "three hours ago" in six languages.

$ dotnet run
en: five | 3 days | 3 hours ago
de: fünf | 3 Tage | vor 3 Stunden
fr: cinq | 3 jours | il y a 3 heures
ru: пять | 3 дня | 3 часа назад
sk: five | 3 dni | pred 3 hodinami
cs: pět | 3 dny | před 3 hodinami

Not all features are translated for all languages. The Slovak number words are missing in this output, so the English "five" is shown, while the Slovak time phrases are present. Check the languages you need.

Source

Humanizer GitHub page

In this article we have presented the Humanizer library.

Author

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all C# tutorials.