Ruby Styling

Japanese

Mono ruby is typically used to represent pronunciation of Japanese kanji characters. Each ideographic base character is mapped in markup to an annotation that indicates how to pronounce it (usually using hiragana).

As you can see in the following example, the annotations don't overlap adjacent kanji characters, and they are normally centred relative to the base character (in Japanese this is called nakatsuke). Lines can break between the base characters.

If the annotation doesn't fit over the base character you can expect one of the following things to happen.

1. If the character alongside is a kanji character, the base characters will be spaced a little wider so that the ruby text doesn't overlap.
2. If the character alongside is punctuation or kana, the annotation will overlap it up to a certain point.
3. If the base character is next to the line start or end, a little extra space will be added alongside the base character so that the annotation doesn't stick into the margin.

This behaviour is currently browser dependent, rather than specified using CSS.

A jukuji annotation occurs where a sequence of base characters has a different pronunciation from what you would expect by looking at the individual base characters, eg. 田舎 (pronounced いなか). Because the kana don't map to individual base characters, you will need to use group ruby: a single annotation is mapped in markup to a range of base characters. The kana annotation is normally spread across the base text evenly, with a little extra space at either end. If the annotation is in the Latin script, however, it is normally centred on the base text. Base characters in group ruby are not split across line breaks.

Jukugo ruby (note that this is a different term from jukuji!) is a term used to describe special treatment of annotations for compound nouns (jukugo in Japanese). Essentially the annotations for compound nouns can be spread across all of the base characters in the word, like group ruby, but a word can still be split at the end of a line, like mono ruby. Furthermore, the distribution of the annotations for a word may follow detailed rules with regards to allowable overlaps, so that they are not necessarily equally spaced as per group ruby. See some examples.

Sometimes ruby annotations appear on opposite sides of a base character at the same time. In such cases, the top/right annotation is typically phonetic and uses mono ruby, and the bottom/left annotation is most likely group ruby and provides additional information about the base text.

Annotations and base text may be aligned at the start in vertical text, but are usually centred on the base in horizontal text.

The sections lower down this page indicate how you can change some of these basic styles.

Simplified Chinese

In Mainland China phonetic annotations normally consist of pinyin transcriptions, which are written in the Latin script. Content annotated with pinyin is usually only set horizontally. This is fortunate since Latin text would be set sideways in vertical text, making it harder to read.

There are two common approaches to phonetic annotation: character based and word based.

Character based annotations are common in text used for Chinese children, whereas word based annotations are often found in texts for those learning the Chinese language.

For character-based phonetic annotations, you will need to use markup to map each ideographic base character to an annotation which indicates the pronunciation. This is mono ruby. The annotations usually appear above the base text.

Word based phonetic annotations use group ruby, associating one annotation with more than one base character, and forbidding line breaks inside the annotation. Note how the top line in fig_chinese_group_ruby no longer breaks between the two parts of the word lizhi.

In both of these examples, the annotations are centred above the base text.

Annotations representing meaning or commentaries are common in light novels and translated works, and tend to describe phrases or words. They may contain casing, punctuation, and spaces, and may contain Chinese text explaining Latin base text, or vice versa, and they may appear on the opposite side of the base to phonetic annotations. Sometimes phonetic annotations are also placed below/left of the base.

As for the Japanese section above, if the annotation doesn't fit over the base character you can expect one of the following things to happen.

1. Since the annotations are often long, compared to the width of the Han base character, care may need to be taken to ensure that long pinyin annotations don't run into each other. To accomodate this, the tracking of the base text is often increased, to provide additional room. Occasionally, the size of the annotation text may be reduced. There may be some cases where annotations slightly overlap adjacent bases, but only while preserving a minimum space between annotations.
2. If the annotation is longer than the base and is next to the line start or end, both the annotation and the base text can be aligned with line head or end. A little extra space will be added on the other side of the base character so that the annotation fits.
3. The syllabic nature of the script makes it fairly easy in most cases to spot the start and end of an annotation, but when adjacent annotations are longer than the base, they should ideally be separated by about a ¼em or ½em space.

