Summary

Set the base direction for metadata in the package document to ensure that it is rendered correctly.

Techniques

Examples

Example 1 — Declaring the default base direction
<package … xml:lang="he" dir="rtl">
   …
</package>
Example 2 — Overriding the default base direction
<package … xml:lang="ar" dir="rtl">
   <metadata>
      …
      <dc:subject dir="ltr">POETRY / Middle Eastern</dc:subject>
      …
   </metadata>
   …
</package>

Frequently Asked Questions

Can I set the language of the text instead?

No. The language declaration does not affect the display directionality. Setting the language is important for text-to-speech rendering.

Why do I need to declare a default left-to-right base direction in EPUB 3 but not HTML?

HTML defaults to left-to-right in the absence of a dir attribute.

EPUB 3 did not define the default directionality for package document metadata prior to EPUB 3.3, or require support for both left-to-right and right-to-left text ranges, so reading systems often only support a single direction regardless of what is authored. Adding the dir attribute to set the default text direction, and to indicate changes on individual metadata elements may help with rendering in these older reading systems, but is not guaranteed. Regardless, it is recommended to set the attribute going forward to ensure the correct base direction is applied.

If a base direction is not specified, reading systems are expected to default to using the Unicode Bidi Algorithm to determine it. As there was initially no default base direction, one could not be added when the requirements for the attribute were improved. Too many publications were authored assuming their local base direction would be applied.

Why is the attribute labelled "under-implemented" in EPUB 3.3?

Most reading systems only support display of a single default text directionality, which leads to text in another direction being incorrectly displayed to users. Features like this typically have to be removed from W3C standards, but it is hoped the support situation will improve moving forward because of the attribute's importance for internationalization.

W3C allowed existing EPUB features that did not meet the minimum support threshold to be retained provided they offered essential functionality and were marked "under-implemented". The label will be removed in the future when support increases.

Explanation

It is important to set the base direction for text in the package document to help ensure that it is displayed properly by reading systems and read properly by assistive technologies.

Note

The dir attribute only affects text content in the metadata section; it does not affect how EPUB content documents are rendered. For information about setting the base direction in EPUB content documents, refer to the Knowledge Base's HTML Text Direction page.

There are three ways to set the base direction in the package document:

Globally

To set the base direction for all text content, set a dir attribute on the root package element.

<package … xml:lang="he" dir="rtl">

Note

EPUB 2 does not support the dir attribute in the package document, so this technique does not apply.

Per-element

To override the default base direction on the package element, add a dir attribute to each metadata element with a different base direction.

<dc:creator … xml:lang="ar" dir="rtl">…</dc:creator>

Note

EPUB 2 does not support the dir attribute in the package document, so this technique does not apply.

Inline

It is not possible to identify inline changes in the base direction in the package document. Although using markup to set the base direction is preferred, in these cases you can use Unicode control characters to identify the changes. For an introduction to the control characters and how to use them, refer to the W3C article How to use Unicode controls for bidi text.

Related Links