Custom Translations

Custom Translations allows developers to override or extend the default text strings used in humanizing date/time output, enabling localization and personalization.

Overview

The Custom Translations feature of the SiticoneHumanizerDateTime control provides methods to add, retrieve, and clear custom translation strings. This allows developers to tailor key phrases—such as "just now," "yesterday," or "in a moment"—to better fit the language and style of their application.

Method	Description
AddCustomTranslation(string key, string value)	Adds or updates a custom translation for a specific key.
ClearCustomTranslations()	Clears all custom translations and resets them to their default values.
GetCustomTranslations()	Retrieves a copy of the current custom translations as a dictionary.

Key Points

Aspect	Detail
Customization Flexibility	Allows overriding of default translation strings to suit localized or branded content.
Runtime Modification	Translations can be added, updated, or cleared during runtime, providing dynamic control over output.
Consistency in Output	Ensures that all humanized output adheres to the custom phrases defined by the developer.

Best Practices

Practice	Recommendation
Define Translations Early	Set up custom translations at application startup to maintain consistency throughout the application lifecycle.
Validate Translation Keys	Ensure that translation keys are non-empty and match those used internally (e.g., "just_now", "yesterday").
Test Localization	Verify that translations appear correctly in different cultural contexts and languages.

Common Pitfalls

Pitfall	Explanation
Using Incorrect Keys	Using translation keys that do not match the control’s internal keys will result in no changes to the output.
Overwriting Essential Defaults	Overwriting default values without providing meaningful replacements can lead to confusing or unintuitive messages.
Neglecting to Restore Defaults	Failing to use ClearCustomTranslations() when needed might cause persistent incorrect translations across the application.

Usage Scenarios

Scenario	Details
Application Localization	Modify the default phrases to match the language and cultural norms of your target audience.
Brand-Specific Messaging	Customize the humanized output to align with your application’s tone and style.
Dynamic Translation Updates	Change translations at runtime based on user preferences or configuration settings.

Real Life Usage Scenarios

Scenario	Details
Multi-Language Support	In a global application, use AddCustomTranslation to provide region-specific phrases for time descriptions.
Themed User Interfaces	For applications with a specific theme (e.g., retro, modern), customize translations to enhance the overall aesthetic.
User-Centric Customization	Allow users to choose their preferred phrases for time descriptions, storing these preferences via custom translations.

Troubleshooting Tips

Issue	Solution
Custom Translation Not Appearing	Confirm that the translation key passed to AddCustomTranslation matches the internal key (e.g., "just_now").
Unintended Overwrites	Check that your custom translation values are correctly assigned and not inadvertently replaced by default initialization.
Persistence Issues	If translations seem to persist or not reset, ensure that ClearCustomTranslations() is being called appropriately when required.

Code Samples and Integration Examples

Adding Custom Translations

using System;
using SiticoneNetFrameworkUI;

namespace CustomTranslationsDemo
{
    public class TranslationDemo
    {
        public static void Main()
        {
            // Create an instance of the humanizer control
            SiticoneHumanizerDateTime humanizer = new SiticoneHumanizerDateTime();

            // Add custom translations
            humanizer.AddCustomTranslation("just_now", "right now");
            humanizer.AddCustomTranslation("yesterday", "the day before");
            humanizer.AddCustomTranslation("tomorrow", "the next day");

            // Set a date value to demonstrate the custom translation
            humanizer.Date = DateTime.Now.AddSeconds(-10);

            // Output the humanized result using custom translations
            Console.WriteLine("Custom Translated Output: " + humanizer.Humanize);
        }
    }
}

Retrieving and Clearing Custom Translations

using System;
using System.Collections.Generic;
using SiticoneNetFrameworkUI;

namespace CustomTranslationsDemo
{
    public class RetrieveClearDemo
    {
        public static void Main()
        {
            // Instantiate the humanizer control
            SiticoneHumanizerDateTime humanizer = new SiticoneHumanizerDateTime();

            // Retrieve current custom translations
            Dictionary<string, string> translations = humanizer.GetCustomTranslations();
            Console.WriteLine("Current Translations:");
            foreach (var item in translations)
            {
                Console.WriteLine($"{item.Key} : {item.Value}");
            }

            // Clear all custom translations (resets to default)
            humanizer.ClearCustomTranslations();
            Console.WriteLine("Custom translations have been reset.");
        }
    }
}

Review

Aspect	Comment
Customization	Custom Translations offer an effective way to adapt the language of the humanized output to meet localization or branding needs.
Flexibility	The ability to add, retrieve, and clear translations at runtime provides dynamic control over output messaging.
Ease of Integration	Simple methods ensure that developers can quickly implement and modify translation strings with minimal code.

Summary

Summary Aspect	Description
Customization Capability	Enables developers to override default translation strings to match specific localization or branding requirements.
Runtime Flexibility	Provides methods to dynamically modify or reset translations, ensuring that changes can be made without redeploying the application.
Consistent Output	Ensures that all humanized outputs reflect the customized language, enhancing user experience and coherence.

Frequently Asked Questions (FAQ)

Question	Answer
How do I add a new custom translation?	Use the AddCustomTranslation(string key, string value) method, ensuring the key matches one of the internal translation keys.
What keys can be customized?	Keys such as "just_now", "yesterday", "tomorrow", and others used internally by the control can be overridden.
How do I reset translations to their defaults?	Call the ClearCustomTranslations() method to remove all custom translations and restore the default values.

Tips for Developers

Tip	Recommendation
Validate Keys Before Adding	Always ensure that the translation key provided is valid and matches the control's expected keys to avoid silent failures.
Document Custom Translations	Maintain documentation for custom translations used in your application to facilitate future updates and troubleshooting.
Test Across Locales	When localizing, verify that custom translations render correctly across different cultures and languages by setting the appropriate Culture.

---

By following this documentation for Custom Translations, developers can seamlessly integrate and tailor the SiticoneHumanizerDateTime control to deliver localized and branded humanized date/time outputs within their .NET WinForms applications.