Intl.Locale API

Einführung

Beim Erstellen von Anwendungen für mehrere Sprachen und Regionen begegnen Ihnen Locale-Identifikatoren wie en-US, fr-FR oder zh-Hans-CN. Diese Strings erscheinen in Browser-APIs, HTTP-Headern und Benutzerpräferenzen. Sie kodieren Informationen über Sprache, Region, Schriftsystem und Formatierungspräferenzen.

Die Intl.Locale API transformiert diese undurchsichtigen Strings in strukturierte Objekte, die Sie inspizieren und manipulieren können. Anstatt Strings manuell zu parsen oder zu raten, was zh-Hans-CN bedeutet, erstellen Sie ein Locale-Objekt und lesen dessen Properties direkt aus.

Dieser Leitfaden erklärt, wie Locale-Identifikatoren funktionieren, wie Sie die Intl.Locale API verwenden, um mit ihnen zu arbeiten, und wann strukturierte Locale-Objekte bei der Lösung realer Probleme helfen.

Locale-Identifikatoren verstehen

Ein Locale-Identifikator ist ein String, der kulturelle Präferenzen für die Formatierung von Datumsangaben, Zahlen, Währungen und Text spezifiziert. Der Identifikator enthält mehrere durch Bindestriche getrennte Komponenten.

Die gängigste Struktur folgt dem BCP 47-Standard:

language-script-region-variant-extensions

Jede Komponente ist optional, außer dem Sprachcode.

Sprachcodes

Sprachcodes verwenden zwei oder drei Buchstaben aus ISO 639. Gängige Beispiele:

• en für Englisch
• es für Spanisch
• fr für Französisch
• de für Deutsch
• ja für Japanisch
• zh für Chinesisch
• ar für Arabisch

Der Sprachcode ist immer kleingeschrieben und erscheint zuerst im Identifikator.

Regionscodes

Regionscodes spezifizieren geografische Gebiete unter Verwendung von zwei Großbuchstaben aus ISO 3166-1. Sie geben an, welche Variante einer Sprache verwendet werden soll:

• en-US für amerikanisches Englisch
• en-GB für britisches Englisch
• es-ES für europäisches Spanisch
• es-MX für mexikanisches Spanisch
• fr-FR für Französisch, wie es in Frankreich gesprochen wird
• fr-CA für kanadisches Französisch

Regionscodes ändern Formatierungskonventionen. Amerikanisches Englisch verwendet MM/DD/YYYY-Datumsangaben, während britisches Englisch DD/MM/YYYY verwendet.

Schriftcodes

Schriftcodes spezifizieren das Schriftsystem mit vier Buchstaben, wobei der erste Buchstabe großgeschrieben wird. Sie sind wichtig für Sprachen, die in mehreren Schriftsystemen geschrieben werden:

• zh-Hans für vereinfachte chinesische Schriftzeichen
• zh-Hant für traditionelle chinesische Schriftzeichen
• sr-Cyrl für Serbisch in kyrillischer Schrift
• sr-Latn für Serbisch in lateinischer Schrift

Die meisten Locales lassen den Schriftcode weg, da die Sprache eine Standardschrift impliziert. Englisch verwendet standardmäßig die lateinische Schrift, daher schreibt man en anstelle von en-Latn.

Erweiterungs-Tags

Erweiterungs-Tags fügen Formatierungspräferenzen zu Locale-Identifikatoren hinzu. Sie beginnen mit -u-, gefolgt von Schlüssel-Wert-Paaren:

en-US-u-ca-gregory-nu-latn-hc-h12

Häufige Erweiterungsschlüssel:

• ca für Kalendersystem (gregory, buddhist, islamic)
• nu für Zahlensystem (latn, arab, hanidec)
• hc für Stundenzyklus (h12, h23, h11, h24)

Erweiterungen passen an, wie Formatierer Daten anzeigen, ohne die Sprache oder Region zu ändern.

Locale-Objekte erstellen

Der Intl.Locale-Konstruktor akzeptiert einen Locale-Identifikator-String und gibt ein strukturiertes Objekt zurück:

