Signatur
Beschreibung
Intl.Locale ist ein eingebautes Objekt des Intl-Namensraums, das einen vollständigen Unicode-Locale-Identifikator kapselt – also eine Kombination aus Sprache, Schrift, Region, Kalender, Zahlensystem und weiteren kulturellen Präferenzen. Es dient als strukturierte Alternative zu einfachen Locale-Strings wie "de-DE" oder "zh-Hant-TW-u-ca-buddhist".
Typische Anwendungsfälle sind das Normalisieren und Maximieren von Locale-Tags (maximize() / minimize()), das Auslesen einzelner Subkennungen wie language, script, region oder calendar, sowie das Erstellen geeigneter Locale-Objekte für andere Intl-Konstruktoren wie Intl.DateTimeFormat oder Intl.NumberFormat.
Ein Intl.Locale-Objekt wird mit dem Konstruktor new Intl.Locale(tag, options) erzeugt, wobei tag ein BCP-47-konformer Locale-String ist. Über das optionale options-Objekt können Erweiterungsschlüssel wie calendar, collation oder numberingSystem gesetzt werden, die auch als Unicode-Erweiterungen im Tag selbst angegeben werden können ("de-u-ca-gregory").
Beachte, dass die Verfügbarkeit von Accessor-Methoden wie getCalendars(), getCollations() oder getHourCycles() erst mit späteren Browser-Versionen (ab ca. 2023) vollständig unterstützt wird; ältere Browser kennen nur die statischen Eigenschaften.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $tag Pflicht | string | Intl.Locale | Ein BCP-47-konformer Locale-Identifikator (z. B. "de", "de-AT", "zh-Hant-TW") oder ein vorhandenes Intl.Locale-Objekt. |
|
| $options | object | {} | Optionales Konfigurationsobjekt mit Feldern wie language, script, region, calendar, collation, hourCycle, caseFirst, numeric und numberingSystem. Werte aus options überschreiben eventuell im tag enthaltene Unicode-Erweiterungen. |
Rückgabewert
Intl.Locale-Instanz, die den normalisierten Locale-Identifikator sowie alle zugehörigen Metadaten kapselt.Beispiele
Einfache Locale erstellen und Eigenschaften auslesen
const locale = new Intl.Locale('de-AT-u-ca-gregory-nu-latn');
console.log(locale.language); // 'de'
console.log(locale.region); // 'AT'
console.log(locale.calendar); // 'gregory'
console.log(locale.numberingSystem);// 'latn'
console.log(locale.toString()); // 'de-AT-u-ca-gregory-nu-latn'Locale maximieren und minimieren
const minimal = new Intl.Locale('zh');
// Fehlende Subkennungen ergänzen
const maximal = minimal.maximize();
console.log(maximal.toString()); // 'zh-Hans-CN'
// Überflüssige Subkennungen entfernen
const reduced = maximal.minimize();
console.log(reduced.toString()); // 'zh'Locale mit options-Objekt konfigurieren
const locale = new Intl.Locale('en', {
region: 'GB',
calendar: 'gregory',
hourCycle: 'h12',
numberingSystem: 'latn',
});
console.log(locale.toString()); // 'en-GB-u-ca-gregory-hc-h12-nu-latn'
console.log(locale.hourCycle); // 'h12'
// Als Basis für Intl.DateTimeFormat verwenden
const fmt = new Intl.DateTimeFormat(locale, { dateStyle: 'full' });
console.log(fmt.format(new Date('2024-06-01'))); // 'Saturday, 1 June 2024'Verfügbare Kalender und Kollationen abfragen (neuere API)
const locale = new Intl.Locale('ar-EG');
// Verfügbare Kalender für diese Locale (ab Chrome 99+, Firefox 113+)
if (typeof locale.getCalendars === 'function') {
console.log(locale.getCalendars()); // ['gregory', 'coptic', 'ethiopic', ...]
console.log(locale.getCollations()); // ['compat', 'emoji', 'eor']
console.log(locale.getHourCycles()); // ['h12']
} else {
// Fallback für ältere Browser
console.log(locale.calendar); // 'gregory' (erste Präferenz)
}// Wichtig · Fallstricke
Browser-Kompatibilität: Der Konstruktor new Intl.Locale() ist seit Chrome 74, Firefox 75, Safari 14 und Node.js 12 verfügbar. Die neueren Methoden getCalendars(), getCollations(), getHourCycles(), getNumberingSystems(), getTextInfo(), getTimeZones() und getWeekInfo() sind erst ab ca. 2022/2023 in allen modernen Browsern verfügbar – vor deren Einsatz sollte eine Feature-Prüfung stattfinden.
Unveränderlichkeit: Intl.Locale-Objekte sind nach der Erstellung unveränderlich. Anpassungen erfordern stets ein neues Objekt.
Normalisierung: Der übergebene Tag wird beim Erstellen normalisiert – Groß-/Kleinschreibung und Trennzeichen werden kanonisch angepasst (z. B. "DE-de" wird zu "de-DE"). Ungültige Tags werfen einen RangeError.