Intl.Locale API

Einführung

Beim Entwickeln von Anwendungen für mehrere Sprachen und Regionen begegnen Ihnen Gebietsschema-Kennungen wie en-US, fr-FR oder zh-Hans-CN. Diese Zeichenketten erscheinen in Browser-APIs, HTTP-Headern und Benutzereinstellungen. Sie kodieren Informationen über Sprache, Region, Schriftsystem und Formatierungseinstellungen.

Die Intl.Locale-API transformiert diese undurchsichtigen Zeichenketten in strukturierte Objekte, die Sie untersuchen und manipulieren können. Anstatt Zeichenketten manuell zu analysieren oder zu erraten, was zh-Hans-CN bedeutet, erstellen Sie ein Locale-Objekt und lesen dessen Eigenschaften direkt aus.

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

Gebietsschema-Kennungen verstehen

Eine Gebietsschema-Kennung ist eine Zeichenkette, die kulturelle Präferenzen für die Formatierung von Datumsangaben, Zahlen, Währungen und Text angibt. Die Kennung enthält mehrere Komponenten, die durch Bindestriche getrennt sind.

Die häufigste Struktur folgt dem BCP 47-Standard:

language-script-region-variant-extensions

Jede Komponente ist optional, mit Ausnahme des Sprachcodes.

Sprachcodes

Sprachcodes verwenden zwei oder drei Buchstaben aus ISO 639. Häufige 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 an erster Stelle in der Kennung.

Regionscodes

Regionscodes spezifizieren geografische Gebiete mit 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 das Datumsformat MM/DD/YYYY, während britisches Englisch DD/MM/YYYY verwendet.

Skript-Codes

Skript-Codes 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 Zeichen
• zh-Hant für traditionelle chinesische Zeichen
• sr-Cyrl für Serbisch in kyrillischer Schrift
• sr-Latn für Serbisch in lateinischer Schrift

Die meisten Locales lassen den Skript-Code weg, weil die Sprache ein Standard-Schriftsystem impliziert. Englisch verwendet standardmäßig die lateinische Schrift, daher schreibt man en anstatt 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

Gängige 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.

Erstellen von Locale-Objekten

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 Options-Objekt ü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 Identifikator 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-Identifikatoren erkennen, bevor Sie sie an Formatierer übergeben.

Lesen von Locale-Eigenschaften

Locale-Objekte stellen Eigenschaften bereit, die den Komponenten des Identifikator-Strings 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 Skriptcode 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 Formatierungspräferenzen ignorieren möchten.

Erweiterungseigenschaften

Erweiterungseigenschaften geben Werte aus dem -u--Erweiterungstag zurück oder undefined, wenn 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 Stundenzykluseinstellung zurück:

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

Die Eigenschaft caseFirst gibt die Groß-/Kleinschreibungspräferenz für die 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, Formatierungspräferenzen zu überprüfen, ohne die Erweiterungszeichenfolge manuell zu analysieren.

Abfragen von Locale-Informationen

Die Intl.Locale-API bietet Methoden, die Arrays mit verfügbaren 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. Thai-Locales verwenden standardmäßig den buddhistischen Kalender, aber auch den gregorianischen Kalender.

Verfügbare Sortierungen

Die Methode getCollations() gibt Sortierungstypen für die Sortierung von Zeichenketten 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 Zeichenketten anders sortiert als die Standard-Unicode-Sortierung.

Verfügbare Stundenzyklen

Die Methode getHourCycles() gibt Stundenzyklusformate 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 Gebietsschemas geben ["h23"] für das 24-Stunden-Format zurück.

Verfügbare Zahlensysteme

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

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

Arabische Gebietsschemas unterstützen oft sowohl arabisch-indische als auch lateinische Ziffern.

Textrichtung

Die Methode getTextInfo() gibt Informationen zur Textanordnung 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 (Sonntag)
console.log(weekInfo.weekend); // [6, 7] (Samstag, Sonntag)
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 Gebietsschema-Kennungen

Die Methode maximize() fügt wahrscheinliche Subtags hinzu, um eine vollständige Kennung zu erstellen. Sie leitet fehlende Skript- und Regionscodes basierend auf Sprachdaten ab.

Wenn Sie nur einen Sprachcode angeben, fügt maximize() das häufigste Skript und die häufigste Region hinzu:

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

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

Die Maximierung des Chinesischen hängt vom Skript 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(), wenn Sie Benutzereingaben normalisieren oder Locale-Kennungen vergleichen. Es macht implizite Informationen explizit.

Minimieren von Locale-Kennungen

Die Methode minimize() entfernt redundante Subtags, um die kürzeste äquivalente Kennung zu erstellen. Sie entfernt Skript- und Regionscodes, wenn diese mit den wahrscheinlichen Standardwerten übereinstimmen.

Wenn ein Locale das Standardskript und die Standardregion verwendet, entfernt minimize() diese:

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

Das lateinische Skript und die Region Vereinigte Staaten sind Standardwerte für Englisch, daher können sie ohne Informationsverlust entfernt werden.

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 Kennungen für die Speicherung oder URLs zu erstellen, während die Bedeutung erhalten bleibt.

Konvertierung in Strings

Die Methode toString() gibt die vollständige Locale-Kennung 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 für 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 Konstruktor DateTimeFormat 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.

Erstellung von Locale-Auswahlmenüs

Locale-Auswahlmenüs ermöglichen Benutzern die Auswahl ihrer Sprache und Region. Die Intl.Locale-API hilft bei der Analyse und Validierung 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

Bei der Annahme von Locale-Kennungen aus Benutzereingaben oder Konfigurationsdateien sollten diese vor der Verwendung validiert werden:

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

Bei der Implementierung von Sprach-Fallback-Ketten kann der Sprachcode ohne die Region extrahiert werden:

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 die spezifische Locale versucht, dann die Sprache ohne Region und schließlich die Standardsprache.

Formatierungen konfigurieren

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"

Benutzerpräferenzen erkennen

Browser-APIs stellen Locale-Strings bereit, die Sie analysieren 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 ihren Browser-Einstellungen.

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 Methoden, die in diesem Leitfaden beschrieben werden.

Die neueren Methoden wie getCalendars(), getCollations(), getHourCycles(), getNumberingSystems(), getTextInfo(), getTimeZones() und getWeekInfo() erfordern aktuelle Browser-Versionen. Überprüfen Sie die Browser-Kompatibilitätstabellen, bevor Sie diese Methoden verwenden, wenn 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 höher.

Zusammenfassung

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

Kernkonzepte:

• Locale-Identifier enthalten Komponenten für Sprache, Schrift, Region und Erweiterungen
• 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 arbeiten direkt mit anderen Intl-APIs zusammen

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