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).

Why specify the language of content?

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.

Other benefits

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.

Examples of primary language declarations

Use:

<html lang="en"> to show a web page is in English
<html lang="en-nz"> to show a page is in New Zealand English
<html lang="mi"> to show a page is in te reo Māori.

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.

Use the lang attribute to indicate any language changes in text on a web page.

Example of markup to indicate a change in language

In this sentence the language changes from English to Spanish:

<p>My friend isn’t very good at speaking Spanish. While we were in Spain, everyone kept saying to her “<span lang="es">No comprendo nada de lo que dices.</span>”</p>

Exceptions

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.

Right-to-left languages

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 dir attribute.

Example of markup for right-to-left language

<p lang="he" dir="rtl">לחיים</p>

לחיים is a Hebrew blessing or toast, “to life”.

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.

PDF

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.

Word

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

Web page

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 lang attribute on the opening <html> tag.
If there are any foreign words or expressions, check that the opening tag of the element that contains them has a lang attribute with the correct language code.

PDF

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.