Formatting and Localization Options

This feature allows developers to tailor the appearance and cultural formatting of the converted word output, ensuring that the result meets regional or custom display requirements.

Overview

The Formatting & Localization Options feature provides developers with properties and methods to adjust the output of the number-to-word conversion. These options include setting culture-specific formatting, customizing separators, enabling ordinal representation, and capitalizing the first letter. In addition, there are helper methods to format the number in various representations such as custom grouping, scientific notation, and Roman numerals.

---

Key Points

Key Point	Description
Culture customization	The Culture property lets you define locale-specific formatting rules for the conversion process.
Custom separators	Use the CustomSeparator property to override the default word separator ("and") with your custom string.
Ordinal and capitalization options	The UseOrdinalNumbers and CapitalizeFirst properties enable conversion to ordinal forms and adjust text case.
Additional formatting methods	Helper methods like FormatWithCustomGrouping, GetScientificNotation, and ToRomanNumerals provide extra formatting capabilities.

---

Best Practices

Best Practice	Description
Set Culture early in the lifecycle	Configure the Culture property early in your application to ensure consistent localization across conversions.
Adjust custom separators to match design	Use CustomSeparator if the default "and" does not align with your application's language or design style.
Enable ordinal formatting only when necessary	Activate UseOrdinalNumbers for specific scenarios (like rankings or positions) to avoid misrepresentation.
Use formatting methods for specialized displays	Leverage helper methods for non-standard representations (e.g., scientific or Roman numerals) as needed.

---

Common Pitfalls

Pitfall	Description
Incorrect culture settings	Failing to set the Culture property may result in unexpected formatting that does not match user expectations.
Over-customizing separators	Changing CustomSeparator without proper testing might lead to grammatically incorrect output.
Inconsistent text case handling	Not enabling CapitalizeFirst when required may result in lower-case output that may not be suitable for titles.
Misusing ordinal conversion	Enabling UseOrdinalNumbers indiscriminately can cause non-ordinal contexts to display incorrectly.

---

Usage Scenarios

Scenario	Description
Localized number-to-word conversion	Use the Culture property to adapt the conversion process for different regional formats (e.g., using "and" vs. localized conjunctions).
Custom UI displays with tailored separators	Adjust the CustomSeparator to match the application's style guidelines or language-specific requirements.
Converting numbers into ordinal form	Enable UseOrdinalNumbers to display numbers as "first", "second", etc., for applications like leaderboards or rankings.
Capitalizing output for headlines or titles	Use CapitalizeFirst to automatically capitalize the first letter of the converted output for better presentation.

---

Real Life Usage Scenarios

Scenario	Description
Multilingual applications	In apps targeting multiple regions, setting the Culture ensures that numbers are converted in accordance with local norms.
Financial reports and documents	Custom separators and capitalization can help format checks or financial documents where both numeric and word representations are necessary.
Educational software	For learning tools, converting numbers into both cardinal and ordinal forms provides clarity and reinforces language learning.

---

Troubleshooting Tips

Issue	Possible Cause	Recommended Action
Unexpected formatting output	The default culture or custom separator settings may not be aligned with user expectations.	Double-check the values of Culture, CustomSeparator, UseOrdinalNumbers, and CapitalizeFirst.
Inconsistent capitalization	The CapitalizeFirst property might be disabled.	Enable CapitalizeFirst if a title-case representation is required.
Incorrect ordinal output	The UseOrdinalNumbers property could be incorrectly applied to contexts not requiring ordinal conversion.	Ensure that ordinal formatting is only enabled when contextually appropriate.

---

Code Examples

Example 1: Setting Culture and Custom Separator

using System.Globalization;
using SiticoneNetFrameworkUI;

// Create an instance of the control
var humanizer = new SiticoneHumanizerLong();

// Set a specific culture (e.g., en-GB for British English)
humanizer.Culture = new CultureInfo("en-GB");

// Customize the separator from "and" to a comma
humanizer.CustomSeparator = ",";

// Set a numeric value
humanizer.Value = 1500;

// Output the converted words
Console.WriteLine("Converted Words: " + humanizer.Words);

Example 2: Enabling Ordinal Conversion and Capitalization

using SiticoneNetFrameworkUI;

// Create an instance of the control
var humanizer = new SiticoneHumanizerLong();

// Enable ordinal number conversion
humanizer.UseOrdinalNumbers = true;

// Enable capitalization of the first letter
humanizer.CapitalizeFirst = true;

// Set a numeric value to see the ordinal and capitalized output
humanizer.Value = 3;

// Output the formatted words
Console.WriteLine("Converted Words: " + humanizer.Words);

Example 3: Using Helper Formatting Methods

using System;
using SiticoneNetFrameworkUI;

// Create an instance of the control
var humanizer = new SiticoneHumanizerLong();

// Set a numeric value
humanizer.Value = 2560;

// Get custom grouping format (e.g., using a dot as thousand separator)
string customGrouping = humanizer.FormatWithCustomGrouping(groupSeparator: ".", decimalSeparator: ",");
Console.WriteLine("Custom Grouping: " + customGrouping);

// Get scientific notation
string scientificNotation = humanizer.GetScientificNotation(3);
Console.WriteLine("Scientific Notation: " + scientificNotation);

// Convert to Roman numerals (ensure the value is within 1-3999)
humanizer.Value = 1999;
string romanNumeral = humanizer.ToRomanNumerals();
Console.WriteLine("Roman Numerals: " + romanNumeral);

---

Review

Aspect	Review Comments
Customization flexibility	Offers extensive customization through culture settings, custom separators, and text formatting options.
Integration ease	Integrates seamlessly into various applications with clear, property-based configuration.
Versatility	The helper methods for different formatting representations (e.g., scientific and Roman numerals) enhance overall utility.

---

Summary

Summary Statement	Description
Formatting & Localization Options enable culturally appropriate and stylistically tailored conversions	This feature empowers developers to adjust the number-to-word conversion output through culture settings, custom separators, ordinal conversion, and additional helper formatting methods to suit diverse application requirements.

---

Additional Useful Sections

Integration Checklist

Checklist Item	Status/Notes
Set Culture property	Ensure the Culture property is set early to maintain consistent localization.
Configure custom separators	Adjust the CustomSeparator based on application design and language.
Enable appropriate formatting options	Toggle UseOrdinalNumbers and CapitalizeFirst based on the context of the output display.
Test helper methods	Verify the outputs of FormatWithCustomGrouping, GetScientificNotation, and ToRomanNumerals for expected formats.

FAQ

Question	Answer
How do I adjust the output to match local language rules?	Set the Culture property to the appropriate locale (e.g., "en-US", "fr-FR") to adhere to regional formatting.
Can I change the default separator used in the conversion?	Yes, modify the CustomSeparator property to use a different string in place of the default "and".
What if I need the first letter capitalized in the result?	Enable the CapitalizeFirst property to ensure the converted output starts with an uppercase letter.
How can I display numbers in scientific notation?	Use the GetScientificNotation method, specifying the number of decimals if necessary.

---

This comprehensive documentation for the Formatting & Localization Options feature provides developers with detailed guidance on how to customize the conversion output, ensuring that the converted words match regional, stylistic, and application-specific requirements.