String.prototype.toLocaleLowerCase() — Methode · JavaScript-Referenz

Signatur

String.prototype.toLocaleLowerCase(locales)

Beschreibung

toLocaleLowerCase() wandelt alle Zeichen eines Strings in Kleinbuchstaben um und wendet dabei sprachspezifische Regeln an. Für die meisten Sprachen ist das Ergebnis identisch mit toLowerCase(). Unterschiede zeigen sich jedoch bei Sprachen mit besonderen Zuordnungen, etwa Türkisch und Aserbaidschanisch ("I" → "ı" ohne Punkt, "İ" → "i") oder Litauisch (Erhalt des Punkts über i mit Akzenten).

Über den optionalen Parameter locales legt man fest, nach welcher Sprache umgewandelt wird. Gibt man ihn nicht an, gilt die Standard-Locale der Laufzeitumgebung (Browser- bzw. Systemsprache). Deshalb kann dasselbe Programm auf verschiedenen Rechnern unterschiedliche Ergebnisse liefern.

Verwenden Sie die Methode, wenn Text für Menschen in einer bekannten Sprache aufbereitet wird, etwa für die Anzeige oder für eine sprachbewusste Suche in Nutzereingaben. Für technische Vergleiche (Schlüssel, HTTP-Header, Dateiendungen, Protokollbezeichner) ist das locale-unabhängige toLowerCase() die richtige Wahl.

Der ursprüngliche String bleibt unverändert, da Strings in JavaScript unveränderlich sind. Die Länge des Ergebnisses kann sich vom Original unterscheiden.

Parameter

Name	Typ	Default	Beschreibung
$locales	string \| string[] \| Intl.Locale \| Intl.Locale[] \| undefined	Standard-Locale der Laufzeitumgebung	BCP-47-Sprachkennung (z. B. `"tr"`, `"de-DE"`) oder ein Array davon. Bei einem Array wird die erste unterstützte Locale verwendet. Ungültige Kennungen lösen einen `RangeError` aus.

Rückgabewert

Typ

string

Beschreibung

Ein neuer String, dessen Zeichen nach den Regeln der gewählten Locale in Kleinbuchstaben umgewandelt wurden.

Beispiele

Grundlegende Verwendung

const titel = 'HALLO WELT';
console.log(titel.toLocaleLowerCase());
console.log(titel.toLocaleLowerCase('de-DE'));
console.log(titel); // Original bleibt unverändert

hallo welt hallo welt HALLO WELT

Türkisches I: Unterschied zu toLowerCase()

const stadt = 'İSTANBUL IĞDIR';

console.log(stadt.toLowerCase());
console.log(stadt.toLocaleLowerCase('tr'));
console.log(stadt.toLocaleLowerCase('en-US'));

i̇stanbul iğdir istanbul ığdır i̇stanbul iğdir

Sprachbewusste Suche in Nutzereingaben

const staedte = ['İzmir', 'Ankara', 'Isparta', 'Iğdır'];

const suche = (liste, begriff, locale) => {
  const b = begriff.toLocaleLowerCase(locale);
  return liste.filter((s) => s.toLocaleLowerCase(locale).startsWith(b));
};

console.log(suche(staedte, 'ı', 'tr'));
console.log(suche(staedte, 'i', 'tr'));

[ 'Isparta', 'Iğdır' ] [ 'İzmir' ]

Mehrere Locales als Fallback-Liste

// Die erste unterstützte Locale wird verwendet
const text = 'ISIK';
console.log(text.toLocaleLowerCase(['tr', 'en-US']));

try {
  text.toLocaleLowerCase('kein_gültiger_tag');
} catch (e) {
  console.log(e.name);
}

ısık RangeError

// Wichtig · Fallstricke

Nicht deterministisch ohne locales: Ohne Argument hängt das Ergebnis von der Systemsprache ab. Auf einem türkischen System wird 'TITLE'.toLocaleLowerCase() zu 'tıtle'. Das ist ein klassischer Fehler bei Vergleichen von Schlüsseln, Tags oder Befehlen. Für technische Zeichenketten deshalb immer toLowerCase() verwenden.
Kein Ersatz für Vergleiche ohne Rücksicht auf Groß-/Kleinschreibung: Für robuste Vergleiche eignet sich localeCompare() mit { sensitivity: 'base' } oder Intl.Collator besser.
Länge kann sich ändern: Zum Beispiel wird 'İ' mit toLowerCase() zu 'i̇' (zwei Codepunkte). Indexbasierte Logik auf Original und Ergebnis kann daher auseinanderlaufen.
Ungültige Locale: Ein fehlerhafter BCP-47-Tag löst einen RangeError aus. Nicht unterstützte, aber gültige Tags führen stillschweigend zur Standard-Locale.
Kompatibilität: Die Methode wird von allen Browsern und Node.js unterstützt. Der Parameter locales setzt Unterstützung für ECMA-402 (Intl) voraus. In Node.js-Builds ohne vollständige ICU-Daten (small-icu, bei älteren Versionen) werden sprachspezifische Regeln unter Umständen ignoriert.
Wird die Methode mit call auf null oder undefined aufgerufen, entsteht ein TypeError. Andere Werte werden vorher in einen String umgewandelt.

Siehe auch

String.prototype.toLowerCase() String.prototype.toLocaleUpperCase() String.prototype.toUpperCase() String.prototype.localeCompare() String.prototype.normalize() Intl.Collator