const locale = new Intl.Locale("en-US");

console.log(locale.language); // "en"
console.log(locale.region); // "US"

Sie können auch ein Optionsobjekt übergeben, um Eigenschaften zu überschreiben oder hinzuzufügen:

const locale = new Intl.Locale("en", {
  region: "GB",
  hourCycle: "h23"
});

console.log(locale.baseName); // "en-GB"
console.log(locale.hourCycle); // "h23"

Der Konstruktor wirft einen RangeError, wenn der Bezeichner ungültig ist:

try {
  const invalid = new Intl.Locale("invalid-locale-code");
} catch (error) {
  console.error(error.message); // "invalid language subtag: invalid"
}

Diese Validierung stellt sicher, dass Sie fehlerhafte Locale-Bezeichner abfangen, bevor Sie sie an Formatter übergeben.

Locale-Eigenschaften auslesen

Locale-Objekte stellen Eigenschaften bereit, die den Komponenten der Bezeichnerzeichenfolge entsprechen. Alle Eigenschaften sind schreibgeschützt.

Kerneigenschaften

Die Eigenschaft language gibt den Sprachcode zurück:

const locale = new Intl.Locale("fr-CA");
console.log(locale.language); // "fr"

Die Eigenschaft region gibt den Regionscode zurück:

const locale = new Intl.Locale("fr-CA");
console.log(locale.region); // "CA"

Die Eigenschaft script gibt den Schriftcode zurück, falls vorhanden:

const locale = new Intl.Locale("zh-Hans-CN");
console.log(locale.script); // "Hans"

Die Eigenschaft baseName gibt den vollständigen Kernbezeichner ohne Erweiterungen zurück:

const locale = new Intl.Locale("en-US-u-ca-gregory-nu-latn");
console.log(locale.baseName); // "en-US"

Verwenden Sie baseName, wenn Sie die Sprache und Region benötigen, aber Formatierungseinstellungen ignorieren möchten.

Erweiterungseigenschaften

Erweiterungseigenschaften geben Werte aus dem -u--Erweiterungs-Tag oder undefined zurück, falls nicht angegeben.

Die Eigenschaft calendar gibt das Kalendersystem zurück:

const locale = new Intl.Locale("ar-SA-u-ca-islamic");
console.log(locale.calendar); // "islamic"

Die Eigenschaft numberingSystem gibt das Zahlensystem zurück:

const locale = new Intl.Locale("ar-EG-u-nu-arab");
console.log(locale.numberingSystem); // "arab"

Die Eigenschaft hourCycle gibt die Stundenzyklus-Präferenz zurück:

const locale = new Intl.Locale("en-US-u-hc-h23");
console.log(locale.hourCycle); // "h23"

Die Eigenschaft caseFirst gibt die Präferenz für die Groß-/Kleinschreibung bei der Sortierung zurück:

const locale = new Intl.Locale("en-US-u-kf-upper");
console.log(locale.caseFirst); // "upper"

Die Eigenschaft numeric gibt an, ob die numerische Sortierung aktiviert ist:

const locale = new Intl.Locale("en-US-u-kn-true");
console.log(locale.numeric); // true

Diese Eigenschaften ermöglichen es Ihnen, Formatierungspräferenzen zu überprüfen, ohne die Erweiterungszeichenfolge manuell zu parsen.

Abfragen von Locale-Informationen

Die API Intl.Locale bietet Methoden, die Arrays verfügbarer Optionen für eine Locale zurückgeben. Diese Methoden helfen beim Erstellen von Benutzeroberflächen und beim Validieren von Formatierungsoptionen.

Verfügbare Kalender

Die Methode getCalendars() gibt Kalendersysteme zurück, die üblicherweise für die Locale verwendet werden:

const locale = new Intl.Locale("th-TH");
const calendars = locale.getCalendars();
console.log(calendars); // ["buddhist", "gregory"]

Das erste Element ist der Standardkalender. Thailändische Locales verwenden standardmäßig den buddhistischen Kalender, nutzen aber auch den gregorianischen Kalender.

