Export 6 min read

How to Add Language Metadata to an EPUB

Setting dc:language does not set the language of your content. The spec says resources do not inherit it, so every document needs its own lang attribute.

Language metadata in an EPUB has two separate parts, and doing only the first is the commonest mistake in the format.

dc:language in the package document declares the publication's language for catalogues and stores. A lang and xml:lang attribute on every content document declares the language for rendering, which is what a screen reader or a braille display actually uses.

The second does not follow from the first. The specification says so directly.

The Trap, in the Spec's Own Words

EPUB 3.3 attaches a note to its dc:language definition that most tutorials never mention:

"Publication resources do not inherit their language from the dc:language element(s). EPUB creators must set the language of a resource using the intrinsic methods of the format."

The DAISY Consortium, which maintains accessible publishing guidance, puts the consequence plainly: the package document's language "is not used when rendering the content", and "To ensure the proper language for braille rendering or TTS playback, the language must be set in each document."

So a French novel whose package document says fr but whose chapters carry no language attribute will be read aloud by an English voice. The metadata is correct and the book is unusable.

Part One: The Package Document

dc:language is one of the four required metadata items in an EPUB, alongside title, identifier and modified timestamp. Its cardinality is one or more.

The value must be a well-formed BCP 47 language tag, defined by RFC 5646. In practice that means:

  • A primary subtag: en, fr, de, ja
  • Optionally a region: en-US, en-GB, fr-CA, pt-BR
  • Optionally a script where it disambiguates: zh-Hans, zh-Hant

Use a region subtag only when it means something. en is correct and sufficient for most books; en-GB is worth setting if spelling or conventions matter to a cataloguer.

If your book is genuinely multilingual you may add more than one element, and the spec defines the precedence: "reading systems will treat the first dc:language element in document order as the primary language of the EPUB publication."

A separate mechanism, easily confused with this one, is xml:lang in the package document itself. That tags the language of the metadata strings rather than the book, so a French author's name inside an English book's metadata would be marked with it. It is not a substitute for either part above.

Part Two: Every Content Document

Each XHTML file needs the language on its root element, and it needs both attributes:

<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">

Both are required because the file is XML but processed as HTML. xml:lang serves the XML processor, lang serves the HTML one. Setting only one works in some reading systems and fails in others.

Within a document, inheritance does work. DAISY notes that "by setting the attribute on the root element you automatically declare the language for all the elements and text in the document", so you do not need to repeat it per paragraph.

This satisfies WCAG 2.2 success criterion 3.1.1, Language of Page, at Level A: "The default human language of each web page can be programmatically determined."

Part Three: Passages in Another Language

A phrase in a different language should carry its own tag:

<span xml:lang="fr" lang="fr">rue Saint-André-des-Arts</span>

This is WCAG 2.2 success criterion 3.1.2, Language of Parts, at Level AA. Its exceptions are doing real work and worth quoting:

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

So a French street name in dialogue should be tagged. A word like "rendezvous", naturalised into English, should not. Tagging every foreign-derived word makes text-to-speech worse, not better, by forcing accent switches on words the language has absorbed.

Why It Matters More Than It Looks

Language is, in practice, the only pronunciation control that works.

DAISY notes that the finer-grained tools exist but are unsupported: SSML, PLS lexicons and CSS Speech are all defined, and "none of these technologies is supported in reading systems". That leaves the language attribute as the single lever that reliably changes how a book is spoken.

It also drives braille translation, which is language-specific in its contractions, and hyphenation, since a reading system picks its dictionary from the nearest declared language.

This matters commercially as well as ethically. EPUB Accessibility 1.1 requires conformance to WCAG, which makes 3.1.1 mandatory at Level A. See European EPUB requirements.

What Deckle Does

Deckle handles all three parts correctly, which is worth knowing because many tools do not.

The package document gets dc:language from the language you set in the export metadata.

Every generated content page carries xml:lang taken from that same book language, rather than a hardcoded value.

Inline language spans emit both attributes. Where you mark a passage as being in another language, Deckle outputs <span xml:lang="fr-FR" lang="fr-FR">, which is exactly the pattern above. There is a test in the codebase asserting that a language of "none" is never emitted as an attribute, so unmarked text stays unmarked rather than being wrongly labelled.

One known exception: the full-bleed image page template hardcodes xml:lang="en". If your book is not in English and uses a full-page image, that single page declares the wrong language. It carries no readable text, so the practical impact is small, but it is a real inconsistency rather than a design decision.

For the rest of the metadata picture, see ebook metadata explained, and for what else accessibility requires, accessible EPUB structure and reading order.

Common Mistakes

  • Setting only dc:language. The spec states resources do not inherit from it.
  • Setting only lang or only xml:lang. Both are needed on XHTML content documents.
  • Tagging naturalised loanwords. WCAG's exceptions exclude them, and tagging them degrades speech.
  • Using a region subtag by default. en is fine unless the region carries meaning.
  • Assuming SSML will fix pronunciation. DAISY says no reading system supports it.
  • Leaving translated editions on the original language tag. A common copy-paste error when reusing a project.

FAQ

Q: Is dc:language required? A: Yes, it is one of the four mandatory metadata items in an EPUB.

Q: What format is the value? A: A BCP 47 tag, defined by RFC 5646. en, fr, zh-Hans are all valid.

Q: Do I need lang on every paragraph? A: No. Setting it on the root element covers the whole document by inheritance.

Q: What about a bilingual book? A: Multiple dc:language elements are allowed, and the first is treated as primary. Tag each passage in the content.

Q: Does this affect how the book is spoken aloud? A: Yes, and it is effectively the only control that does, since SSML and lexicons are unsupported in practice.