Authoring HTML: Handling Right-to-left Scripts

Attributes in HTML 4.01 that have values of right and left are align and clear.

The align attribute is used with the elements hr, div, h1-h6, p, table, caption, col, colgroup, tbody, table, td, tfoot, th, thead and tr. The use of this attribute is deprecated in HTML 4.01 for all but the table-related elements.

clear is used with br, but is also deprecated in HTML 4.01.

For example, to right-align an image, such as the icons in this document that return you to the table of contents, you could use the CSS rule in Example 6:

You can achieve the same effect as the clear attribute using the CSS shown in Example 7. This rule ensures that the h2 element has no floated content to its left.

These style rules would, of course, need to be changed in the style sheet for a version of the page that was localized into a right-to-left script, but it should be much easier to do that than to go through all the HTML content.

(Note that this technique does not refer to the values rtl and ltr that are used with the dir attribute.)

Values of right and left in attributes need to be reversed when translating the document into a language using a right-to-left script.

Whether you are authoring a LTR document or a RTL document, it can save a lot of time and risk to use CSS style sheets to achieve the same effect, since one small change in a CSS file can save the trouble of editing code in many HTML documents. (One should expect the style sheet to need conversion anyway as part of the translation process.)

Values of right and left need to be reversed when translating the document into a language using a script with a different direction. To reduce the effort and complexity of adapting the styles it is better to only use text-align where it is actually needed to override the current default alignment.

Often people apply it by default when it is not actually required. This overrides the default alignment derived from the base direction, and leads to more work when localizing a document - particularly if the document contains blocks of text in more than one direction. By default the dir attribute setting should produce the correct alignment.

Create and store your Hebrew content in logical order (ie. usually as you would pronounce it), not the order you expect to see it displayed.

You will need to use an appropriate character encoding. It is usually best to use an Unicode encoding, such as UTF-8. If, for some reason, you choose to serve your Hebrew page in an ISO encoding instead, then specify ISO-8859-8-I, not ISO-8859-8.

Visual ordering. Visual ordering of text was common for old user agents that didn't support the Unicode bidirectional algorithm. Text was stored in the source code in the same order you would expect to see it displayed. This also involved such things as disabling any line wrapping, explicit right-alignment of text in paragraphs/ table cells, and reverse-ordering of table columns when translating from English to a language using a bidi script. For example, if you want to add a few words in the middle of a paragraph, you would have to move text to and from every line that followed it in the paragraph (see the tutorial Creating HTML Pages in Arabic & Hebrew for an example).

Note, too, that if you have in-line markup, such as emphasis or link text, that spans more than one line, you will need to mark up the text runs on both lines separately. Again, adding text before such markup in a paragraph would mean that you have to carefully change this markup to reflect the new position of the text.

The result is very fragile code that is difficult to maintain. In addition, all the extra tags needed to manage the text would bloat your code and impact not only authoring time, but also bandwidth. Visually ordered bidirectional HTML does not conform to the HTML specification unless bdo markup is used.

Logical ordering. Using logical ordering, on the other hand, makes it almost trivial to create long paragraphs of flowing text that automatically wraps to the width of the block element. It also makes it much easier to address accessibility, using such things as screen readers.

Logically ordered text is stored in memory in the order in which it would normally be typed (and usually pronounced). The Unicode bidirectional algorithm is then applied by the browser to render the correct visual display.

Character encoding considerations. Certain character encodings are associated with visual vs. logical ordering of text. Text in a Unicode encoding, such as UTF-8, is always logical. Unicode is generally the best choice for a character encoding, but if you wish to use an ISO code page, you should read 6.2 Use bidi markup only when necessary.

It is usually best to use an Unicode encoding, such as UTF-8. If, for some reason, you choose to serve your Hebrew page in an ISO encoding instead, then declare the encoding to be ISO-8859-8-i, not ISO-8859-8, and create and store your Hebrew content in logical order, not the order you expect to see it displayed.

Certain character encodings are associated with visual vs. logical ordering of text. Text in a Unicode encoding, such as UTF-8, is always logical.

According to RFC1555 and RFC1556, there are special conventions for the use of charset parameter values to indicate bidirectional treatment in MIME mail, in particular to distinguish between visual, implicit, and explicit directionality. 'Visual' refers to the practice of storing Hebrew characters in presentation order, so that there is no reliance on reordering performed by the operating system or the display subsystem. 'Implicit' is also called logical ordering, and refers to an approach where all characters are stored in memory in the order in which they would normally be typed. Correct ordering for display is then done by a special algorithm (this is the preferred approach). 'Explicit' refers to the use of explicit markers in the text to indicate directional changes.

The charset parameter value ISO-8859-8 for Hebrew denotes visual ordering, ISO-8859-8-i denotes implicit bidirectionality, and ISO-8859-8-e denotes explicit directionality. (The latter is not supported by any common browser.)

