Skip to content

Getting started

Requirements

  • Node.js: 20+ with ICU data for the locales you use. duration() additionally requires Intl.DurationFormat, available in Node.js 23.0.0+.
  • Browsers: native ES modules and ES2022 support, plus the Intl APIs 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

npm install @miloun/cosmo

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.