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());
}