How to Translate EPUB Ruby Annotations Without Breaking the Base Text

Treat ruby as a relationship, not as a second line of ordinary text. In an EPUB, the visible base text and its short annotation are separate nodes joined by HTML markup. A translation workflow can preserve every character yet still damage the book by moving an <rt> annotation to the wrong word, translating a pronunciation that should remain unchanged, or flattening both layers into one sentence.

The safest workflow is to classify each ruby pair before translation, keep its markup intact, and test the finished EPUB in more than one reading system. The base text, the annotation, and their association are three separate things to verify.

The four decisions every ruby pair needs

Ruby commonly supplies pronunciation for Japanese kanji, but the annotation can also contain a gloss, a second reading, or other short information. The HTML ruby model distinguishes the base range from its annotation range; EPUB 3 packages that HTML-family content with styles, navigation, images, and other resources in one publication.

Use this decision table before changing either layer:

That is why “translate everything inside <ruby>” and “never translate <rt>” are both bad universal rules. The correct action depends on the annotation’s function.

A small fixture you can inspect before touching a real book

We created a text-only four-case ruby fixture and a corresponding review candidate. They contain original example sentences rather than third-party book text. The files are intentionally plain XHTML fragments so you can inspect the relationships without mistaking a successful ZIP package for a successful translation.

The fixture covers:

1. a Japanese place name with a pronunciation annotation;
2. a term with an English gloss rather than a reading;
3. one ruby element containing two base-and-reading units; and
4. rp fallback parentheses around an annotation.

The accompanying pair audit CSV records what changed and what must remain paired. The reproduction notes explain the limits: this is a markup inspection fixture, not evidence that BookTranslator or any named reading system passes every ruby case.

Case 1: retain a pronunciation while translating the sentence

<p>
  <ruby>高尾山<rt>たかおさん</rt></ruby
  >を歩いた。
</p>

The annotation is the Japanese reading of the base name. An English translation might retain the proper name as “Mount Takao,” but moving たかおさん after another noun would create a false association. The markup boundary must travel with the name even if the surrounding sentence is reordered.

Case 2: identify a gloss before deciding to translate it

<p>
  <ruby>校正<rt>proofreading</rt></ruby
  >は最後の工程ではない。
</p>

Here the annotation is already an English meaning aid, not kana pronunciation. A target edition may remove it, translate it, or replace it with a target-language gloss. The decision is editorial; treating every <rt> as immutable phonetic data would preserve the wrong thing.

Case 3: preserve pair boundaries inside grouped ruby

<p>
  <ruby>東<rt>とう</rt>京<rt>きょう</rt></ruby
  >の地図を開く。
</p>

The alternating sequence represents two annotation units. Joining both base characters into one translated label while leaving two independent readings can make the pairing ambiguous. If the translation no longer needs character-level readings, simplify the structure deliberately rather than letting a text transformer collapse it accidentally.

Case 4: keep fallback content out of the sentence

<p>
  <ruby>翻訳<rp>（</rp><rt>ほんやく</rt><rp>）</rp></ruby>を確認する。
</p>

The rp elements supply fallback punctuation for presentation when ruby layout is unavailable. The W3C description makes clear that this is presentational fallback content. It is not ordinary punctuation to move elsewhere in the translated sentence.

Separate extraction safety from translation quality

Before evaluating word choice, check whether the tool exposes ruby as structure or as a flattened text stream.

Run these three inspections on a copy of the EPUB:

1. DOM inspection: open representative XHTML files and count <ruby> and <rt> elements before and after processing.
2. Pair inspection: compare each base range with the annotation immediately associated with it. Counts alone will not catch a shifted pair.
3. Rendered inspection: open the EPUB in the reading systems you actually support, because valid markup and acceptable rendering are different gates.

A plain-text extractor may return 高尾山たかおさん or 高尾山（たかおさん）. That output can be useful for search, but it no longer proves which characters the reading annotates. Do not use flattened output as the sole source for a round-trip translation.

A markup-preserving translation workflow

1. Inventory ruby before translation

Unzip a working copy of the EPUB and search its content documents for <ruby, <rt, <rp, and any CSS rules beginning with ruby or rt. Record the files and counts, then inspect examples from different chapters.

Counts are only a smoke test. A file can retain ten <rt> elements while attaching all ten to the wrong bases.

2. Assign an annotation policy

Write a short policy for the edition:

• phonetic readings: retain, revise, or remove;
• glosses: translate, replace, or remove;
• proper names: source script, romanized form, target-language conventional form, or a documented combination;
• wordplay and exceptional readings: mandatory human review;
• fallback rp: preserve as markup unless the publication intentionally changes the fallback strategy.

The policy should be consistent across chapters. A glossary can help keep names and terms stable, but it cannot decide the literary function of an unusual reading.

3. Protect the element boundaries

The translation input should distinguish translatable base prose from protected markup and separately governed annotation text. If a workflow serializes the whole XHTML fragment into one string, verify that it can restore the original nesting after sentence reordering. If it cannot, translate smaller text nodes or use an EPUB-aware path.

Do not “repair” unfamiliar ruby syntax by deleting tags. HTML permits compact forms where base text appears directly inside <ruby> and annotations appear in <rt>. Normalize only with a standards-aware parser and a reviewed diff.

4. Reconcile language and typography

Check lang and xml:lang on the publication and content where applicable. A target-language paragraph can still contain a source-language reading that benefits from its own language declaration. Then inspect CSS such as ruby-position, vertical writing rules, font support, and line-height. Typography can fail even when the DOM pairing is correct.

For Chinese Zhuyin or vertically set Japanese text, the position of the annotation is part of the reading experience. The CSS Ruby Layout specification explains how presentation rules interact with the same semantic markup; do not replace semantic ruby with manually positioned spans just to imitate one screenshot.

5. Validate, render, and sample

Run an EPUB conformance checker, but treat a clean result as the beginning of visual QA, not its conclusion. Inspect at least:

• the first ruby occurrence in each structural pattern;
• long base text and long annotations;
• punctuation next to ruby;
• a line break near ruby;
• vertical writing if the book uses it;
• small-screen and large-screen rendering;
• search, text selection, and text-to-speech behavior if those matter to the edition.

The EPUB translation QA checklist covers the broader package, navigation, typography, image, and accessibility checks. The cross-reader test matrix separates file validity from behavior in specific reading systems.

The release checklist

Do not release a ruby-bearing translated EPUB until all of these are true:

1. Ruby patterns and chapter locations were inventoried from the source.
2. The edition has a written policy for readings, glosses, names, and exceptional ruby.
3. Base text and annotations were reviewed as separate content layers.
4. Every sampled annotation remains paired with the intended base range.
5. rp fallback content was not translated as ordinary prose.
6. Ruby-related language and CSS declarations were reviewed.
7. The EPUB passes the chosen conformance checks.
8. Representative patterns were rendered in each required reading system.
9. Wordplay, unusual readings, and target-language pronunciation decisions received human editorial review.

Where BookTranslator fits

If you have a DRM-free EPUB you are allowed to process, BookTranslator’s EPUB translator can provide a complete-file translation workflow. Ruby still needs the source inventory and post-translation checks above: this article does not claim that every ruby pattern, CSS combination, or reading system is preserved automatically.

Start with a representative chapter containing the hardest ruby patterns. Compare the source and output DOM, apply the pair audit, then open the result in the reading app you plan to use. For a bilingual edition, also decide how source and target blocks coexist using the bilingual EPUB structure guide.

The governing rule is simple: translate the intended content, preserve the base-to-annotation relationship, and treat rendering as a separate release gate.