What This Rule Checks
The lang attribute in the <html> tag specifies the primary language of the webpage. It is crucial for making content accessible to users relying on assistive technologies like screen readers, ensuring that text is pronounced correctly. If the value of the lang attribute is invalid, these tools may be unable to determine the language, leading to mispronunciations or a suboptimal experience for users with disabilities.
Who Is Affected
This issue primarily affects: Blind users, who rely entirely on screen readers or braille displays to navigate and interact with content; Deafblind users, who rely on braille displays and cannot access visual or auditory content; Cognitive users, who benefit from clear structure, simple language, and consistent navigation patterns.
Why This Matters
Invalid lang values prevent screen readers from selecting the correct pronunciation engine. The fallback behavior varies — some screen readers default to the user’s system language, others may produce no speech at all for unrecognized codes.
How to Fix
Use Standard Two-Letter Language Codes: Ensure that the language code follows the correct ISO 639-1 standard (two-letter codes). For example, use lang=”en” for English, lang=”fr” for French, or lang=”es” for Spanish.
Optionally Include Region Codes: If necessary, you can include a region code in addition to the language code to specify regional variations (e.g., lang=”en-US” for American English, lang=”en-GB” for British English).
Right-to-Left (RTL) Languages: If your content is in a right-to-left language, such as Arabic (lang=”ar”) or Hebrew (lang=”he”), add dir=”rtl” to the <html> tag to ensure proper text direction.
Specify Language Changes Within a Document: If different sections of your content are in different languages, specify the language for those sections using the lang attribute on specific elements.
Code Examples
<!-- Invalid language codes -->
<html lang="english">
<!-- Full word, not BCP 47 -->
</html>
<html lang="us">
<!-- Country code, not language -->
</html>
<html lang="x-klingon">
<!-- Not a registered language -->
</html>
Copy
<!-- Valid BCP 47 language codes -->
<html lang="en">
<!-- English -->
</html>
<html lang="en-US">
<!-- American English -->
</html>
<html lang="pt-BR">
<!-- Brazilian Portuguese -->
</html>
Copy
Common Mistakes to Avoid
- Using full language names (“English”) instead of BCP 47 codes (“en”).
- Using country codes alone (“US”) instead of language codes (“en-US”).
- Misspelling language codes (e.g., “eng” instead of “en”).
AI Auto-Fix Available
This rule supports ACE™ AI Auto-Fix. When a violation is detected, ACE can automatically generate a code fix for review. The AI analyzes the specific element in context and proposes a targeted remediation that preserves your existing markup and styling. You can preview, modify, and approve the fix before it is applied.
Tip: Page-level metadata and settings affect the entire browsing experience. Language declarations, viewport settings, and page titles are foundational to accessibility and affect every user on every page load.
Related WCAG Criteria
• 3.1.1: Language of Page