Humanizer для C# (.NET): полное руководство с примерами

1. Что это и зачем нужна

Humanizer — это популярная библиотека с открытым исходным кодом для платформы .NET, которая решает одну из самых частых проблем разработчиков: преобразование технических, машинно-ориентированных данных в формат, понятный человеку. Вместо того чтобы писать десятки вспомогательных методов для форматирования дат, чисел, перечислений и строк, Humanizer предоставляет элегантный fluent-интерфейс (цепочки вызовов методов), который делает код чище, а вывод — дружелюбнее.

Зачем это нужно? Представьте, что вы показываете пользователю время публикации комментария. Вместо сухого "2024-03-15T14:30:00Z" гораздо лучше отобразить "15 марта 2024 г., 14:30" или, если прошло немного времени, "только что", "5 минут назад". Humanizer делает такие преобразования одной строкой кода. Библиотека поддерживает локализацию (более 30 языков, включая русский), работу с числами (порядковые номера, римские цифры, "человеческие" байты), перечислениями (красивые строки с пробелами вместо CamelCase) и многое другое.

Humanizer написан на C# и полностью совместим с .NET Framework 4.6.1+, .NET Core 2.0+, .NET 5/6/7/8, а также с Xamarin, Unity и другими платформами, поддерживающими .NET Standard 2.0. Это делает её идеальным выбором для любого .NET-проекта, где требуется локализация и улучшение пользовательского опыта.

2. Установка

Установка Humanizer в проект .NET выполняется через менеджер пакетов NuGet. Используйте одну из следующих команд:

# Установка через .NET CLI (рекомендуется)
dotnet add package Humanizer

# Установка через Package Manager Console (Visual Studio)
Install-Package Humanizer

# Установка через NuGet Package Manager
# Или найдите "Humanizer" в графическом интерфейсе NuGet

После установки добавьте директиву using Humanizer; в начало файла с кодом.

3. Быстрый старт — минимальный рабочий пример

Создайте консольное приложение .NET и замените содержимое Program.cs следующим кодом:

using System;
using Humanizer;

class Program
{
    static void Main()
    {
        // 1. Преобразование даты в человекочитаемый формат
        DateTime date = DateTime.UtcNow.AddDays(-3);
        Console.WriteLine($"Дата: {date.Humanize()}"); // "3 дня назад" (на русском)

        // 2. Преобразование числа в порядковое числительное
        int number = 42;
        Console.WriteLine($"Порядковое: {number.Ordinalize()}"); // "42-й"

        // 3. Преобразование CamelCase в читаемую строку
        string camelCase = "PascalCaseString";
        Console.WriteLine($"Декомпозиция: {camelCase.Humanize()}"); // "Pascal case string"

        // 4. Преобразование байтов
        long bytes = 1024 * 1024 * 5; // 5 MB
        Console.WriteLine($"Байты: {bytes.Bytes()}"); // "5 MB"

        // 5. Работа с перечислениями
        Console.WriteLine($"Enum: {DayOfWeek.Monday.Humanize()}"); // "Monday" (на английском) или "Понедельник" (на русском)
    }
}

Для работы с русским языком добавьте using Humanizer.Localisation; и установите культуру:

using Humanizer;
using Humanizer.Localisation;

// Устанавливаем русскую культуру для всего приложения
System.Threading.Thread.CurrentThread.CurrentUICulture = new System.Globalization.CultureInfo("ru-RU");
System.Threading.Thread.CurrentThread.CurrentCulture = new System.Globalization.CultureInfo("ru-RU");

// Теперь все методы Humanizer будут возвращать строки на русском
Console.WriteLine(DateTime.UtcNow.AddDays(-1).Humanize()); // "вчера"

4. Основные методы/функции/классы

Рассмотрим 10 ключевых методов Humanizer. Для каждого приведена сигнатура, описание и рабочий пример.

4.1. Humanize() для строк (String Extensions)

Сигнатура: public static string Humanize(this string input, LetterCasing casing = LetterCasing.Title)

Что делает: Преобразует строки в форматах PascalCase, CamelCase, snake_case и kebab-case в читаемый текст с пробелами. Опционально меняет регистр первой буквы.

string[] tests = { "PascalCase", "camelCase", "snake_case", "kebab-case", "HTMLString" };
foreach (var test in tests)
{
    Console.WriteLine($"{test} => {test.Humanize()}");
}
// Вывод:
// PascalCase => Pascal case
// camelCase => Camel case
// snake_case => Snake case
// kebab-case => Kebab case
// HTMLString => HTML string (умное обращение с аббревиатурами)

4.2. Humanize() для дат (DateTime Extensions)

Сигнатура: public static string Humanize(this DateTime input, bool utcDate = true, DateTime? dateToCompareAgainst = null, CultureInfo culture = null)

Что делает: Возвращает относительное описание даты ("только что", "5 минут назад", "вчера", "2 недели назад", "в следующем году").

