Language of content
Declare the language of text content so that browsers and text-to-speech software can read it correctly.
Meeting the Web Accessibility Standard
When the primary language of a web page is specified, this meets WCAG 2 Success Criterion 3.1.1 Language of Page (Level A).
When language changes in a web page are specified, this meets WCAG 2 Success Criterion 3.1.2 Language of Parts (Level AA).
On this page
- Why specify the language of content?
- Setting the language in HTML
- Setting the language in PDF and Microsoft Word
- Testing that language is correctly identified
Why specify the language of content?
Benefits screen reader users
Specifying the language that content is written in enables screen reader and other text-to-speech software to properly pronounce that content according to the rules of that language (as long as the software supports the language identified).
If the language of web content is different from the screen reader software’s default language setting and cannot be identified by the software, the screen reader will read out the web page with the incorrect accent and pronunciation for that language, making it difficult to understand, if not incomprehensible for the user.
When browsers know what language web content is in, they can present that content in ways that make it easier for disabled people — and all users generally — to understand it. For example:
- browsers can display text using characters and scripts appropriate to the language in question
- video players can display captions in the appropriate language
- search engines can more accurately index content by language.
For more reasons to declare the language of web content, see Why use the language attribute? — W3C.
Setting the language in HTML
In web pages, the
lang attribute is used to declare the language of content. The
lang attribute takes an ISO-639 language code or ‘subtag’ as its value.
For a full list of language codes, see:
Or try out the Language Subtag Lookup tool.
For more detailed information on declaring the language of web content and using the
lang attribute, see Declaring language in HTML — W3C.
Declare the primary language of a web page
In the opening
<html> tag, specify the primary language of the web page by adding the
lang attribute with the correct ISO-639 code.
Indicate a switch to a different language in a web page
If there are words or passages of text that switch to different languages, you’ll need to indicate which language the text has changed to.
lang attribute to indicate any language changes in text on a web page.
The following types of words or text that change to another language do not need to have their language identified:
- proper names
- technical terms
- words whose language cannot be determined
- foreign words or phrases that have become part of the main language — for example, “déjà vu” is a phrase used in general English but is of French origin, and is pronounced properly by English screen reader software.
Te reo Māori in New Zealand English
New Zealand phrases like “kia ora” (hello) and “haere mai” (welcome) or a word like “whānau” (family) will not be found in typical English dictionaries. But they can be found in the New Zealand Oxford Dictionary, as they, along with many other Māori words and phrases, have become part of New Zealand English.
At the same time, te reo Māori is pronounced in ways that English is not. This has a direct impact on the accessibility of the content for people who listen to text as it is read out to them by their screen reader software. While a phrase like “kia ora” might still be recognisable when it is pronounced as if it were English, words like “whānau” or “haere mai”, and any longer passages in Māori, could be very difficult for some people to understand. There is also the question of showing respect for the proper pronunciation of languages other than English.
NVDA (Non-Visual Desktop Access) is a popular and free screen reader for Windows. The speech synthesiser that it comes with by default is able to pronounce te reo Māori rather faithfully, as long as such passages are correctly declared to be in Māori.
Therefore, where practicable, use HTML markup to explicitly identify all te reo Māori content on a web page. There are several ways to do this programmatically to reduce the effort for authors and content designers, who otherwise might have to do it manually in their editor. For example, as content is saved to a CMS, it could be machine-reviewed against a list of common Māori words/phrases, and automatically marked up, or at least the author prompted to indicate the change in language.
If the language is one that needs to be read from right to left, such as with Hebrew, Arabic and Urdu, then you’ll need to specify the direction by using the
For more on the
dir attribute, see: dir — MDN Web Docs.
Setting the language in PDF and Microsoft Word
The default language, as well as any changes to the language of words or passages in the text, can also be set in PDF and Microsoft Word documents to meet the Web Accessibility Standard.
In Adobe Acrobat Pro, navigate to the File menu and select ‘Properties…’, which opens the ‘Document Properties’ dialog window. Go to the ‘Advanced’ tab in this window and choose the PDF’s default language from the dropdown list in the ‘Language’ field.
To indicate changes in the language of words in the text of a PDF, see the W3C's Technique for WCAG 2, Specifying the language for a passage or phrase with the Lang entry in PDF documents.
The way to change the editing and proofing language used in Microsoft Word is different depending on the version of Word that you have. For help, see Microsoft's guidance, Change the language Office uses in its menus and proofing tools.
Testing that language is correctly identified
Inspect the HTML source of the web page and search for the markup that you want to check.
- Check that the primary language of the page is declared in a
langattribute on the opening
- If there are any foreign words or expressions, check that the opening tag of the element that contains them has a
langattribute with the correct language code.
- Make sure that you have Adobe Reader installed on your machine. Note that Adobe Reader can only view the PDF’s language setting. To change the language setting, you’ll need Adobe Acrobat or another PDF editor.
- Open the Document Properties of the PDF and select ‘Advanced’ in the dialog window.
- Check under ‘Reading Options’ that the language is set.