Ruby Annotations
Ruby annotations are small text annotations placed above or below the main text, commonly used for:
- Furigana in Japanese (reading aids above kanji)
- Pinyin in Chinese (romanization above characters)
- Romanization in Thai, Korean, and other scripts
Basic Example
The simplest way to render a word with ruby annotation:
import { SimpleRubyWord } from "@glotblocks/glost-react";
import { createJapaneseWord } from "@glotblocks/glost";
// Create a Japanese word with furigana
const word = createJapaneseWord({
text: "漢字",
transcription: {
furigana: { text: "かんじ", system: "furigana" }
},
translation: "kanji (Chinese characters)"
});
function FuriganaExample() {
return (
<SimpleRubyWord
word={word}
transcriptionSystem="furigana"
rubyPosition="over"
/>
);
}This renders:
かんじ
漢字Ruby Position
The rubyPosition prop controls where annotations appear:
| Position | Description | Common Use |
|---|---|---|
"over" | Above the text | Japanese furigana, Chinese pinyin |
"under" | Below the text | Thai romanization, Korean romanization |
Japanese (Over)
<SimpleRubyWord
word={japaneseWord}
transcriptionSystem="furigana"
rubyPosition="over"
/>Thai (Under)
import { createThaiWord } from "@glotblocks/glost";
const thaiWord = createThaiWord({
text: "สวัสดี",
transcription: {
"paiboon+": { text: "sà-wàt-dee", system: "paiboon+" }
},
translation: "hello"
});
<SimpleRubyWord
word={thaiWord}
transcriptionSystem="paiboon+"
rubyPosition="under"
/>Advanced: RubyWord Component
For full control over styling, use the RubyWord component with render props:
import { RubyWord } from "@glotblocks/glost-react";
function StyledFurigana({ word }) {
return (
<RubyWord
word={word}
displayLevel={2}
transcriptionSystem="furigana"
renderText={(text) => (
<span className="text-3xl font-serif">{text}</span>
)}
renderRuby={(transcription) => (
<rt className="text-sm text-red-600 font-sans">
{transcription}
</rt>
)}
/>
);
}Language Strategies
For language-specific behavior (like hiding furigana for hiragana-only words), use a language strategy:
import { RubyWord, containsKanji } from "@glotblocks/glost-react";
import { getWordText } from "@glotblocks/glost";
const japaneseStrategy = {
shouldShowTranscription: (word, system) => {
// Only show furigana if the word contains kanji
if (system === "furigana") {
return containsKanji(getWordText(word));
}
return true;
},
getRubyPosition: () => "over",
};
<RubyWord
word={word}
displayLevel={2}
transcriptionSystem="furigana"
languageStrategy={japaneseStrategy}
/>Creating Words with Transcription
Japanese
import { createJapaneseWord } from "@glotblocks/glost";
const word = createJapaneseWord({
text: "東京",
transcription: {
furigana: { text: "とうきょう", system: "furigana" },
romaji: { text: "tōkyō", system: "romaji" }
},
translation: "Tokyo"
});Chinese
import { createChineseWord } from "@glotblocks/glost";
const word = createChineseWord({
text: "你好",
transcription: {
pinyin: { text: "nǐ hǎo", system: "pinyin" }
},
translation: "hello"
});Thai
import { createThaiWord } from "@glotblocks/glost";
const word = createThaiWord({
text: "ขอบคุณ",
transcription: {
"paiboon+": { text: "kɔ̀ɔp-kun", system: "paiboon+" },
rtgs: { text: "khop khun", system: "rtgs" }
},
translation: "thank you"
});Korean
import { createKoreanWord } from "@glotblocks/glost";
const word = createKoreanWord({
text: "감사합니다",
transcription: {
rr: { text: "gamsahamnida", system: "rr" }
},
translation: "thank you"
});HTML Output
The components render standard HTML <ruby> elements:
<ruby style="ruby-position: over;">
<span>漢字</span>
<rt>かんじ</rt>
</ruby>This is semantic HTML that works in all modern browsers and degrades gracefully in older ones.
Styling Tips
CSS for Ruby
/* Control ruby text size */
rt {
font-size: 0.5em;
color: #666;
}
/* Adjust ruby spacing */
ruby {
ruby-align: center;
}
/* Style when ruby is below */
ruby[style*="under"] rt {
font-family: monospace;
}Tailwind CSS
<RubyWord
word={word}
displayLevel={2}
transcriptionSystem="furigana"
className="inline-block"
renderText={(text) => (
<span className="text-2xl text-gray-900 dark:text-gray-100">
{text}
</span>
)}
renderRuby={(rt) => (
<rt className="text-xs text-gray-500 dark:text-gray-400 font-mono">
{rt}
</rt>
)}
/>Next Steps
- Progressive Display - Add definitions and metadata
- Multi-Language - Handle multiple languages
- Custom Plugins - Add your own rendering logic
Last updated on