Epub Language Codes

[Mario Davis]

Althoughthe xml:lang attribute sets the language for XML grammars like XHTMLand SVG, it is also good practice to include a lang attribute with the samevalue. Refer to the section on setting the langattribute for more information.

Setting the language of a publication is an important step in ensuring its accessibility as it helpsassistive technologies pronounce the text correctly. Without language declarations, assistivetechnologies will read the text in the default language of the user. This can lead to the entiretext being mispronounced (when reading a publication in another language) or individual phrasesbeing mangled (for inline foreign phrases).

This tutorial covers how to set the language in the EPUB package document as well as in XHTML andSVG content documents so that the information is available to assistive technologies and readingsystems.

Before we can get into the mechanisms for setting the language, it is important to firstunderstand what you are setting. Languages are declared using language tags, whichare hyphen-separated codes that identify the language, region, script, etc.

American and British pronunciations, for example, can differ significantly, but a code of"en" will not inform an assistive technology which to apply when it matters (e.g.,when reading an American or British novel where the characters talk in regional dialects).Adding the region solves this problem as it allows the assistive technology to pick a moreappropriate voice for playback.

You can also specify the script the text is written in using a script subtag. Simplified andtraditional Chinese, for example, can be differentiated using the "zh-Hans" and "zh-Hant"script tags. You should only use script subtags when a language is commonly written in morethan one script.

With an understanding now of what language tags are, it is time to turn to how to express thosetags in markup languages.In XML-based markup languages, like XHTML, SVG and the EPUB package document, the standardmechanism for declaring the language of the text is the xml:lang attribute, wherethe value of this attribute is a language tag.

Not all publications are written in a single language. Multilingual publications may switchbetween languages often, while other publications may contain short phrases or single words inanother language.

To indicate a change of language, you only need to declare the new language on a tag thatsurrounds the foreign text. The change in language only exists within that tag, as shown in thefollowing example:

It is important to indicate when the primary language changes so that text-to-speech engines canpronounce the foreign language phrases correctly. Without the correct language information theywill try to pronounce the text according to the rules for the default language.

It is not necessary to indicate a language change for terms and phrases that have become part ofthe default language, however. Words like "caf" and "coup d'tat", althoughFrench in origin, are now considered common English phrases. Text-to-speech engines cantypically handle these words as English.

The package document is central to an EPUB publication as it contains the metadata about thework, the resources that belong to it, and how to order those resources into a reading order.As you may have guessed already, because the package document contains metadata such as thetitle and author names, it is important to tell reading systems what language this informationis in.

With a global language declaration on the package element, you only need to overridethat declaration if metadata is written in another language. For example, if the book is a translation,you can indicate the language of the author's name by adding a language declaration to theirdc:creator tag:

One limitation of the package document metadata is that it is not possible to override thelanguage of the text within a metadata tag. If you have a title that includes aforeign-language term or phrase, for example, you cannot identify that that text is in adifferent language. It will have to be read in the default language for the tag.

Note that it is rarely helpful to use region codes (e.g., adding "-US" for American English) inthe package document metadata. Users will typically expect to hear the metadata announced intheir preferred regional dialect.

Setting the language of the package document metadata is only the first step in defining theneeded language information for reading systems. It is also necessary to specify the languageof the publication content in the package document, as is covered in the next section.

Although the xml:lang attribute specifies the language of the package documentmetadata, it does not tell reading systems the language of the content of the publication.The language of the metadata and content is often the same, but there are good reasons why aseparate method of specifying this is included. For example, the work may be multilingual, orit may be written in a specific regional dialect.

EPUB requires authors to include at least one dc:language tag in the packagedocument metadata to identify the primary language(s) of the content. Like with thexml:lang attribute, the value of this element is a language code:

If a publication is written in more than one language (e.g., a new language learning guide), youcan repeat the dc:language element for each language (refer to example 2). Do not place all the languages into a single tag. The orderin which you list the languages indicates their primacy (i.e., the firstdc:language element defines the primary language of the work).

The language information contained in the dc:language tags is only informative,however. Setting this property helps reading systems optimize the rendering of the publication.They might use this information to preload a language-specific dictionary, for example, or topreload a text-to-speech engine so that users do not encounter a delay when they try to voicethe content. It is still necessary to set both the language of the package document metadata and the language of each content document in the publication.

Although language settings in the package document are important to set, it is even morecritical to specify the language of each content document. The information set in the packagedocument does not automatically filter down.

Setting the language of XHTML and SVG content documents, the two primary formats EPUB supports,is no different than setting the language in the package document. The primary language of thedocuments is set on the respective root element of each document (refer to example 4). You can then indicate that terms and phrases are in anotherlanguage by wrapping them in any of HTML's or SVG's various tags.

Although you are only required to use the xml:lang attribute with XHTMLand SVG documents, it is best practice to also add a lang attribute. Whendoing so, the language tag expressed in the xml:lang and langattributes must match. For example:

The reason it is recommended to add both attributes is that XHTML and SVG documentsin EPUB publications may not always be processed as XML, despite the requirements of thestandard. A browser-based reading system might, for example, default to processing all theXHTML documents as regular HTML. In this case, HTML processors ignore thexml:lang attribute as they only recognize the lang attribute. Byalways adding both attributes, you help ensure that the correct language information isavailable to users regardless of how the document is processed.

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at

A W3C Recommendation is a specification that, after extensive consensus-building, is endorsed by W3C and its Members, and has commitments from Working Group members to royalty-free licensing for implementations. Future updates to this Recommendation may incorporate new features.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

EPUB 3 has been widely adopted as the format for digital books (ebooks), and this revision continuesto increase the format's capabilities to better support a wider range of publication requirements,including complex layouts, rich media and interactivity, and global typography features. Theexpectation is that publishers will utilize the EPUB 3 format for a broad range of content,including books, magazines, and educational, professional, and scientific publications.

These specifications represent the formal list recognized as belonging to EPUB 3 and that containfunctionality normatively referenced as part of the standard. The development of extensionspecifications periodically adds new functionality to EPUB publications. Features and functionalitydefined outside of core revisions to the standard, while not formally recognized in thisspecification, are nonetheless available for EPUB creators and reading system developers touse.

An EPUB publication is, in its most basic sense, a bundle of resources with instructions on how torender those resources to present the content in a logical order. The types of resources that areallowed in EPUB publication, as well as restrictions on their use, are defined in 3. Publication resources.

A ZIP-based archive with the file extension .epub bundles the EPUB publication'sresources for distribution. As conformant ZIP archives, EPUB publications can be unzipped by manysoftware programs, simplifying both their production and consumption.

The container format not only provides a means of determining that the zipped content represents anEPUB publication (the mimetype file), but also provides a universally named directoryof non-normative resources (/META-INF). Key among these resources is thecontainer.xml file, which directs reading systems to the available package documents. Refer to 4. Open Container Format (OCF) for more information about the container format.

3a8082e126