Imagine walking into a library where every book looks identical from the outside, with no indication of what language it's written in. You'd have to open each book and try to read it before knowing whether you could understand it. That's essentially what happens when websites don't declare their language to browsers and assistive technologies.
The HTML lang attribute is a simple piece of code that tells browsers, screen readers, and other tools what language your webpage is written in. It's added to the opening HTML tag of your page and looks like this: <html lang="en"> for English, or <html lang="es"> for Spanish.
The lang attribute might seem like a small technical detail, but it serves several crucial functions that directly impact user experience:
For users of assistive technologies, the difference between a page with and without proper language declarations can be the difference between accessible content and completely incomprehensible gibberish.
When a page lacks a lang attribute, assistive technologies must guess the language based on content analysis. This guessing process can be slow, inaccurate, and often fails entirely for short content or mixed-language pages. The result is a poor user experience that can make your website completely unusable for people who rely on screen readers or other assistive technologies.
The lang attribute uses standardized language codes that ensure consistency across the web. These codes follow the ISO 639 standard and can be as simple as two letters or more complex when specifying regional variations.
en - Englishes - Spanishfr - Frenchde - Germanit - Italianpt - Portuguesezh - Chineseja - Japanesear - Arabicru - RussianYou can also specify regional differences when they matter for pronunciation or cultural context:
en-US - American Englishen-GB - British Englishes-ES - European Spanishes-MX - Mexican Spanishpt-BR - Brazilian Portuguesept-PT - European Portuguesezh-CN - Simplified Chinese (China)zh-TW - Traditional Chinese (Taiwan)For most websites, the simple two-letter code is sufficient unless you specifically need to distinguish between regional variations that affect pronunciation or user experience.
Adding language declarations is straightforward, but the approach varies depending on your website setup and content structure:
Every page should have a lang attribute on the opening HTML tag to declare the primary language of the content.
<!-- English page -->
<!DOCTYPE html>
<html lang="en">
<head>
<title>Welcome to Our Website</title>
</head>
<!-- Spanish page -->
<!DOCTYPE html>
<html lang="es">
<head>
<title>Bienvenido a Nuestro Sitio Web</title>
</head>
<!-- French page with regional specification -->
<!DOCTYPE html>
<html lang="fr-CA">
<head>
<title>Bienvenue sur Notre Site Web</title>
</head>This primary declaration covers all content on the page unless specifically overridden by more specific language declarations on individual elements.
When you have content in multiple languages on the same page, you can specify different languages for specific sections.
<!-- Page primarily in English with some Spanish content -->
<!DOCTYPE html>
<html lang="en">
<head>
<title>International Business Solutions</title>
</head>
<body>
<h1>Welcome to Our International Services</h1>
<p>We provide business solutions worldwide.</p>
<!-- Spanish section within English page -->
<div lang="es">
<h2>Servicios en Español</h2>
<p>Ofrecemos soluciones empresariales en todo el mundo.</p>
</div>
<!-- Back to English -->
<p>Contact us for more information about our global services.</p>
</body>
</html>You can apply the lang attribute to any HTML element (paragraphs, divs, spans, etc.) to mark content in a different language from the page default.
Most modern CMS platforms make it easy to set language declarations:
If your CMS doesn't automatically handle this, you can usually add it manually through theme files or custom HTML sections.
For websites that serve multiple languages dynamically, you can set the lang attribute programmatically.
// JavaScript example for dynamic language setting
function setPageLanguage(languageCode) {
document.documentElement.lang = languageCode;
}
// React example
function App({ language }) {
useEffect(() => {
document.documentElement.lang = language;
}, [language]);
return <div>Content in {language}</div>;
}
// PHP example for server-side setting
<?php
$user_language = getUserLanguagePreference(); // Your language detection logic
?>
<!DOCTYPE html>
<html lang="<?php echo htmlspecialchars($user_language); ?>">
<head>
<title>Dynamic Language Site</title>
</head>This approach ensures that the language declaration always matches the actual content being served to users.
Even though implementing lang attributes is straightforward, several common mistakes can undermine their effectiveness:
What's happening: Using non-standard or incorrect language codes that assistive technologies don't recognize.
Simple solution: Always use standard ISO 639 language codes. Verify your codes against official references rather than guessing. Common mistakes include using "eng" instead of "en" or "chinese" instead of "zh".
What's happening: Adding the lang attribute to the body tag or other elements instead of the html tag for page-level language declaration.
Simple solution: Always set the primary language on the opening <html> tag. Use lang attributes on other elements only for content that differs from the page's primary language.
What's happening: Translated versions of pages still have the original language's lang attribute.
Simple solution: Ensure that when content is translated, the lang attribute is updated to match. This is especially important for sites with multiple language versions or user-generated content in different languages.
What's happening: Using overly specific regional codes when the general language code would be more appropriate and accessible.
Simple solution: Use simple language codes (like "en" for English) unless you specifically need regional distinction for pronunciation or cultural reasons. Over-specification can sometimes cause assistive technologies to fail if they don't support the specific regional variant.
What's happening: Comments, reviews, or other user-generated content in different languages lacks proper language markup.
Simple solution: For platforms with international users, consider implementing language detection for user-generated content or allowing users to specify the language of their contributions. Many modern language detection APIs can help automate this process.
Beyond basic implementation, several advanced scenarios require thoughtful approach to language declarations:
When your content includes brief quotes or phrases in other languages, mark them appropriately.
<!-- English article with French phrase -->
<p>The French phrase <span lang="fr">"c'est la vie"</span> means "that's life" in English.</p>
<!-- English article with Spanish quote -->
<blockquote lang="es">
<p>La vida es como una caja de chocolates, nunca sabes lo que te va a tocar.</p>
<cite>Translation of famous Forrest Gump quote</cite>
</blockquote>Generally, proper names (people, places, brands) don't need language markup even if they originate from other languages, as they're typically pronounced the same regardless of the surrounding language context.
<!-- These don't need lang attributes -->
<p>We visited Tokyo, Paris, and München on our trip.</p>
<p>The conference featured speakers from BMW, Toyota, and Nestlé.</p>
<!-- But if you want to preserve original pronunciation, you can -->
<p>We visited Tokyo, Paris, and <span lang="de">München</span> on our trip.</p>Programming code and technical examples typically shouldn't have language attributes, as they're not natural language content.
<!-- Code blocks don't need lang attributes for natural language -->
<pre><code>
function sayHello() {
console.log("Hello, world!");
}
</code></pre>
<!-- But comments within code might benefit from language marking -->
<pre><code>
// English comment
function sayHello() {
console.log("Hello, world!"); // English string
}
/* <span lang="es">Comentario en español</span> */
console.log("Hola, mundo!");
</code></pre>It's important to verify that your language declarations are working correctly. Here are several approaches:
Regular testing helps ensure that your language declarations remain accurate as your content evolves.
Implementing proper lang attributes contributes to several important outcomes:
These benefits combine to create more inclusive, accessible, and professionally developed websites that serve all users effectively.
Here are some examples of how different types of websites can implement effective language declarations:
In each case, the key is consistency, accuracy, and attention to how users with different needs and technologies will interact with the content.
The HTML lang attribute represents one of the simplest yet most impactful accessibility improvements you can make to your website. It requires minimal technical effort but provides substantial benefits to users of assistive technologies, while also improving your site's functionality for all users.
What makes the lang attribute particularly valuable is its role as a foundation for other accessibility and user experience features. When browsers and assistive technologies know what language they're working with, they can provide better pronunciation, more accurate translations, effective spell checking, and improved voice control support.
The global nature of the modern web means that proper language declarations aren't just about compliance or accessibility—they're about building websites that truly work for the diverse, international audience that the internet serves. Whether someone is using a screen reader in Seoul, enabling auto-translation in São Paulo, or navigating with voice commands in Stockholm, proper language declarations help ensure your content is accessible and usable.
As we continue building a more inclusive web, let's remember that accessibility often comes down to small details implemented thoughtfully. The lang attribute is a perfect example of how a simple HTML attribute can bridge the gap between content creators and users, ensuring that language differences enhance rather than hinder the web experience.
Greadme's easy-to-use tools can help you identify missing or incorrect language declarations on your website and provide simple instructions to fix them—even if you're not technically minded.
Check Your Website's Language Declarations Today