Did a “Missing Language Declaration” error appear in an Accessibility Checker audit of one of your WordPress posts or pages? Read on below for an explanation of these errors, how they impact your website’s accessibility, and how to fix them.
About the Missing Language Declaration Error
What is a language declaration?
A language declaration is an HTML attribute that denotes the default language of the content on a page or post. Language declarations should be coded into your website theme and appear automatically in the head of the website (the first section of code that contains information about a web page’s properties).
Language declarations are available to search engines and assistive technology but are not visible on the page.
Here is what a language declaration for an English web page looks like in XHTML:
<html xmlns="http://website.com/xhtml" xml:lang="en" lang="en">
And here is how it looks in HTML5:
<html xml:lang="en" lang="en">
The language declaration should immediately follow the doctype declaration.
What does the Missing Language Declaration error mean?
If you have a post or page with a Missing Language Declaration error that means that the page or post is not outputting the required language attribute on the HTML tag and assistive devices will not know what language the page is in.
How does Accessibility Checker test for the language declaration?
While auditing your post or page, Accessibility Checker finds the <HTML> tag and checks to see if lang or XML:lang is present in the tag and that the attribute is not empty.
Impact on Accessibility
Why are language attributes important?
It is important to declare the language of your page because it is used in a variety of ways by assistive technology and without this declaration, blind and visually imparied users may not be able to access the content on the site.
Screen readers use the language attributes to read the content of a page. Without an attribute, the screen reader may have a difficult time determining which language the page or post is in, and may miss sections of text or convey them incorrectly.
Braille keyboards and refreshable braille displays use language attributes to substitute control codes for accented characters, ensuring that the user understands words, phrases, and sections of text correctly.
Some speech synthesizers support multiple languages, and need the language attribute to orient themselves and use the correct pronunciations and syntax of a certain language. Without a language attribute, a speech synthesizer is likely to mispronounce the text and a user may have difficulty understanding it.
In addition to helping people with disabilities, language attributes also help people who speak other languages and may be translating your website, and they can be used by search engines to understand your content and determine your ranking.
Relevant WCAG 2.1 Success Criteria
3.1.1 Language of Page – Level A
The default human language of each Web page can be programmatically determined.
3.1.2 Language of Parts – Level AA
The human language of each passage or phrase in the content can be programmatically determined except for proper names, technical terms, words of indeterminate language, and words or phrases that have become part of the vernacular of the immediately surrounding text.
How to Fix a Missing Language Declaration Error
What to do (in short)
First, install the free Accessibility Checker WordPress plugin.
To fix a Missing Language Declaration error, you will need to edit your theme files to add the missing language attribute to the HTML tag at the very top of your website header. If you’re using a theme that receives updates, then you’ll need to make the change in a child theme to ensure the fix does not get overwritten when you next update your theme.
This is a change that will likely require a developer’s assistance. If you don’t know how to make this change yourself, please see our article discussing what to do if there are accessibility errors in your theme.
Note: language changes within content should also be declared
Just as it is important to declare the language of the whole page, if you change language mid-way through a post or page, it is also important to declare the language change when that change happens.
Accessibility Checker does not currently test for language changes mid-page (though may in a future release), but it is still important that you tag any language changes as they happen.
If your main website is in English, for example, but you provide Spanish translations following your English content, you need to alert screen readers and other assistive technology that the language is changing. This notification can be done by adding the language declaration in a <div> or a <span> or <p> tag that wraps around content in the new language, which will ensure that your user’s assistive technology can accurately convey the text in the second language.
Here is an example of how you can communicate a change in language mid page:
<p>Here is a sentence in English. Most of my content is in English and the main document language is declared to be English so this paragraph does not need a language declaration.</p>
<p lang="es" xml:lang="es">Aquí hay una oración en español. Usamos el traductor de Google, así que espero que sea correcto. Debido a que este párrafo está en un idioma nuevo, lo hemos notado en el HTML del párrafo.</p>Notice the last paragraph has language declarations to tell assistive devices that we have changed from English to Spanish. In case you’re curious, that paragraph reads: “Here is a sentence in Spanish. We used Google translate so hopefully it is correct. Because this paragraph is in a new language, we have noted that in the HTML for the paragraph.”
Language codes
When denoting the language for the page or a section of the page, you need to use the recognized two or four letter language code a.k.a “language culture name.”
Base languages are two letters but you can add additional letters to denote dialect or regional differences in the language. For example, the HTML code for English is “en”, but you can denote American English with “en-US” or British English with “en-GB”.
Here are some language codes for languages most spoken in the world:
| Language | Code |
|---|---|
| English | en |
| Chinese | zh |
| Spanish | es |
| French | fr |
| Hindi | hi |
| Arabic | ar |
| Portuguese | pt |
| Russian | ru |
| Japanese | ja |
| Bengali | bn |
| Indonesian | id |
