Intl.Locale.prototype.getTextInfo() — Methode · JavaScript-Referenz

Signatur

Intl.Locale.prototype.getTextInfo()

Beschreibung

Die Methode getTextInfo() einer Intl.Locale-Instanz liefert Informationen zur Textdarstellung der jeweiligen Locale. Derzeit enthält das Ergebnis genau eine Eigenschaft: direction. Sie gibt an, ob Text in dieser Sprache bzw. Schrift von links nach rechts ("ltr", z. B. Deutsch, Englisch, Japanisch) oder von rechts nach links ("rtl", z. B. Arabisch, Hebräisch, Persisch, Urdu) läuft.

Gebraucht wird das vor allem bei internationalisierten Oberflächen: Wenn die Sprache zur Laufzeit wechselt, lässt sich damit das dir-Attribut von <html> oder von einzelnen Elementen richtig setzen. Eine fest eingebaute Liste von RTL-Sprachen braucht man dann nicht mehr. Die Daten stammen aus CLDR, der Datenbank, die auch die übrigen Intl-APIs nutzen.

Ausschlaggebend für die Richtung ist die Schrift, nicht nur die Sprache. Ist im Tag kein Schrift-Subtag angegeben (z. B. "ar"), wird die wahrscheinlichste Schrift der Sprache angenommen.

Die Methode ersetzt den früheren Getter Intl.Locale.prototype.textInfo, den einige Browser schon vorab eingebaut hatten. Sie gibt bei jedem Aufruf ein neues Objekt zurück.

Rückgabewert

Typ

{ direction: "ltr" | "rtl" | undefined }

Beschreibung

Ein neues Objekt mit der Eigenschaft direction: "ltr" oder "rtl". Laut Spezifikationsentwurf kann sie undefined sein, wenn keine Daten zur Locale vorliegen.

Beispiele

Schreibrichtung verschiedener Locales abfragen

const tags = ['de-DE', 'en-US', 'ar-EG', 'he-IL', 'fa-IR', 'ja-JP'];

for (const tag of tags) {
  const { direction } = new Intl.Locale(tag).getTextInfo();
  console.log(`${tag}: ${direction}`);
}

de-DE: ltr en-US: ltr ar-EG: rtl he-IL: rtl fa-IR: rtl ja-JP: ltr

dir-Attribut beim Sprachwechsel setzen

const setDocumentLanguage = (tag) => {
  const locale = new Intl.Locale(tag);
  const { direction = 'ltr' } = locale.getTextInfo();

  document.documentElement.lang = locale.baseName;
  document.documentElement.dir = direction;
};

setDocumentLanguage('ar-SA');
console.log(document.documentElement.dir);

rtl

Funktion mit Fallback für ältere Engines

// Erst die neue Methode, dann der alte Getter, sonst 'ltr'
const getDirection = (tag) => {
  const locale = new Intl.Locale(tag);
  const info =
    typeof locale.getTextInfo === 'function'
      ? locale.getTextInfo()
      : locale.textInfo;
  return info?.direction ?? 'ltr';
};

console.log(getDirection('ur-PK'));
console.log(getDirection('fr-FR'));

rtl ltr

Richtung der Browsersprache ermitteln

const userLocale = new Intl.Locale(navigator.language);
const isRtl = userLocale.getTextInfo().direction === 'rtl';

document.body.classList.toggle('layout-rtl', isRtl);
console.log(`Sprache: ${userLocale.baseName}, RTL: ${isRtl}`);

Sprache: de-DE, RTL: false

// Wichtig · Fallstricke

Browserunterstützung: Die Methode gehört zum Vorschlag „Intl Locale Info“ (Stage 3). Chrome/Edge (ab 130) und Safari (ab 17) unterstützen sie. Firefox unterstützt sie nicht (Stand 2024). Ältere Chromium- (ab 99) und Safari-Versionen (ab 15.4) kennen nur den Getter textInfo. Deshalb vorher die Unterstützung prüfen und einen Fallback vorsehen (siehe Beispiel 3).
Kein fester Wert: Jeder Aufruf erzeugt ein neues Objekt. a.getTextInfo() === b.getTextInfo() ist also immer false. Vergleichen Sie stattdessen direction.
Nur die Grundrichtung: Das Ergebnis gibt die Hauptrichtung der Schrift an. Gemischter bidirektionaler Text (z. B. lateinische Zahlen in arabischem Text) wird trotzdem vom Unicode-Bidi-Algorithmus behandelt. Für Benutzereingaben ist oft dir="auto" die bessere Wahl.
Ungültige Tags: new Intl.Locale() wirft bei syntaktisch ungültigen Sprach-Tags einen RangeError, bevor getTextInfo() überhaupt aufgerufen wird.
Vertikale Schreibrichtungen (z. B. traditionelles Mongolisch) liefert die Methode nicht. Dafür bleibt die CSS-Eigenschaft writing-mode zuständig.

Siehe auch

Intl.Locale Intl.Locale.prototype.getWeekInfo() Intl.Locale.prototype.getHourCycles() Intl.Locale.prototype.getCalendars() Intl.Locale.prototype.maximize() Intl.Locale.prototype.script