Humanizr/Humanizer: a .NET library for human-readable strings, dates and quantities

What Humanizr/Humanizer actually solves in .NET code

Display strings are a chore in every language, and .NET gives you little help. An enum prints as its identifier. A TimeSpan prints as 00:02:00. A byte count prints as 1000000. Humanizer is a library that converts those values into the phrasing a person would expect: 2 minutes, 1 MB, a pluralized noun for the right count.

The README states the scope plainly: strings, enums, dates, times, durations, numbers, quantities and collections turned into human-friendly text. The audience is .NET developers writing application code, tests or tooling that surfaces values to people. The repository topics include localization alongside hacktoberfest, and the example code is culture-aware throughout, which tells you the intended use is not English-only.

It is not a text-rewriting service. The name collides with a crowded search space of AI rephrasing tools, but nothing in the repository, README or documentation describes paraphrasing prose or evading detectors. It formats values. That distinction matters before you read any further.

The mechanism: culture, CLDR categories and grammatical case

The library is a set of extension methods over framework types. The README example calls Humanize on a TimeSpan, ToIndianWords on a long, and HumanizeWithFractionalSeconds with precision, maxFractionalDigits, roundingMode, culture and maxUnit parameters. Each call takes an optional CultureInfo, so the output language is a parameter rather than a global setting.

The more interesting part is how pluralization is modelled. In v4 previews, applications can supply exact noun forms for a culture's CLDR cardinal categories through a PluralizationForms type, constructed with singular, other, few and many values. TryPluralize takes a decimal and a CultureInfo and returns false when the selected form was not supplied. TrySingularize resolves any exact form in the same set. The README says TryPluralize uses the required cardinal rule for every supported culture, so the caller supplies the words and the library supplies the rule.

Grammatical case gets similar treatment. HumanizeWithCase takes a GrammaticalCase and a culture; the README's German example produces "in einer Woche" from seven days. Two constraints are stated explicitly. HumanizeWithCase returns only the duration phrase, so you add any preposition yourself. And locales or custom components without verified case support throw NotSupportedException rather than falling back to English. That is a deliberate design choice: silent fallback would ship wrong grammar, so the library fails loudly instead. It also means a culture that works for one API may not work for another.

Installing Humanizer and a first real call

The README gives one install command. It targets the NuGet package, so it works in any project that restores from nuget.org.

dotnet add package Humanizer

After restore, the types are available under the Humanizer namespace. The README's example imports System.Globalization and Humanizer, resolves a culture, and humanizes a two-minute TimeSpan. The comment in the source shows the expected output.

using System.Globalization;
using Humanizer;

var culture = CultureInfo.GetCultureInfo("en-US");
var text = TimeSpan.FromMinutes(2).Humanize(culture: culture);

Console.WriteLine(text); // 2 minutes

For a first real use beyond the sample, the byte-size API is a good candidate because the units are visible. The README shows ByteSize.FromBytes followed by Format with ByteSizeUnitSystem.DecimalSi or ByteSizeUnitSystem.BinaryIec. Note the stated caveat: legacy byte-size APIs keep their established unit factors, so the new unit-system parameter is an opt-in path rather than a change to existing calls.

var size = ByteSize.FromBytes(1_000_000);

Console.WriteLine(size.Format(ByteSizeUnitSystem.DecimalSi)); // 1 MB
Console.WriteLine(size.Format(ByteSizeUnitSystem.BinaryIec)); // 976.56 KiB

The README directs readers to the documentation site to select a version, and says the site carries version-correct package, framework and API guidance. Because the pluralization and unit-system examples are labelled v4 previews, check that page before copying them into a project pinned to an older release.

Where Humanizer refuses to guess

The NotSupportedException behaviour is the most consequential limitation documented. A locale without verified grammatical-case support does not degrade to English; the call throws. If your application accepts arbitrary culture codes from users or configuration, you now own the validation: you either restrict the set of cultures you pass to HumanizeWithCase or you catch the exception and choose a fallback yourself. The README does not document a capability query that would let you test a culture before calling, so the failure surfaces at the call site.

The same shape appears in TryPluralize. It returns false when the selected form was not supplied, which pushes the responsibility for complete noun sets onto the application. That is honest, but it is work: a Polish noun set needs singular, other, few and many, and the README's example fills all four.

HumanizeWithCase also returns only the duration phrase. The README is explicit that you add any required preposition yourself, and that singular forms may include a locale-authored one-word or article, and that a locale may encode a count in the unit form. Those three statements together mean the returned string is not a drop-in sentence fragment in every language. If you need a complete localized sentence, this API gives you a component, not the sentence.

Finally, the README does not document rollback or downgrade steps for the v4 preview APIs. The upgrade page is linked, but nothing in the README describes reverting a package version or the compatibility guarantees between preview and stable releases. Treat that as an open question to resolve before shipping preview APIs.

Humanizer compared with plain .NET formatting and resources

The obvious alternative is the framework itself: TimeSpan.ToString with a custom format string, ToString on enums, and resx resource files for pluralized text. That approach has no dependency and no preview APIs. Its difference is that it does not know the rules. A format string produces 00:02:00, not 2 minutes. Enum ToString produces the identifier, not spaced words. Pluralization lives in whatever conditional logic you write per language.

Humanizer's approach is to encode the language rules instead. The CLDR cardinal categories in PluralizationForms, the grammatical case parameter, and the culture-aware Humanize overloads are all attempts to move language knowledge out of application code and into a library. The trade-off is the one described above: you inherit the library's rules and its gaps, including the exception for cultures it cannot verify. A resource-file approach lets you ship a wrong translation quietly; Humanizer makes some of those gaps loud.

For byte sizes specifically, the README contrasts the new DecimalSi and BinaryIec unit systems with legacy APIs that keep their established unit factors. That is a real divergence inside the library, not just against the framework, and worth knowing if your codebase mixes old and new calls.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-09-18. Recent releases listed are documentation deployments from early August 2026, which is consistent with the README's emphasis on a versioned documentation site rather than frequent library releases. The main library lives in src/Humanizer with xUnit tests in tests/Humanizer.Tests, and the README points contributors at .github/CONTRIBUTING.md before sending a change.

Licensing is straightforward at the project level: the README states Humanizer is available under the MIT license, and the repository carries license.txt. The repository metadata reports the license as NOASSERTION, which is a classifier result rather than a statement about the project; the README and the license file are the sources to read. There is also a THIRD-PARTY-NOTICES.txt at the repository root, so a dependency audit should include it. This is a description of what the files say, not legal advice.

Upgrade cost concentrates in two places. First, the v4 preview APIs: the pluralization forms, grammatical case, and the SI and IEC byte-size unit systems are described as previews, and the README links an upgrade guide and a migration analyzer configuration page. Second, the behaviour changes: an exception where a previous version may have fallen back to English is an upgrade concern, and the README's own note that legacy byte-size APIs keep their established factors means old and new formatting can coexist with different results.

Editorial conclusion

Adopt Humanizer if you are writing .NET code that renders durations, enum names, byte sizes or pluralized nouns to end users and you want the grammar handled per culture. Do not adopt it expecting anything to do with AI text rewriting, detector evasion or Grammarly: the related-search traffic around those phrases belongs to unrelated products, not to this NuGet package. Before upgrading, check the versioned documentation at humanizr.net/docs for the API surface you actually call, because the v4 preview material shows both new opt-in APIs and behaviour changes such as NotSupportedException for cultures without verified grammatical-case support.

Frequently asked questions

Official sources

1. Humanizr/Humanizer on GitHub
2. Issues
3. README
4. Releases