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 —

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.

$fa = new Cosmo('fa');
$fa->language('en');          // "انگلیسی"
$fa->country('AU');           // "استرالیا"

$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:

$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
$c = new Cosmo('en_US');
$c->currency('AUD');            // "Australian Dollar"  (localised name)
$c->currency('AUD', true);      // "A$"                 (disambiguated symbol)

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
currency every ISO 4217 code
timeZone every IANA zone
count(new Cosmo('en')->supportedValues('currency'));  // e.g. 300+
new Cosmo('en')->supportedValues('calendar');         // ['buddhist', 'chinese', …]

The transliterator key lists available transforms. An unknown key throws.

Practical examples

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

$supported = ['en-US', 'fr-FR', 'ar-EG', 'ja-JP'];
$menu = array_map(function ($tag) {
  $c = new Cosmo($tag);
  return ['tag' => $tag, 'label' => $c->language(), 'flag' => $c->flag(), 'dir' => $c->direction()];
}, $supported);

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.