View contents
Language Attributes: Ensuring Proper Language Identification for Accessibility
Introduction
The HTML lang attribute tells browsers and assistive technologies what human language your content is in. WCAG 3.1.1 (Language of Page) requires every web page to have its primary language declared. This seemingly simple attribute has profound impacts on accessibility, pronunciation, and user experience.
Screen readers use the language attribute to select the correct pronunciation rules and voice. Without proper language identification, a screen reader might read French text with English pronunciation, making the content incomprehensible to users.
What WCAG Requires
3.1.1 Language of Page (Level A)
The default human language of each Web page can be programmatically determined.
This means:
- Every HTML page must have a
langattribute on the<html>element - The value must be a valid BCP 47 language tag (e.g., “en”, “es”, “fr”)
- This allows assistive technologies to load appropriate pronunciation rules
3.1.2 Language of Parts (Level AA)
The human language of each passage or phrase in the content can be programmatically determined.
This means:
- Content in a different language than the page default should have its own
langattribute - This applies to quotes, phrases, or sections in foreign languages
- Exceptions: proper names, technical terms, words that have become part of the surrounding language
Who Benefits
| User Type | Benefit |
|---|---|
| Screen reader users | Correct pronunciation of content |
| Users of translation tools | Accurate translation targeting |
| Users with reading disabilities | Proper hyphenation and text processing |
| Search engines | Better understanding of content language |
| All users | Correct spell-checking and auto-correction |
Basic Implementation
Page Language
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Page Title</title>
</head>
<body>
<!-- Page content in English -->
</body>
</html>
Language of Parts
<p>
The French phrase <span lang="fr">c'est la vie</span> means "that's life".
</p>
<blockquote lang="es">
<p>La vida es sueño.</p>
<cite>— Calderón de la Barca</cite>
</blockquote>
Common Language Codes
| Language | Code | Extended Variants |
|---|---|---|
| English | en |
en-US, en-GB, en-AU |
| Spanish | es |
es-ES, es-MX, es-AR |
| French | fr |
fr-FR, fr-CA |
| German | de |
de-DE, de-AT, de-CH |
| Portuguese | pt |
pt-BR, pt-PT |
| Chinese | zh |
zh-CN, zh-TW, zh-Hans, zh-Hant |
| Japanese | ja |
ja-JP |
| Korean | ko |
ko-KR |
| Arabic | ar |
ar-SA, ar-EG |
| Russian | ru |
ru-RU |
Common Problems
1. Missing lang Attribute
<!-- BAD: No language specified -->
<!DOCTYPE html>
<html>
<head>...</head>
<body>...</body>
</html>
<!-- GOOD: Language declared -->
<!DOCTYPE html>
<html lang="en">
<head>...</head>
<body>...</body>
</html>
2. Wrong Language Code
<!-- BAD: Invalid language codes -->
<html lang="english">
<html lang="eng">
<html lang="en_US">
<!-- GOOD: Valid BCP 47 codes -->
<html lang="en">
<html lang="en-US">
3. Foreign Phrases Without Language Tags
<!-- BAD: French pronounced with English rules -->
<p>The phrase croissant originated in Austria.</p>
<!-- GOOD: French word marked for correct pronunciation -->
<p>The phrase <span lang="fr">croissant</span> originated in Austria.</p>
4. Language Mismatch
<!-- BAD: Page in Spanish but marked as English -->
<html lang="en">
<body>
<h1>Bienvenido a nuestro sitio</h1>
<!-- Spanish content... -->
</body>
</html>
<!-- GOOD: Correct language declaration -->
<html lang="es">
<body>
<h1>Bienvenido a nuestro sitio</h1>
</body>
</html>
When to Mark Language of Parts
Do Mark
- Foreign words that might be mispronounced
- Quotations in other languages
- Passages or sections in different languages
- Technical terms from other languages (when pronunciation matters)
<!-- Foreign quote -->
<blockquote lang="de">
<p>Ich bin ein Berliner.</p>
</blockquote>
<!-- Foreign phrase -->
<p>The <span lang="la">status quo</span> must change.</p>
Don’t Need to Mark
- Proper names (like “François” or “München”)
- Technical terms widely used (like “pizza” or “entrepreneur”)
- Words adopted into English (like “café” or “fiancé”)
- Brand names
<!-- These don't need lang attributes -->
<p>Meet our CEO, François Martin.</p>
<p>We ordered pizza for the team.</p>
<p>She is his fiancée.</p>
Impact on Screen Readers
When a screen reader encounters text, it checks the lang attribute to select pronunciation rules:
| Without lang | With lang |
|---|---|
| “Bohn-joor” (English pronunciation) | “Bohn-zhoor” (French pronunciation) |
| Screen reader guesses language | Screen reader knows exact language |
| Potentially incomprehensible | Clear, correct pronunciation |
Testing Language Attributes
Quick Manual Test
- Check that
<html>has alangattribute - Verify the language code matches the page content
- Look for foreign phrases and check for
langattributes - Use a screen reader to verify pronunciation
What to Verify
- [ ] Page has
langattribute on<html>element - [ ] Language code is valid BCP 47 format
- [ ] Language matches actual page content
- [ ] Foreign phrases have appropriate
langattributes - [ ] Screen reader pronounces content correctly
Tools for Testing
- axe DevTools - Flags missing page language
- WAVE - Shows language attributes
- Browser DevTools - Inspect
<html>element - W3C Validator - Validates language codes
Best Practices Summary
| Do | Don’t |
|---|---|
Always include lang on <html> |
Leave lang attribute missing |
| Use valid BCP 47 codes | Use full language names or invalid codes |
| Mark foreign phrases | Leave foreign content unmarked |
| Match lang to actual content | Use wrong language code |
| Test with screen readers | Assume pronunciation is correct |
Related Articles
- Language Attributes Implementation Guide - Detailed patterns
- Semantic HTML Guide - Document structure
- WCAG Compliance Hub - All accessibility evaluators
References
- W3C - WCAG 2.2 SC 3.1.1 Language of Page
- W3C - WCAG 2.2 SC 3.1.2 Language of Parts
- W3C - H57 Using lang attribute
- MDN - lang attribute