Getting started¶
Requirements¶
- .NET 8+. The NuGet package bundles the ICU4C native libraries, so there is no system-level ICU to install.
Install¶
Quick start¶
Construct with a locale (and an optional time zone, calendar, or currency modifier), then call methods on it. New to these codes? See Locales & time zones.
using Miloun.Cosmo;
// Modifiers(calendar, currency, timeZone) — any field may be null.
var c = new Cosmo("en-AU", new Modifiers(timeZone: "Australia/Sydney"));
c.Country(); // "Australia"
c.Money(1234.5); // "$1,234.50" (currency inferred from region)
c.Number(1234567.89); // "1,234,567.89"
c.Flag(); // "🇦🇺"
Locale format
Underscore locales (en_AU) and BCP-47 tags (en-AU), including Unicode
extensions like fa-IR-u-nu-latn-ca-buddhist, are supported. Use hyphens
in locale tags, such as en-AU. See
Locales & time zones for the format explained and how to
find yours.
Constructing without a string¶
Build a locale from subtags or an HTTP Accept-Language header:
// Subtags(language, script, region)
Cosmo.FromSubtags(new Subtags("en", "", "AU"));
Cosmo.FromAcceptLanguage(request.Headers["Accept-Language"]);
Migrating existing localisation code¶
If your app already has custom formatting helpers or locale tables, you can use this prompt with a coding assistant that has access to your project:
Migrate this project's custom localisation code to Cosmo.
Read https://cosmo.miloun.com/csharp/getting-started/ and
https://cosmo.miloun.com/csharp/api-reference/. Check
https://cosmo.miloun.com/csharp/platform-notes/ for runtime limitations.
Inspect the project to identify its language, runtime versions, locale and
time-zone settings, and existing localisation helpers. Find custom code for
number, currency, date, time, unit, list, plural, and text formatting, along
with any hardcoded locale data that Cosmo can replace.
Install the appropriate Cosmo package and migrate supported operations using
the documented API for this language. Reuse the app's locale, time zone,
calendar, and currency settings. Keep business rules, currency conversion,
and translation catalogue management in place unless a documented Cosmo
feature covers the existing behaviour.
Preserve public interfaces where practical. Check timestamp units, rounding,
currency precision, plural rules, and error handling at each migrated call
site. If ICU formatting changes the displayed output, explain the difference
rather than assuming it is equivalent. Keep unsupported operations working
and identify why they could not be migrated.
Update or add tests for representative supported locales and important edge
cases, then run the relevant checks. Remove obsolete helpers and locale tables
once their callers have been migrated. Summarise the changes, output differences,
and any remaining custom localisation code.
Review the resulting changes, especially where existing output is part of a public API or an exact string comparison. Locale conventions and ICU versions can affect spacing, punctuation, and wording.
Ready for the details? Head to the Guide.