<img width="30px" src="logo.png" /> Humanizer

Humanizer meets all your .NET needs for manipulating and displaying strings, enums, dates, times, timespans, numbers and quantities.

📚 Full Documentation: See the documentation folder for comprehensive guides, examples, and API reference.

Install

You can install Humanizer as a NuGet package:

English only: Humanizer.Core

All languages: Humanizer

Supported frameworks

Supported frameworks: net10.0, net8.0, net48

netstandard2.0: The NuGet package also targets netstandard2.0 as a special case to support specific scenarios such as Roslyn Analyzers and MSBuild tasks that require netstandard2.0.

Unsupported versions: While other .NET Framework versions (net4.6.1 through net4.7.2) can technically consume netstandard2.0 libraries, they are not officially supported by Humanizer and may not work correctly. Please use one of the explicitly supported frameworks listed above for the best experience.

Humanizer symbols are source-indexed with SourceLink and included in the package, which means you can step through Humanizer's source code while debugging your own application.

[!IMPORTANT] Humanizer 3.0 restore requirements: The Humanizer metapackage now requires the NuGet locale parsing fix shipped in .NET SDK 9.0.200 and corresponding Visual Studio/MSBuild updates. Restore operations must run on .NET SDK 9.0.200 or newer, or on Visual Studio 2022/MSBuild versions that include that patch. Older SDKs/MSBuild builds will fail to restore the metapackage because they do not recognize three-letter locale identifiers. As a workaround, reference Humanizer.Core directly and add the desired Humanizer.Core.<locale> satellite packages individually when targeting older tooling.

Upgrading from 2.14.1 to 3.0.8? See docs/migration-v3.md for the complete breaking-change checklist, patch-line fix notes, and known regression status.

Specify Languages (Optional)

You choose which packages based on what NuGet package(s) you install. By default, the main Humanizer package installs all supported languages. If you're not sure, then just use the main Humanizer package.

Here are the options:

| Option | Package Name | Install Command | Included Languages | |--------|--------------|-----------------|-------------------| | All languages | Humanizer | dotnet add package Humanizer | All supported languages (pulls in Humanizer.Core and all language packages) | | English only | Humanizer.Core | dotnet add package Humanizer.Core | English only | | Specific languages | Humanizer.Core.<locale> | dotnet add package Humanizer.Core.fr (French example) | Install as many language-specific packages as needed |

For example, for French use Humanizer.Core.fr, for Spanish use Humanizer.Core.es, etc. You can include multiple languages by installing however many language packages you want.

The detailed explanation for how this works is in the comments here.

Features

Humanize String

String humanization is a core feature that transforms computerized strings into readable, human-friendly text. This is particularly valuable when you need to display programming identifiers (class names, method names, properties) to end users in a readable format.

The foundation of this feature was originally developed for the BDDfy framework to turn test method names into readable test descriptions. Humanize intelligently handles PascalCase, camelCase, underscored_strings, and dash-separated-strings.

"PascalCaseInputStringIsTurnedIntoSentence".Humanize() 
    => "Pascal case input string is turned into sentence"

"Underscored_input_string_is_turned_into_sentence".Humanize() 
    => "Underscored input string is turned into sentence"

"dash-separated-string".Humanize() 
    => "Dash separated string"

Acronym Handling: Strings containing only uppercase letters are treated as acronyms and left unchanged. To humanize any string, use the Transform method:

"HTML".Humanize() => "HTML"  // Acronym preserved
"HUMANIZER".Humanize() => "HUMANIZER"  // All caps preserved

// Force humanization with Transform
"HUMANIZER".Transform(To.LowerCase, To.TitleCase) => "Humanizer"

Letter Casing: Control the output casing directly:

"CanReturnTitleCase".Humanize(LetterCasing.Title) => "Can Return Title Case"
"CanReturnLowerCase".Humanize(LetterCasing.LowerCase) => "can return lower case"
"CanHumanizeIntoUpperCase".Humanize(LetterCasing.AllCaps) => "CAN HUMANIZE INTO UPPER CASE"
"some string".Humanize(LetterCasing.Sentence) => "Some string"

Version 3.0 Behavioral Change