HTML assumes by default that bidi data is stored in logical order, and that rendering agents will have to use the Unicode Bidirectional Algorithm to present the text in correct visual order. If the encoding is ISO-8859-8, the corresponding charset specification must be ISO-8859-8-i.

Explicit directional control is also possible with HTML, but cannot be expressed with ISO 8859-8, so "ISO-8859-8-e" should not be used.

Note, also, that ISO encodings don't include diacritics - if you want these, then use a logical encoding such as a Unicode encoding or Windows-1255.

By the way, contrary to what is said in RFC1555 and RFC1556, ISO-8859-6 (Arabic) does not imply visual ordering.

Just use the dir attribute when you need to indicate direction, and don't use CSS properties.

It is possible to express direction for a range of text using the CSS direction and unicode-bidi properties. Even when CSS is used, however, because directionality is an integral part of the document structure and needs to be persistent, you should always use dedicated markup to set the base direction for a document or chunk of information, or to indicate places in the text where the Unicode bidi algorithm is insufficient to achieve desired inline directionality.

The way in which a browser is expected to handle the dir attribute and its values is clearly defined in the HTML specification, so CSS is not needed. The CSS2 specification also recommends the use of markup for bidi text in HTML. In fact it goes as far as to say that conforming HTML user agents may ignore CSS bidi properties, since the HTML specification clearly defines the expected behavior of user agents with respect to the bidi markup.

Although XHTML uses XML syntax, it is usually served to browsers using the text/html MIME type, ie. the browser recognizes it and treats it as HTML. Therefore the same principle applies: use the markup, don't use CSS for direction.

See the article CSS vs. markup for bidi support for a fuller explanation.

Add the dir attribute to a block element where you want to change the base direction. Example 10 shows how you might mark up a blockquote element to render a left-aligned English quotation in a right-to-left page.

Do not try to achieve the same effect using CSS or Unicode control characters.

Note also that you should only use the dir attribute on block elements when you need to change the base direction from the current default (see 6.2 Use bidi markup only when necessary).

Tables are slightly different from other block elements. Using a dir attribute directly on a table tag will reorder the columns and contents as expected, but will not cause the table to move to the other side of the displayed page. If you want that to happen, you should put the table in a block element, such as div, and add the dir attribute to that, rather than put the attribute on the table element.

Apart from the fact that it can be difficult to manage Unicode control characters because they are invisible, they don't really work for managing base direction across block elements because of questions of scoping and inheritance.

