Terminology & naming¶

Cosmo deliberately uses one vocabulary across all four ports (PHP, JavaScript, Python, Java). A moment is a moment everywhere; a duration never quietly means a range. This page defines those words so a method name tells you what it does before you read its signature — and so the guides can stay terse.

Why this matters

Most i18n bugs are vocabulary bugs: passing a duration where a moment is expected, or asking for a range when you meant relative time. The names below are chosen so the confusable cases stay visibly distinct.

Naming conventions¶

The method names are identical in every port, with one mechanical difference:

Convention	PHP / JavaScript / Java	Python
Method casing	`camelCase` — `timeZoneName()`, `relativeDuration()`	`snake_case` — `time_zone_name()`, `relative_duration()`
Factory helpers	`fromSubtags()`, `fromAcceptLanguage()`	`from_subtags()`, `from_accept_language()`
Option-bag keys	`camelCase` — `minimumFractionDigits`	`camelCase` (kept identical on purpose)

So a guide that writes relativeDuration() always means relative_duration() in Python — the same operation, never a different one. Option-bag keys stay camelCase in all four ports (including Python) so a JSON config travels between languages unchanged.

The temporal vocabulary¶

These five words are the ones most often confused. They name genuinely different things:

Term	What it is	Has a direction?	Typical input	Method
Moment	A single point on the timeline (a date and a time together)	—	native date/time value	`moment()`
Date	The calendar-date part of a moment (year-month-day)	—	a moment	`date()`
Time	The clock-time part of a moment (hour-minute-second)	—	a moment	`time()`
Duration	The magnitude of a span — "how long", no past/future	No (undirected)	seconds, or a unit breakdown	`duration()`
Relative duration	A span oriented toward past or future — "3 days ago", "in 2 hours"	Yes (directed)	signed value + unit	`relativeDuration()`
Range	The interval between two values	—	two endpoints	`dateRange()`

Moment, not 'date'

The argument that carries a point in time is a moment — it accepts your language's native value (a DateTime / Date / datetime / java.util.Date, or a Unix timestamp). Watch the unit: JavaScript counts milliseconds; PHP, Python, and Java count seconds. See Dates & times.

Duration vs relative duration

duration(1222060) → "339:27:40" — a bare magnitude. relativeDuration(-3, "day") → "3 days ago" — the same idea of elapsed time, but directed. If you catch yourself wanting "ago" or "in" out of duration(), you want relativeDuration() instead.

Core objects¶

Term	Meaning
Locale	The identifier for a language + region + preferences — `en_AU`, `fa-IR`, or a full BCP-47 tag like `fa-IR-u-nu-latn-ca-buddhist`. Underscore and hyphen forms are both accepted.
Instance	A constructed `Cosmo` object, bound to one locale and its modifiers. You build it once and call methods on it.
Subtags	The pieces a locale decomposes into — `language`, `script`, `region`. You can construct from them directly with `fromSubtags()`.
Modifiers	The optional settings layered onto a locale at construction: `timeZone`, `calendar`, `currency`. An options bag in PHP/JS/Python; a typed `Modifiers` value class in Java.
Options bag	A per-call settings object (e.g. rounding/grouping options on `number()`). Keys are `camelCase` in every port.
Width	The verbosity of a formatted result, one scale shared by dates, units, and more: `none` · `short` · `medium` · `long` · `full`.

Numbers & money¶

Term	Meaning
Number	A locale-formatted decimal — grouping and decimal separators per locale.
Percentage	Formats a fraction as a percent (`0.2` → `"20%"`).
Unit	A measured quantity with its unit (`2.19 gigabytes`, `26°C`).
Money	A currency amount, formatted with the currency's symbol and placement. Cosmo only formats — it never converts between currencies.
Currency	The currency itself (its localised name or disambiguated symbol), independent of any amount.
Compact	Short magnitude notation — `1.2K`, `1.2 thousand`.
Scientific	Exponential notation — `1.2345E4`.
Spellout	A number written in words — `"one hundred twenty"`.
Ordinal	Ordinal text — `"2nd"`. (For the ordinal plural category, see Messages & plurals.)
Symbol	A locale's notation symbol by name — e.g. the decimal mark `"٫"` in `fa`.

Money is not currency conversion

money(100, "AUD") formats 100 AUD in the locale's style. It does not convert 100 of anything into AUD — convert the amount yourself first. See Money & currency.

Locale, text & people¶

Term	Meaning
Language / Country / Script / Calendar	The localised display name of a code — `language("en")` in `fa` → `"انگلیسی"`.
Direction	The locale's text direction — `"ltr"` or `"rtl"`.
Time zone	An IANA zone (`Australia/Sydney`); `timeZoneName()` gives its localised name.
Plural category	The CLDR plural class of a number (`one`, `few`, `many`, …) used to choose message forms. See Messages & plurals.
Collation	Locale-correct string ordering (sorting) — distinct from byte order. See Collation & text.
Transliterate / Romanize	Convert text between scripts; romanize is the to-Latin-then-ASCII special case (good for slugs). See Transliteration & parsing.
Confusable / Suspicious	Spoof detection (UTS #39): whether two strings look alike, or one string is spoof-prone.
Parse	The inverse of a formatter — turn locale-formatted text back into a value (`parseNumber`, `parseMoney`, `parseDate`).
Negotiation	Choosing the best of your supported locales for a user, via CLDR language distance — see Negotiation & names.
Index buckets	Alphabetical section headers for a list (A–Z, 가나다, あかさ…).
Person name	A name formatted in the culture's order, spacing, and script.

Not every term is available in every port

The vocabulary is shared, but a few operations depend on a raw-ICU service the Intl API doesn't expose (parsing, transliteration, person names, …). Each guide flags its availability, and the Feature parity matrix and Platform notes give the full picture.