In version 3.0, Humanize and Titleize now preserve input strings that contain no recognized letters (e.g., special characters, unrecognized Unicode scripts) instead of returning an empty string:

// Before v3.0: returned ""
// v3.0 and later: returns "@@"
"@@".Humanize() => "@@"

// Cyrillic and other Unicode scripts are also preserved
"Майк".Titleize() => "Майк"

Dehumanize String

Reverse the humanization process by converting human-friendly strings back to PascalCase:

"Pascal case input string is turned into sentence".Dehumanize() 
    => "PascalCaseInputStringIsTurnedIntoSentence"

"some string".Dehumanize() => "SomeString"
"Some String".Dehumanize() => "SomeString"

Transform String

The Transform method provides a flexible, extensible way to apply string transformations. Unlike the legacy LetterCasing enum which limits you to built-in options, IStringTransformer is an interface you can implement in your codebase for domain-specific transformations.

"Sentence casing".Transform(To.LowerCase) => "sentence casing"
"Sentence casing".Transform(To.SentenceCase) => "Sentence casing"
"Sentence casing".Transform(To.TitleCase) => "Sentence Casing"
"Sentence casing".Transform(To.UpperCase) => "SENTENCE CASING"

Truncate String

Intelligently truncate strings with multiple strategies. The default uses the … character (one character) instead of "..." (three characters) to maximize visible text before truncation. You can also implement custom ITruncator strategies for specialized truncation logic.

"Long text to truncate".Truncate(10) => "Long text…"
"Long text to truncate".Truncate(10, "---") => "Long te---"

// Fixed length (default)
"Long text to truncate".Truncate(10, Truncator.FixedLength) => "Long text…"

// Fixed number of words
"Long text to truncate".Truncate(2, Truncator.FixedNumberOfWords) => "Long text…"

// Truncate from the left
"Long text to truncate".Truncate(10, Truncator.FixedLength, TruncateFrom.Left) 
    => "… truncate"

Humanize Enums

Enum humanization eliminates the need to manually add spaces between words in enum member names. While you could use DescriptionAttribute on every enum member, Humanizer automatically handles the common case of simply needing to add spaces. When DescriptionAttribute (or any attribute with a Description property) is present, it takes precedence, making it easy to provide custom text only when needed.

public enum UserType
{
    [Description("Custom description")]
    MemberWithDescriptionAttribute,
    MemberWithoutDescriptionAttribute,
    ALLCAPITALS
}

// DescriptionAttribute value is used
UserType.MemberWithDescriptionAttribute.Humanize() => "Custom description"

// Automatic humanization when no attribute
UserType.MemberWithoutDescriptionAttribute.Humanize() 
    => "Member without description attribute"

// Apply casing transformations
UserType.MemberWithoutDescriptionAttribute.Humanize().Transform(To.TitleCase) 
    => "Member Without Description Attribute"

Humanizer works with any attribute containing a Description property and supports localized DisplayAttribute for multi-language scenarios. This helps you avoid littering enums with unnecessary attributes while still providing customization when needed.

Dehumanize Enums

Convert humanized strings back to their original enum values:

"Member without description attribute".DehumanizeTo<UserType>() 
    => UserType.MemberWithoutDescriptionAttribute

// Non-generic version for runtime types
"Member without description attribute".DehumanizeTo(typeof(UserType)) 
    => UserType.MemberWithoutDescriptionAttribute

// Handle missing matches gracefully
"Invalid".DehumanizeTo<UserType>(OnNoMatch.ReturnsNull) => null

The method honors DescriptionAttribute and is case-insensitive.

Humanize DateTime

Get relative time descriptions for DateTime and DateTimeOffset values:

DateTime.UtcNow.AddHours(-2).Humanize() => "2 hours ago"
DateTime.UtcNow.AddHours(-30).Humanize() => "yesterday"

DateTime.UtcNow.AddHours(2).Humanize() => "2 hours from now"
DateTime.UtcNow.AddHours(30).Humanize() => "tomorrow"

DateTimeOffset.UtcNow.AddHours(1).Humanize() => "an hour from now"

Supports both UTC and local times, with optional culture specification and custom c