Intl.Locale.prototype.language — Eigenschaft · JavaScript-Referenz

Signatur

get Intl.Locale.prototype.language

Beschreibung

Die Eigenschaft language liefert den Sprach-Subtag eines Gebietsschemas. Er steht in einem BCP-47-Sprach-Tag immer an erster Stelle, also z. B. "de" in "de-Latn-AT-u-ca-gregory". Üblich sind Codes mit 2 oder 3 Buchstaben nach ISO 639 (etwa "en", "fil"). Nach BCP 47 sind auch 5 bis 8 Buchstaben erlaubt.

Die Eigenschaft ist nur lesbar. Es gibt nur einen Getter und keinen Setter. Du kannst language aber im Options-Objekt des Konstruktors angeben. Dann ersetzt dieser Wert die Sprache aus dem Tag. So baust du aus einer bestehenden Locale eine Variante mit anderer Sprache.

In der Praxis nutzt du language, um Nutzer-Locales wie navigator.language auf die Sprache zu reduzieren. Das hilft zum Beispiel, wenn du Übersetzungsdateien pro Sprache und nicht pro Region lädst, oder wenn du Sprachen vergleichst, ohne Region und Schrift zu beachten. Den String musst du dafür nicht selbst mit split("-") zerlegen.

Der Wert wird kanonisiert, also in Kleinbuchstaben umgewandelt. Veraltete Aliase werden durch die aktuellen Codes ersetzt, z. B. wird "iw" zu "he".

Rückgabewert

Typ

string

Beschreibung

Der kanonisierte Sprach-Subtag in Kleinbuchstaben, z. B. "de", "en" oder "zh". Beim Tag "und" (unbestimmte Sprache) ist das Ergebnis "und".

Beispiele

Sprache aus einem vollständigen Sprach-Tag lesen

const locale = new Intl.Locale('de-Latn-AT-u-ca-gregory');
console.log(locale.language);
console.log(locale.script);
console.log(locale.region);

de Latn AT

Sprache über das Options-Objekt überschreiben

const basis = new Intl.Locale('en-US', { hourCycle: 'h23' });
const spanisch = new Intl.Locale(basis, { language: 'es' });
console.log(spanisch.language);
console.log(spanisch.toString());

es es-US-u-hc-h23

Übersetzungsdatei nach Browsersprache wählen

const unterstuetzt = ['de', 'en', 'fr'];

const waehleSprache = (tag) => {
  const { language } = new Intl.Locale(tag);
  return unterstuetzt.includes(language) ? language : 'en';
};

console.log(waehleSprache('de-CH'));
console.log(waehleSprache('FR-ca'));
console.log(waehleSprache('ja-JP'));

// Im Browser z. B.:
// const res = await fetch(`/i18n/${waehleSprache(navigator.language)}.json`);

de fr en

Kanonisierung von veralteten Codes

console.log(new Intl.Locale('iw-IL').language);
console.log(new Intl.Locale('EN').language);

he en

// Wichtig · Fallstricke

Nur lesbar: Die Zuweisung locale.language = 'fr' hat keine Wirkung. Im Strict Mode wirft sie einen TypeError. Für eine andere Sprache legst du eine neue Instanz an: new Intl.Locale(locale, { language: 'fr' }).
Ungültige Tags: Ist der Tag syntaktisch falsch (z. B. 'd' oder 'de_DE' mit Unterstrich), wirft schon der Konstruktor einen RangeError. Unbekannte, aber formal gültige Codes wie 'xy' werden dagegen ohne Fehler angenommen.
Kein Fallback: language ist immer gesetzt. Für die Region oder Schrift nutzt du region bzw. script. Diese sind undefined, wenn sie fehlen. Mit maximize() werden fehlende Teile ergänzt.
Kompatibilität: Intl.Locale ist ab ES2020 verfügbar: Chrome 74+, Firefox 75+, Safari 14+, Node.js 12+. Wie genau Aliase kanonisiert werden, hängt von der ICU-/CLDR-Version der Umgebung ab.

Siehe auch

Intl.Locale Intl.Locale.prototype.region Intl.Locale.prototype.script Intl.Locale.prototype.baseName Intl.Locale.prototype.maximize() Intl.Locale.prototype.minimize() Navigator.language