Missing Language Attribute | Blue Frog Docs

Missing Language Attribute

Add proper lang attribute to HTML elements for accessibility and internationalization

Missing Language Attribute

What This Means

The language attribute (lang) tells browsers, screen readers, and search engines what language your content is written in. When the lang attribute is missing from the <html> element or incorrectly applied to content in different languages, screen readers may pronounce words incorrectly, translation tools malfunction, and search engines struggle to serve your content to the right audience.

How the Language Attribute Works

The Problem Without Language Declaration:

<!-- WRONG: No language specified -->
<!DOCTYPE html>
<html>
<head>
    <title>Welcome to Our Site</title>
</head>
<body>
    <h1>Hello World</h1>
    <p>This is English content, but screen readers don't know that!</p>
</body>
</html>

Screen reader impact:

  • May use wrong language pronunciation rules
  • "Resume" (English) vs "Résumé" (French) sound different
  • "Read" (present) vs "Read" (past) need context
  • User with French screen reader gets French pronunciation for English words

Correct Implementation:

<!-- CORRECT: Language specified -->
<!DOCTYPE html>
<html lang="en">
<head>
    <title>Welcome to Our Site</title>
</head>
<body>
    <h1>Hello World</h1>
    <p>This is English content!</p>

    <!-- French section within English page -->
    <blockquote lang="fr">
        <p>Bonjour le monde!</p>
    </blockquote>
</body>
</html>

Impact on Your Business

Accessibility Impact:

  • Broken screen reader pronunciation - Users can't understand content
  • Poor user experience - Disabled users struggle to use site
  • WCAG violation - Fails WCAG 2.1 Level A requirement 3.1.1
  • Legal liability - ADA compliance issues
  • Lost customers - 15% of users have some form of disability

SEO Consequences:

  • Wrong geographic targeting - Google serves content to wrong countries
  • Hreflang issues - Multilingual sites don't work properly
  • Lower rankings - Search engines can't identify language
  • Missed traffic - Users searching in your language don't find you

Internationalization Issues:

  • Translation tools fail - Google Translate can't detect language
  • Browser features break - Auto-translate, spell-check malfunction
  • Font rendering issues - Some languages need specific fonts
  • Text direction problems - RTL languages render incorrectly

How to Diagnose

Method 1: View Page Source

  1. Right-click page
  2. Select View Page Source
  3. Look at first few lines

Check For:

❌ Missing lang attribute:

<!DOCTYPE html>
<html>
<!-- No lang attribute -->

✅ Correct lang attribute:

<!DOCTYPE html>
<html lang="en">
<!-- Language declared -->

Method 2: Browser DevTools

  1. Open DevTools (F12)
  2. Go to Elements tab
  3. Look at <html> element
  4. Check attributes panel

Look For:

<html lang="en"> ✅ Good
<html> ❌ Missing
<html lang=""> ❌ Empty
<html lang="english"> ❌ Wrong format (use ISO 639-1 codes)

Method 3: Lighthouse Accessibility Audit

  1. Open DevTools (F12)
  2. Go to Lighthouse tab
  3. Check Accessibility
  4. Click Generate report

Check For:

Accessibility Issues:
⚠ <html> element does not have a [lang] attribute

Impact: Serious
WCAG: 3.1.1 Language of Page (Level A)

Method 4: WAVE Browser Extension

  1. Install WAVE Extension
  2. Visit your page
  3. Click WAVE icon

Look For:

  • "Language missing or invalid" error
  • Red icon indicating critical issue

Method 5: W3C Validator

  1. Visit W3C Validator
  2. Enter your URL
  3. Click Check

Check Results:

Warning: Consider adding a lang attribute to the html
start tag to declare the language of this document.

Method 6: Screen Reader Test

  1. Enable screen reader (VoiceOver, NVDA, JAWS)
  2. Navigate to page
  3. Listen to pronunciation

What to Listen For:

  • Words pronounced in wrong language
  • Jarring accent switches
  • Incomprehensible text

General Fixes

Fix 1: Add lang to HTML Element

Basic implementation:

<!-- English -->
<!DOCTYPE html>
<html lang="en">

<!-- French -->
<!DOCTYPE html>
<html lang="fr">

<!-- Spanish -->
<!DOCTYPE html>
<html lang="es">

<!-- German -->
<!DOCTYPE html>
<html lang="de">

<!-- Japanese -->
<!DOCTYPE html>
<html lang="ja">

<!-- Chinese (Simplified) -->
<!DOCTYPE html>
<html lang="zh-CN">

<!-- Chinese (Traditional) -->
<!DOCTYPE html>
<html lang="zh-TW">

<!-- Arabic -->
<!DOCTYPE html>
<html lang="ar" dir="rtl">
<!-- Note: RTL languages also need dir="rtl" -->

Fix 2: Use Region-Specific Language Codes

When you need to specify region:

<!-- US English -->
<html lang="en-US">

<!-- UK English -->
<html lang="en-GB">

<!-- Canadian French -->
<html lang="fr-CA">

<!-- France French -->
<html lang="fr-FR">

<!-- Mexican Spanish -->
<html lang="es-MX">

<!-- Spain Spanish -->
<html lang="es-ES">

<!-- Brazilian Portuguese -->
<html lang="pt-BR">

<!-- Portugal Portuguese -->
<html lang="pt-PT">

Format: language-REGION

  • Language: ISO 639-1 (2-letter code)
  • Region: ISO 3166-1 (2-letter country code)

Fix 3: Mark Sections in Different Languages

Content with mixed languages:

<!DOCTYPE html>
<html lang="en">
<head>
    <title>International Company</title>
