TextTrack.language — Eigenschaft · JavaScript-Referenz

Signatur

TextTrack.language

Beschreibung

Die Eigenschaft language der Schnittstelle TextTrack liefert die Sprache eines Text-Tracks (Untertitel, Bildunterschriften, Beschreibungen, Kapitel oder Metadaten) als String. Der Wert ist ein gültiges BCP-47-Sprach-Tag wie "de", "en" oder "pt-BR". Ist keine Sprache bekannt, wird ein leerer String "" zurückgegeben.

Bei Tracks, die über ein <track>-Element eingebunden sind, stammt der Wert aus dessen Attribut srclang. Bei Tracks, die per HTMLMediaElement.addTextTrack(kind, label, language) erzeugt wurden, entspricht er dem dritten Argument. Bei In-Band-Tracks (im Mediencontainer eingebettet) liest der Browser die Sprache aus den Metadaten der Mediendatei.

Typische Einsatzfälle sind eigene Untertitel-Menüs, das automatische Aktivieren der passenden Untertitelsprache anhand von navigator.language oder das Filtern von Tracks nach Sprache. Da die Eigenschaft schreibgeschützt ist, muss man zum Ändern der Sprache das srclang-Attribut des <track>-Elements anpassen bzw. einen neuen Track anlegen.

Rückgabewert

Typ

string

Beschreibung

BCP-47-Sprach-Tag des Tracks (z. B. "de") oder ein leerer String, wenn keine Sprache angegeben ist.

Beispiele

Sprachen aller Tracks eines Videos auflisten

// HTML: <video id="film" src="film.mp4">
//   <track kind="subtitles" src="de.vtt" srclang="de" label="Deutsch">
//   <track kind="subtitles" src="en.vtt" srclang="en" label="English">
// </video>
const video = document.getElementById('film');

for (const track of video.textTracks) {
  console.log(`${track.label}: ${track.language || '(unbekannt)'}`);
}

Deutsch: de English: en

Untertitel passend zur Browsersprache aktivieren

const video = document.querySelector('video');
const userLang = navigator.language.toLowerCase(); // z. B. "de-de"
const primary = userLang.split('-')[0];              // "de"

const tracks = [...video.textTracks].filter(
  (t) => t.kind === 'subtitles' || t.kind === 'captions'
);

// Erst exakte Übereinstimmung, dann Hauptsprache
const match =
  tracks.find((t) => t.language.toLowerCase() === userLang) ??
  tracks.find((t) => t.language.toLowerCase().split('-')[0] === primary);

tracks.forEach((t) => {
  t.mode = t === match ? 'showing' : 'disabled';
});

console.log(match ? `Aktiv: ${match.language}` : 'Keine passende Sprache');

Aktiv: de

Sprache bei per Skript erzeugtem Track

const video = document.querySelector('video');
const track = video.addTextTrack('captions', 'Français', 'fr');

track.addCue(new VTTCue(0, 4, 'Bonjour à tous !'));
track.mode = 'showing';

console.log(track.language);

// Schreibversuch wird ignoriert (im Strict Mode: TypeError)
try {
  track.language = 'it';
} catch (e) {
  console.log(e.name);
}
console.log(track.language);

fr TypeError fr

// Wichtig · Fallstricke

Schreibgeschützt: Zuweisungen werden stillschweigend ignoriert bzw. werfen im Strict Mode (z. B. in ES-Modulen) einen TypeError. Zum Ändern das srclang-Attribut des <track>-Elements setzen.
Keine Normalisierung: Der Wert wird so zurückgegeben, wie er angegeben wurde. Groß-/Kleinschreibung ("en-US" vs. "en-us") sollte man beim Vergleich selbst angleichen, etwa mit toLowerCase() oder Intl.getCanonicalLocales().
Leerer String: Fehlt srclang, ist der Wert "" – nicht null oder undefined. Hinweis: Bei kind="subtitles" ist srclang laut HTML-Spezifikation Pflicht.
In-Band-Tracks: Ob und wie die Sprache aus eingebetteten Tracks (z. B. MP4, HLS) gelesen wird, hängt vom Browser und Container ab.
Kompatibilität: Wird von allen modernen Browsern (Chrome, Firefox, Safari, Edge) unterstützt; im Internet Explorer ab Version 10.

Siehe auch

TextTrack.label TextTrack.cues TextTrack.kind TextTrack.mode TextTrack.id