In some cases, care may need to be taken to ensure that long pinyin annotations don't run into each other. This can be achieved by increasing the tracking of the hanzi characters or by reducing the size of the annotation text.

Traditional Chinese

In Traditional Chinese, bopomofo (zhùyīn fúhào) ruby nearly always appears to the right of the base character, whether the text is set horizontally or vertically. Furthermore, the bopomofo annotation is always set vertically and the tone marks (apart from the light tone) are displayed in an additional column to the right of the bopomofo characters. The tones are not combining marks, and the vertical position of the tone mark depends on the arrangement of the phonetic symbols in the previous column.

Find more information about Bopomofo usage in Traditional Chinese.

Positioning ruby text 'over' the base

By 'over' we mean above horizontal text and to the right of vertical text.

This is the default behavior, and you can expect browsers to produce this without CSS.

If you need to place the ruby explicitly in this position, use:

ruby { ruby-position: over; }

Does it work? This works well because this is the default rendering for ruby.

Positioning ruby text 'under' the base

To position the ruby text below horizontal base text or to the left of vertical text, use ruby-position: under.

This position is often used in Japanese for semantic information (as opposed to phonetic labelling). It is also used sometimes for pinyin annotations in Chinese. Here is an example from the moedict dictionary.

To produce this effect, use:

ruby { ruby-position: under; }

Positioning bopomofo ruby

In Traditional Chinese, bopomofo (zhùyīn fúhào) ruby appears to the right of the base character, whether the text is set horizontally or vertically. Furthermore, the bopomofo annotation is always set vertically and the tone marks (apart from the light tone) are displayed in an additional column to the right of the bopomofo characters.

How to do it. Your CSS has to indicate that this will be bopomofo ruby, so that the annotation doesn't appear 'over' or 'under' the base text. To do that, you need the inter-character value of ruby-position.

The vertical placement for the bopomofo and the relative position of the tone characters within the invisible column to the right of the Han base character rely on the browser, or possibly font information. You don't need to specify anything more in CSS.

ruby { ruby-position: inter-character; }

Does it work? No, no browser engine currently supports rendering of bopomofo ruby. Very simple annotations can look ok in vertical text, because of the default vertical layout, but as soon as tone marks are added things look a mess.

Positioning double-sided ruby

Occasionally, it is necessary to associate more than one annotation with the same base text. In this case, you need to specify which annotation goes where.

This is complicated a little by the fact that there are two possible ways to create markup for double-sided ruby (see the Ruby Markup article for more details).

How to do it. If you use the 'tabular' model of markup, the styling is reasonably straightforward and involves setting ruby-position on the appropriate rtc element. Given markup such as the following:

<ruby>
<rb>東</rb><rb>南</rb>
<rt>とう</rt><rt>なん</rt>
<rtc><rt>tou</rt><rt>nan</rt></rtc>
</ruby>の方角

you could use CSS like this:

ruby { ruby-position: over; }
rtc { ruby-position: under; }

If you use nested markup, and you have markup such as the following:

<ruby><ruby>東<rt>とう</ruby><rt>tou<rb><ruby>南<rt>なん</ruby><rt>nan</ruby>の方角

you could use CSS like this:

ruby { ruby-position: under; }

ruby ruby { ruby-position: over; }

Aligning to one edge

This kind of alignment is mostly used for vertical Japanese text. (Horizontal Japanese text more often uses centering.)

Note that, currently, applying this setting doesn't automatically handle certain requirements that may arise with regards to overflow and interaction with line edges in traditional printed text.

How to do it. If you want to align the edges of the annotation and the base, you can use the start value of ruby-align. (An older version of the Ruby CSS spec also included an end value, but that has been removed from the current version of the spec.)

ruby { ruby-align: start; }

Does it work? All browser engines now support this value.

Centering shorter items of text

How to do it. Instead of aligning with an edge, if you want the shorter text, whether it is the ruby base or the ruby text, to be centered with the characters set solid, it will hardly come as a surprise to learn that you just need to set the value of ruby-align to center.

ruby { ruby-align: center; }

Does it work? All browser engines now support this value.

Applying justification to shorter items of text in group ruby

This section is applicable for group ruby, ie. when both the base and the annotation contain multiple characters.