</head>
<body>
    <!-- Main content in English -->
    <h1>Welcome to Our Company</h1>
    <p>We operate globally with offices worldwide.</p>

    <!-- French testimonial -->
    <blockquote lang="fr">
        <p>Excellent service! Je recommande vivement cette entreprise.</p>
        <footer> -  Pierre Dubois</footer>
    </blockquote>

    <!-- Spanish section -->
    <section lang="es">
        <h2>Información en Español</h2>
        <p>Contáctenos para más información.</p>
    </section>

    <!-- German quote -->
    <p>As the saying goes, <q lang="de">Ordnung muss sein</q>.</p>
</body>
</html>

Fix 4: WordPress Implementation

Theme files (header.php):

<!-- BEFORE: Missing lang -->
<!DOCTYPE html>
<html <?php language_attributes(); ?>>
<!-- This outputs lang attribute automatically -->

<!-- Output: -->
<!DOCTYPE html>
<html lang="en-US">

<!-- For multilingual sites using WPML/Polylang: -->
<!-- The plugin automatically sets correct lang per page -->

Manually set if needed:

<!DOCTYPE html>
<html lang="<?php echo get_bloginfo('language'); ?>">

Fix 5: React/Next.js Implementation

Next.js (pages/_document.js):

import Document, { Html, Head, Main, NextScript } from 'next/document';

class MyDocument extends Document {
    render() {
        return (
            <Html lang="en">
                <Head />
                <body>
                    <Main />
                    <NextScript />
                </body>
            </Html>
        );
    }
}

export default MyDocument;

React (index.html or public/index.html):

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>React App</title>
</head>
<body>
    <div id="root"></div>
</body>
</html>

Dynamically change language in React:

import { useEffect } from 'react';

function App() {
    const currentLanguage = 'fr'; // from state/context

    useEffect(() => {
        document.documentElement.lang = currentLanguage;
    }, [currentLanguage]);

    return <div>App content</div>;
}

Fix 6: Server-Side Language Detection

Node.js/Express example:

const express = require('express');
const app = express();

app.get('/', (req, res) => {
    // Detect user's language from Accept-Language header
    const userLang = req.acceptsLanguages(['en', 'fr', 'es', 'de']) || 'en';

    res.send(`
        <!DOCTYPE html>
        <html lang="${userLang}">
        <head>
            <title>Multilingual Site</title>
        </head>
        <body>
            <h1>Content in ${userLang}</h1>
        </body>
        </html>
    `);
});

Fix 7: Static Site Generators

Jekyll (_layouts/default.html):

<!DOCTYPE html>
<html lang="{{ site.lang | default: 'en' }}">
<head>
    <title>{{ page.title }}</title>
</head>
<body>
    {{ content }}
</body>
</html>

Hugo (layouts/_default/baseof.html):

<!DOCTYPE html>
<html lang="{{ .Site.Language.Lang }}">
<head>
    <title>{{ .Title }}</title>
</head>
<body>
    {{ block "main" . }}{{ end }}
</body>
</html>

Gatsby (gatsby-ssr.js):

export const onRenderBody = ({ setHtmlAttributes }) => {
    setHtmlAttributes({ lang: 'en' });
};

Fix 8: Shopify Theme

theme.liquid:

<!DOCTYPE html>
<html lang="{{ shop.locale }}">
<head>
    <title>{{ page_title }}</title>
</head>
<body>
    {{ content_for_layout }}
</body>
</html>

Platform-Specific Guides

Detailed implementation instructions for your specific platform:

Platform Troubleshooting Guide
Shopify Shopify Language Attribute Guide
WordPress WordPress Language Attribute Guide
Wix Wix Language Attribute Guide
Squarespace Squarespace Language Attribute Guide
Webflow Webflow Language Attribute Guide

Verification

After adding language attributes:

Test 1: View Source

  1. View page source
  2. Confirm <html lang="XX"> present
  3. Verify correct language code
  4. Check language-specific sections marked

Test 2: Lighthouse

  1. Run Lighthouse accessibility audit
  2. "html element has lang attribute" should pass
  3. Accessibility score should improve

Test 3: W3C Validator

  1. Validate HTML
  2. No language warnings
  3. Valid language codes used

Test 4: Screen Reader

  1. Enable screen reader
  2. Navigate to page
  3. Listen to pronunciation
  4. Should use correct language voice
  5. Multi-language sections should switch voices

Test 5: Browser DevTools

// Check current language
console.log(document.documentElement.lang);
// Output: "en"

// Check all elements with lang
document.querySelectorAll('[lang]').forEach(el => {
    console.log(el.tagName, el.lang, el.textContent.substring(0, 50));
});

Common Mistakes

  1. Using full language names - Use ISO codes (en, not english)
  2. Wrong code format - Use lowercase (en-US, not EN-us)
  3. Forgetting multi-language content - Mark sections in different languages
  4. Not updating dynamically - Single-page apps need to update lang attribute
  5. Incorrect region codes - en-UK is wrong, use en-GB
  6. Missing from iframe - Iframes need own lang attribute
  7. Using non-standard codes - Stick to ISO 639-1 codes
  8. Not considering RTL - Arabic, Hebrew need dir="rtl" too

Language Code Reference

Common ISO 639-1 language codes:

Code Language
ar Arabic
de German
en English
es Spanish
fr French
hi Hindi
it Italian
ja Japanese
ko Korean
nl Dutch
pl Polish
pt Portuguese
ru Russian
zh Chinese

Full list: ISO 639-1 Codes

Further Reading

↑ Back to top
// SYS.FOOTER