var now = DateTime.UtcNow;
Console.WriteLine(now.Humanize());                          // "только что"
Console.WriteLine(now.AddMinutes(-5).Humanize());           // "5 минут назад"
Console.WriteLine(now.AddDays(-1).Humanize());              // "вчера"
Console.WriteLine(now.AddDays(3).Humanize());               // "через 3 дня"
Console.WriteLine(now.AddYears(-2).Humanize());             // "2 года назад"

4.3. Ordinalize() для чисел

Сигнатура: public static string Ordinalize(this int number, string culture = null)

Что делает: Преобразует число в порядковое числительное (1 -> "1-й", 2 -> "2-й", 21 -> "21-й").

for (int i = 1; i <= 5; i++)
    Console.WriteLine($"{i} -> {i.Ordinalize()}");
// 1 -> 1-й
// 2 -> 2-й
// 3 -> 3-й
// 4 -> 4-й
// 5 -> 5-й

// Особые случаи:
Console.WriteLine(21.Ordinalize()); // "21-й"
Console.WriteLine(113.Ordinalize()); // "113-й"

4.4. Bytes() для чисел (размер файлов)

Сигнатура: public static string Bytes(this double bytes, string format = null)

Что делает: Преобразует количество байт в человекочитаемый формат с единицами измерения (B, KB, MB, GB, TB).

long[] sizes = { 500, 1024, 1024 * 1024, 1024 * 1024 * 1024, (long)(1.5 * 1024 * 1024 * 1024) };
foreach (var size in sizes)
    Console.WriteLine($"{size} байт -> {size.Bytes()}");
// 500 байт -> 500 B
// 1024 байт -> 1 KB
// 1048576 байт -> 1 MB
// 1073741824 байт -> 1 GB
// 1610612736 байт -> 1.5 GB

4.5. Humanize() для перечислений (Enum Extensions)

Сигнатура: public static string Humanize(this Enum input)

Что делает: Преобразует значение перечисления в читаемую строку. Учитывает атрибут [Description] и разбивает CamelCase.

enum Status { NotStarted, InProgress, Completed }

Console.WriteLine(Status.NotStarted.Humanize()); // "Not started"
Console.WriteLine(Status.InProgress.Humanize());  // "In progress"

// С атрибутом [Description]:
enum Priority 
{
    [System.ComponentModel.Description("Очень высокий")]
    High,
    [System.ComponentModel.Description("Средний")]
    Medium,
    Low
}
Console.WriteLine(Priority.High.Humanize());   // "Очень высокий"
Console.WriteLine(Priority.Low.Humanize());    // "Low" (без атрибута)

4.6. Dehumanize() для строк

Сигнатура: public static string Dehumanize(this string input)

Что делает: Обратная операция к Humanize() — преобразует читаемую строку обратно в PascalCase.

string humanized = "hello world";
string dehumanized = humanized.Dehumanize();
Console.WriteLine(dehumanized); // "HelloWorld"

string another = "Pascal case string";
Console.WriteLine(another.Dehumanize()); // "PascalCaseString"

4.7. ToRoman() и FromRoman() для чисел

Сигнатура: public static string ToRoman(this int number) и public static int FromRoman(this string roman)

Что делает: Преобразует арабские числа в римские и обратно. Поддерживает числа от 1 до 3999.

int[] numbers = { 1, 4, 9, 42, 99, 2024, 3999 };
foreach (var num in numbers)
    Console.WriteLine($"{num} -> {num.ToRoman()}");

string[] romans = { "I", "IV", "IX", "XLII", "XCIX", "MMXXIV", "MMMCMXCIX" };
foreach (var roman in romans)
    Console.WriteLine($"{roman} -> {roman.FromRoman()}");

4.8. Pluralize() и Singularize() для строк

Сигнатура: public static string Pluralize(this string word, bool inputIsKnownToBeSingular = true) и public static string Singularize(this string word, bool inputIsKnownToBePlural = true)

Что делает: Преобразует существительные между единственным и множественным числом. Работает для английского языка (для русского требуется дополнительная настройка).

string[] words = { "cat", "dog", "child", "mouse", "person", "box", "knife" };
foreach (var word in words)
    Console.WriteLine($"{word} -> {word.Pluralize()}");

string[] plurals = { "cats", "dogs", "children", "mice", "people", "boxes", "knives" };
foreach (var plural in plurals)
    Console.WriteLine($"{plural} -> {plural.Singularize()}");

4.9. Truncate() для строк

Сигнатура: public static string Truncate(this string value, int length, string truncationString = "...", TruncateFrom truncateFrom = TruncateFrom.Right)

Что делает: Обрезает строку до указанной длины, добавляя суффикс (по умолчанию "..."). Можно обрезать слева или справа.

string longString = "Это очень длинная строка, которую нужно обрезать";
Console.WriteLine(longString.Truncate(20));              // "Это очень длинная..."
Console.WriteLine(longString.Truncate(20, ">>"));        // "Это очень длинная>>"
Console.WriteLine(longString