Upgrade from 3.0.10 to Humanizer 4
Orientation
Use this page when upgrading an application from Humanizer 3.0.10 to
Humanizer 4. Start from a clean 3.0.10 build, update the NuGet package, then
work through each compatibility boundary below.
Example
Create an application branch, update the package from NuGet, and validate the application before changing source:
git switch -c upgrade-humanizer-4
dotnet add <app-project.csproj> package Humanizer --version 4.0.0
dotnet restore <app-project.csproj> --force-evaluate
dotnet build <app-project.csproj>
dotnet test <app-project.csproj>
Replace <app-project.csproj> with the application project path relative to
the repository root.
Consolidate package references
Published releases through 3.0.10 use a Humanizer metapackage over
Humanizer.Core and locale packages. Humanizer 4 consolidates runtime code,
generated locale data, and analyzers in Humanizer. Remove direct
locale-package references as part of the migration and verify the resulting
asset graph.
Supporting locale assemblies do not need new explicit references. Culture
selection remains a runtime CultureInfo concern.
Widen number-word parser results
ToNumber and TryToNumber return int through 3.0.10 and long in
Humanizer 4. Use var when the wider result is acceptable. When the
application contract remains 32-bit, use a checked conversion:
var parsed = "one hundred".ToNumber(culture);
var legacyValue = checked((int)parsed);
The Humanizer 4 analyzer can offer that checked conversion for recognized
assignments failing with CS0029 or CS0266. It is separate from
HUMANIZER001 and is not present in 3.0.10.
Replace removed resource internals
Resources and ResourceKeys remain public in 3.0.10 and are removed in
Humanizer 4. Replace direct resource-key access with typed Humanizer APIs.
Custom formatters and converters should implement the typed public interfaces
rather than depending on resource names.
Recheck ampersands in humanized strings
Humanizer 4 preserves & as a separate token when humanizing PascalCase or
camelCase text. 3.0.10 discarded it with other punctuation, so exact-output
tests and persisted display labels can change:
// 3.0.10: "Research development"
// Humanizer 4: "Research & development"
var label = "Research&Development".Humanize();
Other punctuation such as + and / remains discarded. Compare any output
that contains ampersands before adopting the preview.
Recheck frameworks and localization
3.0.10 ships netstandard2.0, net48, net8.0, and net10.0 assets.
Humanizer 4 also targets net11.0. It generates locale registries and
formatting data from reviewed locale definitions instead of shipping the
historical locale-assembly implementation.
Pitfall
Do not retain mixed Humanizer 3 and Humanizer 4 assemblies. Package
consolidation can make a restore appear simpler while stale lock files or
direct Humanizer.Core references still select the old graph.
Version notes
This page is specific to the Humanizer 4 package.