If you want to use up redundant space by stretching the shorter text, be it the annotation or the base, you have two choices: you can justify the shorter text from edge to edge of the longer one (space-between), or justify across a space that is slightly smaller than the full width available (space-around). Note, however, that the justification outcome differs according to what scripts are involved.

The default setting is space-between.

ruby { ruby-align: space-between; }

ruby { ruby-align: space-around; }

ruby { ruby-align: space-between; }

Working with jukugo ruby

The CSS Ruby specification describes a method of handling jukugo ruby using the ruby-merge property. This allows you to indicate, through styling, whether the annotations associated with a compound noun in Japanese should be applied like mono ruby, or spread across the whole word like group ruby. In the latter case, however, a line can be broken inside a compound noun, so it differs slightly from the normal group ruby in a way that jukugo handling typically works in Japanese.

In the latter case, the browser could specify more detailed rules about how to align the annotations across the compound bases. This allows rules of (internal) overlapping to be more fluid in jukugo ruby than in mono ruby.

Unfortunately, at the time of writing, the ruby-merge property is not supported by any of the major browser engines, so for now we will omit a description of how this works.

Overlapping characters that are outside the ruby element

Overlapping of annotations and ruby bases is handled by the ruby-merge property. To control the overlap of long annotations relative to the characters alongside the base(s) you can use the ruby-overhang property.

How to do it. Set ruby-overhang to auto to enable the overhang. The amount of overhang is determined by the browser. To prevent overhang, set the value to none.

In the example below, the red lines were added as a visual aid.

ruby { ruby-overhang: auto; }

Does it work? This is a mixed bag. Blink browsers support an overhang by default — the CSS is not needed. However, ruby-overhang: none; has no effect, so it appears that Blink doesn't support the CSS itself.

WebKit browsers also support an overhang by default, but they do support ruby-overhang: none;, pushing the adjacent text apart so that there is no overhang.

Gecko browsers, which normally have good support for ruby styling, do not support overhang — neither by default, nor by CSS styling.

Note that no browser produces overlap if the alignment of ruby text is set to space-between.

Working with rp markup

If you use rp markup to specify what characters to use as delimiters and where to place them, you need to render the annotation inline and make the delimiters (which are invisible by default) visible.

You could use the following CSS, which changes the display value for the rt element and sets the font size to be the same as the base text (overriding the default size for the rt element set by the browser).

rt { display: inline; font: inherit; }
rp { display: inline; }

The rest of this section looks at how you can use CSS if your content doesn't have rp markup.

Working with interleaved markup

If you are quite happy for annotations to appear immediately after the base character(s) they are attached to, your content may be using the interleaved approach to ruby markup, and the expected outcome would be like this.

`

In addition to making the rt content display appropriately inline (as mentioned earlier), you will also need to surround each annotation with something, to set it off from the base text. Here we use the before and after pseudo-elements to surround it with parentheses.

The markup for the example is:

<ruby><rb>水<rt>みず<rb>芝<rt>し<rb>居<rt>ばい</ruby>

The CSS is:

rt { display: inline; font: inherit; }
rt::before { content: '（'; }
rt::after { content: '）'; }

Working with tabular markup

If you want all the annotations for a given word to follow that word, grouped together as shown here, your content will use the tabular markup approach. This approach generally provides a more useful outcome than that produced by interleaved markup.

The markup for the example is:

<ruby><rb>水<rb>芝<rb>居<rt>みず<rt>し<rt>ばいばい</ruby>

This markup model supports double-sided ruby using the rtc tag (see Ruby Markup).

Producing inline annotations in this case is a little more complicated if you're not using rp markup. The following CSS should work whether you use the rtc tag or not.

rt { display: inline; font: inherit; }

/* Parens around <rtc> */ 
rtc::before { content: "（"; } rtc::after  { content: "）"; } 

/* Parens before first <rt> not inside <rtc> */ 
rb  + rt::before, rtc + rt::before { content: "（"; } 

/* Parens after <rt> not inside <rtc> */
rb ~ rt:last-child::after, rt + rb::before  { content: "）"; } 
rt + rtc::before { content: "）（"; }