Adding Furigana to Word Documents is a Nightmare

Adding furigana to a Word document seemed like a simple extension to EZFurigana. Furigana are small pronunciation guides for Japanese kanji, and I, despite being fluent in Japanese, still encounter kanji I can't read immediately. Doing it manually in Microsoft Word is manageable for a few words, but on longer documents, it becomes tedious.

I wanted EZFurigana to automatically add furigana to DOCX documents. My initial plan was to open the DOCX, find the Japanese text, generate the readings, and save the file. However, when I examined a DOCX file, I quickly learned it's a complex nightmare. It's not a simple text file; it's a ZIP package containing XML files, styles, images, and fonts scattered throughout.

The main body content is stored in document.xml, but it's not as straightforward as one might expect. Word documents can contain tables, hyperlinks, images, and various structures that are difficult to understand and recreate accurately. EZFurigana modifies the existing Word document while preserving the rest of the file. However, the process gets more complicated, as a single word can span multiple elements due to formatting changes, hyperlinks, tables, and images.

EZFurigana keeps track of text pieces and only changes safe parts of the XML, leaving the rest intact. Microsoft Word has built-in support for ruby annotations, which are similar to furigana. EZFurigana had to convert the annotations into this format while preserving the original text and reading. Once the DOCX with furigana is ready, it needs to be previewed in a browser.

However, browsers don't understand Word documents natively, so a valid DOCX still needs to be reconstructed with margins, fonts, spacing, and the secret glue that makes it look like Word again. While LibreOffice offers a decent preview, its handling of East Asian typography is not perfect, especially with furigana. The final solution involves uploading the DOCX, generating furigana, rewriting safe parts of the XML, rendering a preview with LibreOffice, and then downloading the modified DOCX.

Although the feature has its challenges, it's better to miss a few annotations than to destroy a document. The author hopes the DOCX feature in EZFurigana is a worthwhile addition and encourages feedback from users who encounter issues with their Word documents.