Ask the Community
valid-lang
Rule Severity : Serious
Description
The valid-lang rule ensures that lang attributes on HTML elements contain valid BCP 47 language tags. Browsers and assistive technologies rely on lang attribute values to select the correct pronunciation rules, voice profile, and text processing behavior. An invalid language tag, such as a full language name instead of a code or an underscore instead of a hyphen, prevents assistive technologies from identifying the language, causing mispronunciation or incorrect text rendering.
This rule meets WCAG requirements by:
-
Language of Page (WCAG 3.1.1 Language of Page): The default human language of each web page must be programmatically determinable. An invalid
langvalue on the<html>element means the page language cannot be reliably determined. -
Language of Parts (WCAG 3.1.2 Language of Parts): The human language of each passage or phrase in the content must be programmatically determinable. An invalid
langvalue on inline elements means the language of that passage cannot be correctly identified by assistive technologies.
To comply with this rule, use valid BCP 47 language tags. Primary language subtags are two-letter ISO 639-1 codes (such as en, fr, es, de, ja). Region subtags use ISO 3166-1 alpha-2 codes (such as US, GB, FR) and are always separated from the primary subtag by a hyphen, not an underscore.
Examples
This example shows two invalid lang values: the <html> element uses the full word “english” instead of a BCP 47 code, and the inline <span> uses an underscore separator instead of a hyphen. Neither value will be recognized by assistive technologies.
Here, both lang values are valid BCP 47 tags. The <html> element uses en-US for US English, and the inline French phrase uses fr so screen readers switch to a French voice profile when reading that text.
How to fix?
To fix violations of the valid-lang rule, follow these steps:
-
Identify all elements with a
langattribute and verify that the attribute value is a valid BCP 47 language tag. -
Replace full language names (such as “english” or “french”) with their two-letter ISO 639-1 primary subtags (such as
enorfr). -
Replace any underscores used as separators with hyphens. For example, change
en_UStoen-USandzh_TWtozh-TW. -
For pages that only need to specify a primary language without a regional variant, a two-letter code alone (such as
en,fr, ores) is sufficient for the<html>element.
Reference
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
Thank you for your valuable feedback!