The HTML srclang attribute
The HTML srclang attribute states the language of a <track> element's text. It takes a BCP 47 language tag such as en, es or pt-BR, it is required when kind is subtitles or missing, and browsers can use it to match tracks to a viewer's language preferences.
Overview
The srclang attribute gives the language of a text track's cues. It belongs on the <track> element and takes a valid BCP 47 language tag, the same format as the lang attribute, so values like en, fr, pt-BR and zh-Hant all work.
The attribute is required in one case. The HTML Standard says srclang must be present when the track's kind is subtitles, and because a missing kind means subtitles, a bare <track src="subs.vtt"> needs it too. On other kinds it is optional but still useful.
The value becomes the track's language in the DOM. When srclang has a non-empty value, textTrack.language returns it, and otherwise the track has no language. Browsers can compare that language, along with kind and label, against a viewer's caption preferences to turn on a matching track automatically.
The entry in the captions menu comes from label. When a track has no label, the HTML Standard says the browser should generate one from properties such as the track's kind and language. The language of the surrounding page comes from lang, so a Spanish subtitle track on an English page still uses srclang="es".
Syntax
<track kind="subtitles" src="subs-fr.vtt" srclang="fr" label="Français">Values
| Value |
|---|
A BCP 47 language tag, e.g. en. |
Example
<video id="v" src="https://codeshack.io/web/example.mp4" controls muted width="240">
<track kind="subtitles" srclang="en" label="English" src="data:text/vtt,WEBVTT%0A%0A00:00.000%20--%3E%2000:31.000%0AEnglish%20subtitles">
<track kind="subtitles" srclang="fr" label="Français" src="data:text/vtt,WEBVTT%0A%0A00:00.000%20--%3E%2000:31.000%0ASous-titres%20en%20fran%C3%A7ais">
</video>
<p id="out"></p>
<p><small>Each track inlines its WebVTT text as a data: URL. A real page points src at a .vtt file.</small></p>
<script>
const wanted = navigator.language.split('-')[0];
let picked = 'none';
for (const track of document.getElementById('v').textTracks) {
track.mode = track.language === wanted ? 'showing' : 'disabled';
if (track.mode === 'showing') picked = track.label;
}
document.getElementById('out').textContent = 'Browser language: ' + navigator.language + ', showing: ' + picked;
</script>Best practices
- Use a tag no more specific than the text needs, such as
es, and add a region only when it distinguishes the text, as withes-419for Latin American and Caribbean Spanish. RFC 5646 advises using as precise a tag as possible, but no more specific than is justified. - Set
srclangon every subtitles track and on any track without akind, because the HTML Standard requires it there. - Match
srclangto the language of the cue text, not to the page or the spoken audio. - Pair
srclangwith a readable label, since the label is the title browsers show when they list tracks.