Verfügbare Sortierungen

Die Methode getCollations() gibt Sortierungstypen für das Sortieren von Zeichenfolgen zurück:

const locale = new Intl.Locale("de-DE");
const collations = locale.getCollations();
console.log(collations); // ["phonebk", "emoji", "eor"]

Deutsch verfügt über eine Telefonbuch-Sortierung, die Zeichenfolgen anders sortiert als die standardmäßige Unicode-Sortierung.

Verfügbare Stundenzyklen

Die Methode getHourCycles() gibt Stundenzyklus-Formate zurück:

const locale = new Intl.Locale("en-US");
const hourCycles = locale.getHourCycles();
console.log(hourCycles); // ["h12"]

Amerikanisches Englisch verwendet standardmäßig das 12-Stunden-Format. Viele andere Locales geben ["h23"] für das 24-Stunden-Format zurück.

Verfügbare Zahlensysteme

Die Methode getNumberingSystems() gibt Zahlensysteme zurück, die üblicherweise für die Locale verwendet werden:

const locale = new Intl.Locale("ar-EG");
const numberingSystems = locale.getNumberingSystems();
console.log(numberingSystems); // ["arab", "latn"]

Arabische Locales unterstützen häufig sowohl arabisch-indische als auch lateinische Ziffern.

Textrichtung

Die Methode getTextInfo() gibt Informationen zur Textausrichtung zurück:

const locale = new Intl.Locale("ar-SA");
const textInfo = locale.getTextInfo();
console.log(textInfo.direction); // "rtl"

Rechts-nach-links-Sprachen wie Arabisch und Hebräisch geben "rtl" zurück. Links-nach-rechts-Sprachen geben "ltr" zurück.

Wochenkonventionen

Die Methode getWeekInfo() gibt die Wochenstruktur für das Gebietsschema zurück:

const locale = new Intl.Locale("en-US");
const weekInfo = locale.getWeekInfo();
console.log(weekInfo.firstDay); // 7 (Sunday)
console.log(weekInfo.weekend); // [6, 7] (Saturday, Sunday)
console.log(weekInfo.minimalDays); // 1

Wochenkonventionen variieren je nach Region. Amerikanische Wochen beginnen am Sonntag, während die meisten europäischen Wochen am Montag beginnen.

Zeitzonen

Die Methode getTimeZones() gibt Zeitzonen für die Region des Gebietsschemas zurück:

const locale = new Intl.Locale("en-US");
const timeZones = locale.getTimeZones();
console.log(timeZones); // ["America/New_York", "America/Chicago", ...]

Diese Methode gibt IANA-Zeitzonenbezeichner für den Regionscode zurück.

Maximierung von Gebietsschemabezeichnern

Die Methode maximize() fügt wahrscheinliche Subtags hinzu, um einen vollständigen Bezeichner zu erstellen. Sie leitet fehlende Schrift- und Regionscodes basierend auf Sprachdaten ab.

Wenn Sie nur einen Sprachcode angeben, fügt maximize() die gebräuchlichste Schrift und Region hinzu:

const locale = new Intl.Locale("en");
const maximized = locale.maximize();
console.log(maximized.baseName); // "en-Latn-US"

Englisch verwendet standardmäßig die lateinische Schrift und die Region Vereinigte Staaten, da dies die häufigsten Zuordnungen sind.

Die Maximierung von Chinesisch hängt von der Schrift ab:

const simplified = new Intl.Locale("zh-Hans");
const maximized = simplified.maximize();
console.log(maximized.baseName); // "zh-Hans-CN"

const traditional = new Intl.Locale("zh-Hant");
const maximizedTrad = traditional.maximize();
console.log(maximizedTrad.baseName); // "zh-Hant-TW"

Vereinfachtes Chinesisch wird mit China assoziiert, während traditionelles Chinesisch mit Taiwan assoziiert wird.

Verwenden Sie maximize() beim Normalisieren von Benutzereingaben oder beim Vergleichen von Gebietsschemabezeichnern. Es macht implizite Informationen explizit.

