Skip to content

Getting started

Requirements

  • Java 11+. ICU4J (com.ibm.icu:icu4j) is pulled in transitively — it bundles its own ICU data, so there is no system library to install.

Install

<dependency>
  <groupId>com.miloun</groupId>
  <artifactId>cosmo</artifactId>
  <version>1.0.0</version>
</dependency>

Gradle: implementation("com.miloun:cosmo:1.0.0").

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 com.miloun.cosmo.Cosmo;
import com.miloun.cosmo.Modifiers;

// Modifiers(calendar, currency, timeZone) — any field may be null.
Cosmo c = new Cosmo("en_AU", new Modifiers(null, null, "Australia/Sydney"));

c.country();            // "Australia"
c.money(1234.5);        // "$1,234.50"  (currency inferred from region)
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:

// Subtags(language, script, region)
Cosmo.fromSubtags(new Subtags("en", null, "AU"));
Cosmo.fromAcceptLanguage(request.getHeader("Accept-Language"));

// Java adds a CLDR-negotiating overload against your supported locales:
Cosmo.fromAcceptLanguage(header, List.of("en-GB", "fr-FR", "de-DE"));

Negotiating against your own locales

Pass your supported locales to choose the closest match using CLDR language distance. See Negotiation & names.

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/java/getting-started/ and
https://cosmo.miloun.com/java/api-reference/. Check
https://cosmo.miloun.com/java/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.