Skip to content

Locale metadata

Translate language, country, script, calendar, and currency codes into their localised display names. Related methods provide text direction, flag emoji, supported values, and likely-subtags expansion. Display methods use the instance locale's subtags when called without an argument.

Method Returns Default argument
Language(code?) localised language name the instance language
Country(code?) localised region/country name the instance region
Script(code?) localised script name the instance script
Calendar(code) localised calendar name —
Currency(code?, symbol?, strict?) currency name or symbol the currency modifier
DisplayName(type, code) any of the above, by type —
Direction(language?) "ltr" / "rtl" the instance locale
Flag(region?) country flag emoji the instance region
SupportedValues(key) values the runtime's ICU supports —
AddLikelySubtags() / RemoveLikelySubtags() a new Cosmo with subtags expanded/collapsed —

Language, country, script, calendar

Each takes a code and returns its name in the instance locale's language — so a fa instance describes everything in Persian.

var fa = new Cosmo("fa");
fa.Language("en");           // "انگلیسی"
fa.Country("AU");            // "استرالیا"

var en = new Cosmo("en");
en.Script("Latn");           // "Latin"
en.Calendar("buddhist");     // "Buddhist Calendar"

Called with no argument, each uses the instance locale: new Cosmo('en_AU')'s Country() returns "Australia", Language() returns "English". Language() and Country() also accept a full locale and pull the right subtag out of it, so Language("pt-BR") → "Portuguese" and Country("pt-BR") → "Brazil".

Generic dispatcher: DisplayName()

When the category is itself a variable (say, you're rendering a settings row by type), DisplayName(type, code) is the single entry point over all of the above:

var c = new Cosmo("en");
c.DisplayName("language", "fr");   // "French"
c.DisplayName("region", "JP");     // "Japan"
c.DisplayName("currency", "EUR");  // "Euro"

type is one of language, region, script, calendar, currency. An unknown type throws.

Currency name & symbol

Currency() is the metadata view of a currency — its localised name (default) or symbol — independent of any amount (for amounts, see Money).

Argument Default Meaning
code the currency modifier ISO 4217 code
symbol false true → the disambiguated symbol, not the name
strict false throw on an unknown code instead of echoing it back
var c = new Cosmo("en-US");
c.Currency("AUD");                  // "Australian Dollar"
c.Currency("AUD", symbol: true);    // "A$"

The symbol form returns the standard, disambiguated symbol ("A$" for AUD in en_US), not the ambiguous narrow "$" — so a price list mixing AUD, USD, and CAD stays unambiguous. Without strict, an unrecognised code is echoed back uppercased (handy for graceful UIs); with strict, it throws so you catch bad data early.

Direction & flag

new Cosmo("fa").Direction();    // "rtl"
new Cosmo("en").Direction();    // "ltr"
new Cosmo("en-AU").Flag();      // "🇦🇺"

Direction() is what you bind to an HTML dir attribute. It resolves likely subtags first, so even a script-only or minority RTL language (ku, ckb) is detected correctly; pass a language/locale to test one other than the instance. Flag() is pure Unicode codepoint math (region letters → regional-indicator symbols), so no data table is involved — it returns "" for anything that isn't a two-letter region.

Supported values

SupportedValues(key) lists everything the runtime's ICU can handle for a given category — useful to populate a dropdown without hardcoding a list that drifts from the engine:

key Yields
calendar gregory, persian, buddhist, …
collation standard, phonebook, pinyin, …
currency every ISO 4217 code
numberingSystem latn, arab, deva, …
timeZone every IANA zone
new Cosmo("en").SupportedValues("currency").Count;    // e.g. 300+
new Cosmo("en").SupportedValues("calendar");          // ["buddhist", "chinese", …]
// "unit" throws CosmoUnsupportedException — not exposed in the ICU C API

The transliterator key lists available transforms. The unit key is unsupported because the wrapper cannot enumerate measure units. An unknown key throws.

Likely subtags

ICU can expand a terse locale to its most likely full form and back — AddLikelySubtags() returns a new Cosmo with the script/region filled in, RemoveLikelySubtags() strips the redundant ones:

new Cosmo("en").AddLikelySubtags().Locale;          // "en_Latn_US"
new Cosmo("en_Latn_US").RemoveLikelySubtags().Locale; // "en"

Practical examples

A language switcher. Render each supported locale's endonym (its name in its own language) alongside its flag and direction:

var supported = new[] { "en-US", "fr-FR", "ar-EG", "ja-JP" };
var menu = supported.Select(tag => {
    var c = new Cosmo(tag);
    return new { tag, label = c.Language(), flag = c.Flag(), dir = c.Direction() };
}).ToList();
// { tag: "ar-EG", label: "العربية", flag: "🇪🇬", dir: "rtl" }, …

A native-name picker, sorted for the user. Build names in the user's locale, then Sort() them with that locale's collator so the list reads naturally.