Minimierung von Gebietsschemabezeichnern

Die Methode minimize() entfernt redundante Subtags, um den kürzesten äquivalenten Bezeichner zu erstellen. Sie entfernt Schrift- und Regionscodes, wenn diese mit den wahrscheinlichen Standardwerten übereinstimmen.

Wenn ein Gebietsschema die Standardschrift und -region verwendet, entfernt minimize() diese:

const locale = new Intl.Locale("en-Latn-US");
const minimized = locale.minimize();
console.log(minimized.baseName); // "en"

Die lateinische Schrift und die Region Vereinigte Staaten sind Standardwerte für Englisch, sodass sie ohne Informationsverlust entfernt werden können.

Für Locales mit nicht standardmäßigen Regionen behält minimize() die Region bei:

const locale = new Intl.Locale("en-Latn-GB");
const minimized = locale.minimize();
console.log(minimized.baseName); // "en-GB"

Britisches Englisch benötigt den Regionscode, da es sich vom Standard unterscheidet.

Verwenden Sie minimize(), um kompakte Identifikatoren für die Speicherung oder URLs zu erstellen und dabei die Bedeutung zu erhalten.

Konvertierung in Strings

Die Methode toString() gibt den vollständigen Locale-Identifikator einschließlich Erweiterungen zurück:

const locale = new Intl.Locale("en-US", {
  calendar: "gregory",
  numberingSystem: "latn",
  hourCycle: "h12"
});

console.log(locale.toString()); // "en-US-u-ca-gregory-hc-h12-nu-latn"

Die String-Darstellung ist gültig für die Übergabe an andere Intl-APIs oder die Speicherung als Konfigurationsdaten.

Sie können Locale-Objekte auch implizit in Strings konvertieren:

const locale = new Intl.Locale("fr-FR");
const formatter = new Intl.DateTimeFormat(locale);

Der DateTimeFormat-Konstruktor akzeptiert Locale-Objekte direkt und ruft intern toString() auf.

Praktische Anwendungsfälle

Die Intl.Locale-API löst mehrere häufige Probleme beim Erstellen internationalisierter Anwendungen.

Erstellen von Locale-Selektoren

Locale-Selektoren ermöglichen es Benutzern, ihre Sprache und Region auszuwählen. Die Intl.Locale-API hilft beim Parsen und Validieren von Benutzerauswahlen:

function createLocaleSelector(locales) {
  const options = locales.map(identifier => {
    const locale = new Intl.Locale(identifier);
    const displayName = new Intl.DisplayNames([identifier], { type: "language" });

    return {
      value: locale.toString(),
      label: displayName.of(locale.language),
      region: locale.region
    };
  });

  return options;
}

const options = createLocaleSelector(["en-US", "en-GB", "fr-FR", "es-MX"]);
console.log(options);
// [
//   { value: "en-US", label: "English", region: "US" },
//   { value: "en-GB", label: "English", region: "GB" },
//   { value: "fr-FR", label: "French", region: "FR" },
//   { value: "es-MX", label: "Spanish", region: "MX" }
// ]

Validierung von Locale-Eingaben

Wenn Sie Locale-Identifikatoren aus Benutzereingaben oder Konfigurationsdateien akzeptieren, validieren Sie diese vor der Verwendung:

function validateLocale(identifier) {
  try {
    const locale = new Intl.Locale(identifier);
    return {
      valid: true,
      locale: locale.toString(),
      language: locale.language,
      region: locale.region
    };
  } catch (error) {
    return {
      valid: false,
      error: error.message
    };
  }
}

console.log(validateLocale("en-US")); // { valid: true, locale: "en-US", ... }
console.log(validateLocale("invalid")); // { valid: false, error: "..." }

Extrahieren der Sprache für Fallbacks

Beim Implementieren von Sprach-Fallback-Ketten extrahieren Sie den Sprachcode ohne die Region:

