Siticone Humanizer DateTime

The SiticoneHumanizerDateTime is a powerful non-visual component that transforms raw DateTime objects into human-friendly, conversational strings. Instead of displaying "12/05/2023 14:30:00", it outputs phrases like "2 hours ago", "in 5 minutes", or "yesterday". It supports extensive customization, including seasonal context, adaptive precision, relative day naming, and full localization support.

Core Data

The fundamental properties that define the input for the humanizer component.

Property	Type	Description & Usage Example
`Date`	DateTime	humanizer.Date = DateTime.Now.AddMinutes(-5); The primary DateTime value to process. Changing this property immediately updates the `Humanize` output.
`PreferredKind`	DateTimeKind	humanizer.PreferredKind = DateTimeKind.Utc; Determines the time zone context (Local or UTC) used for calculating the difference from "now".
`Humanize`	string	lblTime.Text = humanizer.Humanize; Read-Only. Returns the calculated, formatted string (e.g., "5 minutes ago").

Formatting Options

Control the structure and style of the output text.

Property	Type	Description & Usage Example
`TimeFormat`	TimeSpanFormat	humanizer.TimeFormat = TimeSpanFormat.Natural; Selects the output style. Options: `Standard`, `Detailed`, `Concise`, `Natural`, `Custom`.
`UseRelativeDays`	bool	humanizer.UseRelativeDays = true; Replaces exact time spans with relative terms like "yesterday", "today", or "tomorrow" where applicable.
`UseAbbreviations`	bool	humanizer.UseAbbreviations = true; Shortens units to their abbreviated forms (e.g., "5 mins ago", "2 yrs from now").
`UseSeasonalContext`	bool	humanizer.UseSeasonalContext = true; Appends seasonal information to the output (e.g., "in 5 months in winter").
`CustomFormat`	string	humanizer.CustomFormat = "{H} hours and {m} mins {DIR}"; Defines a custom pattern when `TimeFormat` is set to `Custom`.

Precision & Calculation

Fine-tune how time differences are calculated and how much detail is shown.

Property	Type	Description & Usage Example
`CalculationMode`	TimeCalculationMode	humanizer.CalculationMode = TimeCalculationMode.Calendar; Controls the calculation logic. Options: `Calendar` (Standard), `Fixed` (30-day months), `Astronomical`.
`MaxPrecision`	int	humanizer.MaxPrecision = 2; Limits the number of time units displayed (e.g., "2 years, 3 months" vs "2 years, 3 months, 4 days, 5 hours"). Max 4.
`AdaptivePrecision`	bool	humanizer.AdaptivePrecision = true; Automatically adjusts precision based on the magnitude of the time span (e.g., shows fewer details for dates far in the past).
`IncludeMilliseconds`	bool	humanizer.IncludeMilliseconds = true; Includes milliseconds in the output for high-precision scenarios.

Localization & Customization

Adapt the component for different languages and custom terminologies.

Property/Method	Type	Description & Usage Example
`Culture`	CultureInfo	humanizer.Culture = new CultureInfo("fr-FR"); Sets the cultural context for formatting numbers and dates.
`AddCustomTranslation`	Method	humanizer.AddCustomTranslation("just_now", "instantly"); Overrides specific phrase keys (e.g., "just_now", "yesterday", "tomorrow") with custom text.
`ClearCustomTranslations`	Method	humanizer.ClearCustomTranslations(); Resets all custom translations back to their default English values.

Designer Support

The component offers a comprehensive Smart Tag menu in Visual Studio for rapid configuration without coding.

Feature Category	Capabilities
`Format Presets`	One-click options to apply common styles: Standard, Detailed, Concise, Natural, and Abbreviated.
`Date Presets`	Quickly test the output by setting the date to: Yesterday, Tomorrow, Last Week, Next Month, etc.
`Calculation Setup`	Visual toggles for Adaptive Precision, Relative Days, and Calculation Mode.
`Actions`	View Output Preview: Shows a message box with the current humanized string. Copy/Paste Settings: Transfer configuration between components.

Detailed Usage Examples

Example 1: Chat Message Timestamp

Format a message timestamp using natural language (e.g., "just now", "5 mins ago").

C# - Chat Implementation

private void DisplayMessageTime(DateTime messageSentTime)
{
    humanizer1.Date = messageSentTime;
    humanizer1.TimeFormat = SiticoneHumanizerDateTime.TimeSpanFormat.Concise;
    humanizer1.UseAbbreviations = true;
    humanizer1.UseRelativeDays = true;
    
                // Override "just now" for a snappier feel
    humanizer1.AddCustomTranslation("just_now", "now");
    
    lblTime.Text = humanizer1.Humanize; 
                // Output examples: "now", "5 mins ago", "yesterday"
}

Example 2: Project Deadline Countdown

Display a detailed countdown to a future event.

C# - Countdown Logic

private void UpdateCountdown()
{
    humanizer1.Date = _deadlineDate; // Future date
    humanizer1.TimeFormat = SiticoneHumanizerDateTime.TimeSpanFormat.Detailed;
    humanizer1.MaxPrecision = 3; // Show up to 3 units (e.g., days, hours, mins)
    humanizer1.UseSeasonalContext = false;
    
    lblDeadline.Text = "Due " + humanizer1.Humanize;
                // Output: "Due 2 days, 4 hours, 15 minutes from now"
}

Example 3: Custom Format Pattern

Using the Custom format to create a specific log file timestamp style.

C# - Custom Formatting

private string GetLogTimestamp(DateTime eventTime)
{
    humanizer1.Date = eventTime;
    humanizer1.TimeFormat = SiticoneHumanizerDateTime.TimeSpanFormat.Custom;
    
                // Define pattern: {H} hours, {m} minutes ({DIR})
    humanizer1.CustomFormat = "[{H}h:{m}m {DIR}]";
    
    return humanizer1.Humanize;
                // Output: "[0h:45m ago]" or "[2h:10m from now]"
}