Getting started¶
Requirements¶
- Node.js: 20+ with ICU data for the locales you use.
duration()additionally requiresIntl.DurationFormat, available in Node.js 23.0.0+. - Browsers: native ES modules and ES2022 support, plus the
IntlAPIs used by the methods you call. For all methods in the JavaScript port, the API requirements give these minimum versions:
| Browser | Minimum version |
|---|---|
| Chrome / Edge | 129 |
| Firefox | 153 |
| Safari / iOS Safari | 16.4 |
For method-specific requirements, see Older browser support.
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.
import { Cosmo } from "@miloun/cosmo";
const c = new Cosmo("en-AU", { timeZone: "Australia/Sydney" });
c.country(); // "Australia"
c.money(1234.5, "AUD"); // "$1,234.50" (JS needs an explicit currency)
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:
Cosmo.fromSubtags({ language: "en", region: "AU" });
Cosmo.fromAcceptLanguage(req.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/javascript/getting-started/ and
https://cosmo.miloun.com/javascript/api-reference/. Check
https://cosmo.miloun.com/javascript/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.
Older browser support¶
Older browsers can run methods whose required APIs they support:
| Cosmo methods | Required API | Chrome / Edge | Firefox | Safari |
|---|---|---|---|---|
contains(), splitWords(), splitSentences(), splitGraphemes(), ellipsize() |
Intl.Segmenter |
87+ | 125+ | 14.1+ |
numberRange(), moneyRange() |
Intl.NumberFormat.prototype.formatRange |
106+ | 116+ | 15.4+ |
duration() |
Intl.DurationFormat |
129+ | 136+ | 16.4+ |
weekInfo() |
Intl.Locale.prototype.getWeekInfo() or the older weekInfo accessor |
99+ | 153+ | 15.4+ |
direction() |
Intl.Locale.prototype.getTextInfo() or the older textInfo accessor |
99+ | 153+ | 15.4+ |
These version requirements are derived from the APIs used by Cosmo and MDN browser compatibility data; they are not a browser test matrix. The runtime must also include data for your requested locales. Cosmo does not bundle polyfills or locale data.