function getLanguageFallback(identifier) {
  const locale = new Intl.Locale(identifier);
  const fallbacks = [locale.toString()];

  if (locale.region) {
    const languageOnly = new Intl.Locale(locale.language);
    fallbacks.push(languageOnly.toString());
  }

  fallbacks.push("en");

  return fallbacks;
}

console.log(getLanguageFallback("fr-CA"));
// ["fr-CA", "fr", "en"]

Dies erstellt eine Fallback-Kette, die zuerst das spezifische Locale versucht, dann die Sprache ohne Region und schließlich die Standardsprache.

Konfigurieren von Formatierern

Verwenden Sie Locale-Objekte, um Intl-Formatierer mit spezifischen Präferenzen zu konfigurieren:

function createFormatter(baseLocale, options = {}) {
  const locale = new Intl.Locale(baseLocale, {
    calendar: options.calendar || "gregory",
    numberingSystem: options.numberingSystem || "latn",
    hourCycle: options.hourCycle || "h23"
  });

  return {
    date: new Intl.DateTimeFormat(locale),
    number: new Intl.NumberFormat(locale),
    locale: locale.toString()
  };
}

const formatter = createFormatter("ar-SA", {
  calendar: "islamic",
  numberingSystem: "arab"
});

console.log(formatter.locale); // "ar-SA-u-ca-islamic-nu-arab"

Erkennung von Benutzerpräferenzen

Browser-APIs stellen Locale-Strings bereit, die Sie parsen können, um Benutzerpräferenzen zu verstehen:

function getUserPreferences() {
  const userLocale = new Intl.Locale(navigator.language);
  const hourCycles = userLocale.getHourCycles();
  const calendars = userLocale.getCalendars();
  const textInfo = userLocale.getTextInfo();

  return {
    language: userLocale.language,
    region: userLocale.region,
    preferredHourCycle: hourCycles[0],
    preferredCalendar: calendars[0],
    textDirection: textInfo.direction
  };
}

const preferences = getUserPreferences();
console.log(preferences);
// { language: "en", region: "US", preferredHourCycle: "h12", ... }

Dies erstellt ein Profil der Benutzerpräferenzen basierend auf deren Browsereinstellungen.

Browser-Unterstützung

Die Intl.Locale-API funktioniert in allen modernen Browsern. Chrome, Firefox, Safari und Edge bieten vollständige Unterstützung für den Konstruktor, die Eigenschaften und die Methoden, die in diesem Leitfaden beschrieben werden.

Die neueren Methoden wie getCalendars(), getCollations(), getHourCycles(), getNumberingSystems(), getTextInfo(), getTimeZones() und getWeekInfo() erfordern aktuelle Browserversionen. Prüfen Sie die Browser-Kompatibilitätstabellen, bevor Sie diese Methoden verwenden, falls Sie ältere Browser unterstützen.

Node.js unterstützt die Intl.Locale-API ab Version 12, mit vollständiger Methodenunterstützung in Version 18 und später.

Zusammenfassung

Die Intl.Locale-API transformiert Locale-Identifier-Strings in strukturierte Objekte, die Sie inspizieren und manipulieren können. Anstatt Strings manuell zu parsen, erstellen Sie Locale-Objekte und lesen deren Eigenschaften.

Kernkonzepte:

• Locale-Identifier enthalten Sprach-, Schrift-, Regions- und Erweiterungskomponenten
• Der Intl.Locale-Konstruktor validiert Identifier und erstellt Objekte
• Eigenschaften wie language, region und calendar bieten strukturierten Zugriff
• Methoden wie getCalendars() und getHourCycles() geben verfügbare Optionen zurück
• Die Methoden maximize() und minimize() normalisieren Identifier
• Locale-Objekte funktionieren direkt mit anderen Intl-APIs

Verwenden Sie die Intl.Locale-API beim Erstellen von Locale-Selektoren, beim Validieren von Benutzereingaben, beim Implementieren von Fallback-Ketten oder beim Konfigurieren von Formatierern. Sie bietet eine standardisierte Methode zur Arbeit mit Locale-Identifiern in JavaScript-Anwendungen.