CSS is not needed for bidi support in HTML, and it is best to rely on the dedicated markup that HTML provides, with all needed behavior built in (see 5.5 Don't use CSS styling for direction in HTML)

For more information see the tutorial Creating HTML Pages in Arabic & Hebrew.

Once you have established the appropriate base direction for the html element you will only need to apply bidi markup to another element if you want that element's base direction to be different from that currently in force.

The same principle applies for inline markup. Do not use inline bidi markup unless the Unicode bidi algorithm is insufficient on its own to produce the expected results.

The following Arabic example shows bad usage. None of the dir attributes are needed if dir="rtl" is added to the html element. Removing them will significantly simplify the document and reduce bandwidth requirements.

The block elements inherit their direction from that set on the html element, or the previous parent element where a change was made. The inline 'HTML' and 'CSS' words in Example 11 do not need markup because the bidi algorithm can produce the right result automatically.

Occasionally the Unicode bidirectional algorithm is not sufficient to correctly order certain inline sequences of bidirectional text. Alternatively, you may want to override the effects of the bidirectional algorithm for a part of the page. In these cases you can apply additional markup to produce the ordering you want. These scenarios are discussed in other techniques in this document.

Add the dir attribute to an element surrounding the embedded text. If there is no element surrounding the text, use a span element. Set the value of the dir attribute to either ltr or rtl, depending on the base direction of the embedded text, as shown in the examples below.

If it is not possible to use markup, eg. in the title element or attribute values, you will need to use Unicode control characters.

For examples and more detailed explanations see the discussion that follows.

This technique is useful where nested, inline text, such as a quotation, is bidirectional. At a simple level the Unicode bidirectional algorithm takes care of the reordering of inline text, but where nested text is bidirectional you need to set up an embedding level, ie. indicate a range of text for which a different base direction will be applied.

This can be done using markup around the relevant text, or by adding Unicode control characters to the text. It is recommended that markup be used in preference to control characters because the latter are difficult to manage well, given that they are invisible.

You need to be familiar with the concepts in the article What you need to know about the bidi algorithm and inline markup to understand this technique.

Using markup. Example 12 shows a sentence that, because we rely solely on the bidirectional algorithm, is incorrectly ordered, but that can be fixed with markup.

It is possible that the embedded text is not surrounded by markup, and you may therefore need to add it, but note that the quotation here was already surrounded by markup. A span was used in order to label the language of the quotation. This is likely to be a common occurrence. In addition to marking up for language, quotations may be marked up with such things as a span or q element for styling or semantic properties. Given that the boundary of the quotation is already clearly marked, adding the dir attribute is simple and quick.

Note also, by the way, that we placed the span element inside the quotation marks, since these are a part of the English text.

Using control characters. Where markup is not available, such as in a title attribute value or an option element, you will have to use Unicode control characters to demarcate the required range of text and assign a base direction to it.

To mark the beginning of the embedded section you use one of U+202B RIGHT-TO-LEFT EMBEDDING (RLE) or U+202A LEFT-TO-RIGHT EMBEDDING (LRE) to set the base direction. This corresponds to the markup <span dir="rtl"> or <span dir="ltr">, respectively. At the other end of the embedded section is U+202C POP DIRECTIONAL FORMATTING (PDF). This corresponds to </span> in markup terms.

These characters can be added as characters or as escapes. (But see the issues associated with escapes in the section Adding escapes to the content.)

Example 13 shows how.

If the directional run is surrounded by markup, you can simply add the dir attribute to the element surrounding it.

If not, rather than use the RLE/LRE plus PDF controls to create embedded text, place U+200F RIGHT-TO-LEFT MARK (RLM) or U+200E LEFT-TO-RIGHT MARK (LRM) alongside misplaced characters to produce the desired result.

The RLM/LRM characters can be added as either characters or as escapes. (But see the issues associated with escapes in the section Adding escapes to the content.)

For examples and more detailed explanations see the discussion that follows.

You need to be familiar with the concepts in the article What you need to know about the bidi algorithm and inline markup to understand this technique.

Weakly-typed or neutral characters between different directional runs take on the directionality of the base direction. This can be an issue if the character in question is part of, but on the edge of, a directional run which has a different direction from the current base direction.

You can deal with misplaced characters by either providing a different base direction, or by making sure the problematic character is followed by an appropriate strongly-typed character. Example 14 illustrates the problem and both of these solutions.

Although our base text for Example 14 was in Latin script, you are more likely to encounter this kind of problem in an Arabic paragraph that included English text followed by punctuation. In that case you would use U+200E LEFT-TO-RIGHT MARK (LRM) to address the problem. Here is an example.

Here is a slightly different looking example, that turns out to be the same problem. There is a major issue with this example because it is not obvious that a mistake has been made.

Similar results can be obtained for telephone numbers with certain separators.

If the base direction is right-to-left, place an RLM character (U+200F RIGHT-TO-LEFT MARK) between the directional runs to produce the desired result. Otherwise use a LRM mark (U+200E LEFT-TO-RIGHT MARK).

These characters can be added as characters or as escapes. (But see the issues associated with escapes in the section Adding escapes to the content.)

Note that the dir attribute is not appropriate to resolve this case.

This technique is relevant when you have a list or sequence of items in text that includes more than one adjacent items with the same directionality, but a directionality that is different to the current base direction.

It will be easiest to describe this using some examples.

Example 17 shows a case that occurs only rarely in English. Because of the likelihood of Latin text showing up in languages written with the Arabic or Hebrew scripts, this situation is more common when writing in those languages. Example 18 shows a typical case.

The same problem can occur when, say, a Persian sentence ends in an English word followed by a period, and then the next sentence starts with an English word. To avoid the two words being swapped around you need to put an RLM after the end of the first sentence.

This same issue also applies to sequences of items such as checkbox or radio button labels or other lists of items on a page. See Example 19 for an illustration.

There are a number of scenarios where you need to look out for this issue. For example, it is common to create navigation bars from items listed in a ul element that are then rendered as inline items using CSS display: inline. For this to work you will need to end relevant li content with a RLM or LRM (depending on the base direction of the context in which the items will be displayed).

The same applies to lists that are created at run time using scripting, such as that shown at the top left of the page in Example 20, where the language links are automatically generated based on information about which language versions are supported for that page. In this case, the same mechanism and labels are used as for left-to-right pages, so the script detects the language of this page as one that is written right-to-left, and then adds an RLM to all of the labels, whatever the language.

In HTML do not use the Unicode characters RLE, LRE, RLO, LRO and PDF where markup is available. To show the limits of embedded text with a different base direction, use the dir attribute, and to override the bidirectional algorithm use the bdo element.

On the other hand, attribute text or element text that allows no internal markup, such as the title, textarea and option elements, cannot support use of dir on a span or other element to label part of its content.

In these cases you need to use Unicode characters to do the job. The following table shows correspondences between markup and Unicode control codes:

These characters can be added as characters or as escapes. (But see the issues associated with escapes in the section Adding escapes to the content.)

The HTML 4 specification specifically warns against mixing the two approaches because of the increased likelihood of improper nesting. It also recommends the use of markup because it "offers a better guarantee of document structural integrity and alleviates some problems when editing bidirectional HTML text with a simple text editor". It does not proscribe the use of Unicode bidi formatting codes.

The joint Unicode Technical Report #20 and W3C Note, Unicode in XML and other Markup Languages goes further. It explicitly recommends that only the markup be used. It also recommends that the Unicode bidi formatting codes should be ignored if detected in a browser context, and replaced by appropriate markup when received in an editing context.

Of course, in attribute values or for the three elements listed above markup cannot be used, so the Unicode control characters are the only option available.

For further discussion, see the article Bidi formatting codes vs. markup in (X)HTML.

Put the Unicode characters RLE (U+202B) or LRE (U+202A) at the beginning, and PDF (U+202C) at the end of bidirectional text that you expect to be displayed in one of the following situations:

• as a tooltip
• in the page title
• on a JavaScript dialog box

These characters can be added as characters or as escapes. (But see the issues associated with escapes in the section Adding escapes to the content.)

Bidirectional text that is displayed in page titles, or JavaScript dialog boxes in a browser with a left-to-right locale is typically displayed with a base direction of left-to-right. This means that directional runs in these contexts are also ordered left-to-right. At the time of writing Internet Explorer and Firefox do respect the base direction of the content when displaying tooltips for title attributes, but other browsers do not.

Since markup is not effective in any of these situations, Unicode control characters can be used to establish the base direction as right-to-left. This produces the desired effect on most browsers.

For more information about handling of these situations in browsers and examples, follow the link to more information, below, and look at the test and results pages.

Remove all white space from before the end tag of an inline element that changes the base direction.

Spaces between directional runs may appear to collapse at the boundary of an embedding if there is a space just before the end tag of the inline element that surrounds the embedded text. Here is an example.

Although this seems paradoxical, that an extra space can cause a missing space, it is not a bug. For a detailed explanation of why this happens see the article Bidi space loss.

Whatever the base direction of the text you are authoring, always use U+0028 LEFT PARENTHESIS and U+0029 RIGHT PARENTHESIS (or their equivalents in non-Unicode but logical encodings) as the opening parenthesis and closing parenthesis, respectively. Ignore the actual names of these characters. Allow the rendering algorithms to choose the appropriate shape for you.

The same applies to the other mirrored characters.

Mirrored characters are used according to their Unicode semantics, rather than their actual displayed shape. There are a number of paired punctuation characters, but also some single characters. The shape of a mirrored character when displayed will automatically change according to the directional context.

It is unfortunate in this case that Unicode character names cannot be changed, otherwise these parentheses you see in Example 24 would have been named OPENING PARENTHESIS and CLOSING PARENTHESIS instead, to make their use clearer.

Surround the text with a bdo element. Set the value of the dir attribute on the bdo tag to either ltr or rtl, depending on the base direction of the surrounding text, as shown in the examples below.

If it is not possible to use markup, eg. in the title element or attribute values, you will need to use Unicode control characters.

For examples and more detailed explanations see the discussion that follows.

bdo stands for 'bidirectional override'. This inline element can be used to override the Unicode bidirectional algorithm, and just list all characters in the sequence they are stored in memory.

This is not often required, but it can be very useful to correctly display part numbers or to show how text is stored in memory.

This can be done using markup around the relevant text, or by adding Unicode control characters to the text. It is recommended that markup is used in preference to control characters because control characters create states with invisible boundaries, and are difficult to manage.

Using markup. Example 25 shows how to use bdo.

It is possible that the embedded text is not surrounded by markup, and you may need to add it, but note that the quotation here was already surrounded by markup. A span was used in order to label the language of the quotation. This is likely to be a common occurrence. In addition to marking up for language, quotations may be marked up with such things as a span or q element for styling or semantic properties. Given that the boundary of the quotation is already clearly marked, adding the dir attribute is simple and quick.

Note also, by the way, that we placed the span element inside the quotation marks, since these are a part of the English text.

Using control characters. Where markup is not available, such as in a title attribute value or an option element, you will have to use Unicode control characters to demarcate the required range of text and assign a base direction to it.

To mark the beginning of the embedded section you use one of U+202E RIGHT-TO-LEFT OVERRIDE (RLO) or U+202D LEFT-TO-RIGHT OVERRIDE (LRO) to set the base direction. This corresponds to the markup <bdo dir="rtl"> or <bdo dir="ltr">, respectively. At the other end of the embedded section is U+202C POP DIRECTIONAL FORMATTING (PDF). This corresponds to </bdo> in markup terms.

These characters can be added as characters or as escapes. (But see the issues associated with escapes in the section Adding escapes to the content.)