# Formatting and Localization Options

## 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

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

***

### Best Practices

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

***

### Common Pitfalls

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

***

### Usage Scenarios

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

***

### Real Life Usage Scenarios

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

***

### Troubleshooting Tips

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

***

### Code Examples

#### Example 1: Setting Culture and Custom Separator

```csharp
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

```csharp
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

```csharp
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

<table><thead><tr><th width="226">Aspect</th><th>Review Comments</th></tr></thead><tbody><tr><td>Customization flexibility</td><td>Offers extensive customization through culture settings, custom separators, and text formatting options.</td></tr><tr><td>Integration ease</td><td>Integrates seamlessly into various applications with clear, property-based configuration.</td></tr><tr><td>Versatility</td><td>The helper methods for different formatting representations (e.g., scientific and Roman numerals) enhance overall utility.</td></tr></tbody></table>

***

### Summary

<table><thead><tr><th width="355">Summary Statement</th><th>Description</th></tr></thead><tbody><tr><td>Formatting &#x26; Localization Options enable culturally appropriate and stylistically tailored conversions</td><td>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.</td></tr></tbody></table>

***

### Additional Useful Sections

#### Integration Checklist

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

#### 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.