WSS
Web Specification Studio Home
On this page
InternationalisationRequiredUpdated

lang attribute on inline content

Mark passages, phrases, and inline elements that differ from the document language with a lang attribute. WCAG 3.1.2 requires it so assistive tech can switch pronunciation.

What it is

lang is a global HTML attribute that names the natural language of the element’s content. The root document language belongs on <html lang="…"> (covered by the html lang attribute spec page). This page is about the other lang declarations - the ones you add to spans, paragraphs, quotes, and any inline content whose language differs from the page default.

<p>The German verb <span lang="de">verschlimmbessern</span> means to make
something worse by trying to improve it.</p>

Why it matters

WCAG 2.4.2 Level A requires a page-level language. WCAG 3.1.2 Level AA requires per-part language declarations for any passage or phrase whose language differs from the surrounding text. The benefits are concrete:

  • Screen readers switch voice and pronunciation rules. VoiceOver reads a French sentence with a French voice when it sees lang="fr"; without it, it mangles the words with the document-language voice.
  • Browsers apply the correct spellcheck dictionary, font fallback, hyphenation rules, and quotation marks.
  • Search engines and translation tools know which spans to leave alone and which to translate.
  • CSS can target language with the :lang() pseudo-class - useful for typography and quotation marks.

How to implement

Use BCP 47 tags, the same tagging system used for hreflang. Language subtag first, optional script and region after.

<html lang="en-GB">
  <body>
    <blockquote lang="fr">
      Je pense, donc je suis.
    </blockquote>
    <p>The motto <i lang="la">per aspera ad astra</i> is Latin.</p>
    <p>The Japanese term <span lang="ja">改善</span>
       (<span lang="ja-Latn">kaizen</span>) means continuous improvement.</p>
  </body>
</html>

Rules of thumb:

  • Mark the smallest correct element. A <span> around a foreign phrase is fine.
  • Mark scripts when relevant. zh-Hans vs zh-Hant matters for font selection. ja-Latn distinguishes romanised Japanese from kanji.
  • Do not mark proper names that are widely used in the page language (“Paris” in an English text does not need lang="fr").
  • Quotes and citations are good candidates - <blockquote lang="…"> and <q lang="…"> change quotation-mark glyphs via the browser.

Common mistakes

  • Tagging every loanword. “Café” and “ad hoc” in English text are English now.
  • Using invalid codes like lang="english" or lang="UK". Use en or en-GB.
  • Setting lang="" (empty) on an element to “unset” it - that is only valid on <html> when the language is genuinely unknown.
  • Forgetting the script subtag for CJK content, which causes wrong font rendering.

Screen Reader Voice Switching & CJK Glyph Substitution

Marking inline language tags across multi-lingual content blocks requires understanding screen reader synthesizer engines and font fallback rules:

  • Screen Reader Voice Synthesizer Switching: When a screen reader (VoiceOver, NVDA, JAWS) encounters <span lang="es">, it instantly pauses output, loads the Spanish voice synthesizer module, and pronounces the inline span using native Spanish phonetics. Omission causes the English synthesizer to read Spanish words phonetically as garbled English.
  • CJK Font Glyph Substitution (Han Unification): Unicode unifies Chinese, Japanese, and Korean (CJK) ideographs into shared code points. Browsers rely on the lang attribute (lang="zh-Hans", lang="zh-Hant", lang="ja", lang="ko") to pick the correct regional glyph variant from system fonts. Omitting lang on Japanese or Chinese text renders incorrect stroke shapes.
  • Hyphenation and Quotation Mark Localization (:lang()): CSS pseudo-class selectors (:lang(fr)) dynamically style nested inline quotes with proper localized glyphs (« and » for French vs and for German).

Verification

  • Inspect inline foreign language spans in DevTools: confirm lang="..." contains a valid BCP 47 tag.
  • Test with VoiceOver or NVDA to verify natural voice synthesizer switching when traversing foreign phrases.
  • Check CJK content to ensure proper regional glyph selection in typography.

Related topics

Sources & further reading