Skip to content

Negotiation & names

Choose the closest supported locale for a user and build alphabetical indexes for contact lists. You can also format person names with locale-specific ordering and spacing.

Method Use it for
bestMatch(supported) Choose the closest supported locale
fromAcceptLanguage(header, supported) Negotiate from an HTTP header
indexBuckets(names) Build alphabetical section headers
personName(fields) Format a person's name

Best-match locale negotiation

fromAcceptLanguage(header) alone just parses the header and picks the highest-quality tag. Passing your supported locales enables CLDR language-distance matching. This chooses the closest supported locale, falling back to the first entry when none is close.

// Which of MY locales best serves this user?
new Cosmo("en_AU").bestMatch(List.of("en-US", "en-GB", "fr")); // "en-GB"
new Cosmo("ja").bestMatch(List.of("fr", "de"));                // "fr" (fallback)

// Negotiate straight from an Accept-Language header:
Cosmo c = Cosmo.fromAcceptLanguage("fr-CH, en;q=0.9", List.of("en-US", "fr-FR"));
c.locale; // "fr_FR"  (public final field)

Why language distance beats prefix matching: en_AU is served better by en-GB than en-US (closer English variant); sr-Latn maps to hr over sr-Cyrl (shared script wins); nn (Nynorsk) falls back to nb (Bokmål). These matches use language and script relationships that prefix matching cannot express. An empty supported list throws.

Order your supported list by preference

The first entry is the fallback when nothing matches, so put your default locale first. Everything after it is reachable only when it's genuinely the closest.

Alphabetical index buckets

indexBuckets(names) groups strings under the locale's index headers — A–Z in English, but 가나다 in Korean, あかさ in Japanese, А–Я in Russian — with each bucket collation-ordered. These are the section headers you'd run down the side of a contact list. Empty buckets are omitted.

Map<String, List<String>> buckets =
    new Cosmo("en").indexBuckets(List.of("banana", "apple", "Cherry", "avocado"));
buckets.keySet();      // [A, B, C]
buckets.get("A");      // [apple, avocado]

The buckets come back in index order (an ordered map / LinkedHashMap), so you can iterate straight into your UI without re-sorting. Names that don't fit any letter bucket land in an overflow bucket (often #).

Person names

personName(fields) formats a name with the locale's ordering, spacing, and script conventions — surname-first where appropriate, no space in CJK, locale-aware initials. You pass a map of name parts; two optional keys refine the output.

Field keys:

Key Meaning
given Given (first) name
given2 Middle name(s)
surname Family name
surname2 Second family name (e.g. Spanish)
title Honorific (Dr., Ms.)
generation Jr., Sr., III
credentials Post-nominals (PhD, MD)
locale The name's own locale — so a Japanese name renders correctly even from an en formatter

Refinement options (pass alongside the fields):

Option Values Effect
length short · medium · long How many parts to include
formality formal · informal Full name vs familiar form
import java.util.Map;

// Western order:
new Cosmo("en").personName(Map.of("given", "John", "surname", "Smith"));
// "John Smith"

// Japanese: surname first, no separating space — driven by the name's own locale:
new Cosmo("ja").personName(Map.of(
    "given", "太郎", "surname", "山田", "locale", "ja"));
// "山田太郎"

// Informal, given name only:
new Cosmo("en").personName(Map.of(
    "given", "John", "surname", "Smith", "formality", "informal", "length", "short"));
// "John"

Technology preview

ICU labels PersonNameFormatter a technology preview. Formatting may change as its CLDR data evolves.

Practical examples

An HTTP request handler that picks the right locale. Negotiate once, then build every formatter from the chosen locale:

static final List<String> SUPPORTED = List.of("en-US", "fr-FR", "de-DE", "ja-JP");

Response handle(Request request) {
    String header = request.header("Accept-Language");
    Cosmo c = Cosmo.fromAcceptLanguage(header, SUPPORTED);
    return render(c.message("Welcome to {0}", "Acme"), c.locale, c.direction());
}