Ruby filter
| Ruby filter | |
|---|---|
| Type | Filter |
| Set | N/A |
| Downloads | https://moodle.org/plugins/filter_ruby |
| Issues | https://github.com/adamjenkins/moodle-filter_ruby/issues |
| Discussion | https://moodle.org/plugins/filter_ruby |
| Maintainer(s) | Adam Jenkins (WiseCat) |
The Ruby (furigana) filter adds furigana (small kana readings, also called ruby) above Japanese kanji wherever Moodle shows text: pages, labels, forum posts, quiz questions, course summaries and anything else that goes through Moodle's filters. It is made for Japanese-language courses and Japanese schools, where students meet kanji they have not learned yet.
Each course can have its own readings, so a teacher can add furigana for exactly the words their students need.
Installation
Install the plugin from the Moodle plugins directory, or download the ZIP file and follow Installing plugins. The files go in the folder filter/ruby. The plugin supports Moodle 4.5 to 5.3.
Then go to Site administration > Plugins > Filters > Manage filters and set Ruby (furigana) to On, or to Off, but available so that courses can turn it on for themselves (see Managing filters).
The companion plugin Ruby (furigana) for TinyMCE adds editor buttons for typing furigana and for making word lists.
Where readings come from
Readings come from three places. The nearest one wins:
- Inline markup that the author types into the content.
- Word lists: a plain list of words and readings, for the site and for each category, course or activity.
- Tier dictionaries that come with the plugin, grouped by school level.
Where two entries could match at the same place, the longest one wins, so 今日 is read きょう, not 今 + 日.
Inline markup
Two forms are recognised anywhere in filtered text. Both take precedence over every word list, so an author can always set a reading in place.
| Form | Example | Result |
|---|---|---|
| Braces | {漢字|かんじ} |
漢字 with かんじ above it |
| Braces, empty reading | {金|} |
No reading here, even if a list has one |
| Aozora Bunko | ｜漢字《かんじ》 |
漢字 with かんじ above it |
| Aozora Bunko, empty reading | ｜金《》 |
No reading here |
The full-width bar ｜ at the start of the Aozora Bunko form is required. Without it, ordinary Japanese text that uses 《》 as quotation marks would be changed by mistake.
Typing <ruby> HTML directly is not a good alternative: Moodle's HTML cleaner removes ruby markup in the modern HTML form, in which the base text is not wrapped in an <rb> element. The inline forms above are plain text, so nothing removes them, and the filter adds the ruby markup itself after the text has been cleaned.
Word lists
A word list has one entry per line, written as word=reading:
漢字=かんじ 勉強=べんきょう # lines starting with # are comments, and blank lines are ignored 金=
- A later line beats an earlier one for the same word.
- An empty reading (
金=above) stops that word from getting a reading, for example when a tier dictionary adds one your students don't need. - A word can be at most 32 characters long.
- Lists are merged, not replaced: an activity's list is added to its course's, the course's to its category's, and the category's to the site's. A course only has to list the words it wants to add or change.
Tier dictionaries
There are four tier dictionaries, each turned on or off on its own:
| Tier | Covers |
|---|---|
| Elementary school words | Words whose hardest kanji is taught in grades 1 to 6 |
| Junior high school words | Words whose hardest kanji is taught in junior high school |
| Senior high school words | Words beyond the junior high school list, including name kanji |
| University and rare words | Words with the rarest kanji, outside the everyday-use list |
Turning on a tier means "add readings to words at this level", not "students already know this level". The tiers are independent on purpose: a course that reads academic Japanese can add readings to university-level words and leave elementary words plain. All four are off by default.
Together the four dictionaries hold about 9,700 readings of words and kanji runs, and 3,200 single-kanji readings. They are made from the JMdict and KANJIDIC2 dictionaries.
Display modes
| Mode | What readers see |
|---|---|
| Always show, on every occurrence (default) | Every matched word has its reading, every time. |
| Show on the first occurrence of each word only | A word has its reading the first time it appears on the page, and is plain after that. |
| Show on hover | Readings are hidden until the reader points at the word with the mouse. Keyboard and touch-screen users cannot show them, so use the reader toggle for them. |
| Reader toggle (button) | Readings are hidden until the reader clicks the Furigana button. Moodle remembers each reader's choice. |
Settings
Site settings
In Site administration > Plugins > Filters > Ruby (furigana):
- Word list: the site-wide word list.
- Tier dictionaries: Elementary school words, Junior high school words, Senior high school words and University and rare words (all off by default).
- Display mode: see Display modes.
- Single-kanji fallback (off by default): when no word matches, give a single kanji its most common reading. Keep this off for most courses: a single kanji read out of context often gets the wrong reading, and wrong furigana teaches a wrong reading. With the fallback off, the filter stays silent where it is not sure. A single kanji that you put in a word list yourself always gets its reading.
The site settings page also shows the licence of the dictionary data.
Course settings
A teacher who can manage the course's filters (the moodle/filter:manage capability, which editing teachers have by default) can give the course its own readings without changing anything for the rest of the site:
- Open the course.
- Go to More > Filters.
- In the Ruby (furigana) row, click Settings.
This page has the same settings as the site settings. Each one can be Site default, or a value for this course. Word lists are merged with the lists above, and the other settings are inherited from the level above when they are left at Site default (activity, then course, then category, then site). Activities and categories have the same page.
When you save a course word list, Moodle checks it. A missing =, an empty word or a word that is too long is an error and blocks the save. A reading that is not written in kana is only a warning, shown after the save.
Limitations
- No inflection handling. Matching is exact: a list entry 忘れる does not match 忘れました or 忘れない. To help with this, the tier dictionaries also contain the kanji part of a word (忘 → わす), so inflected forms still get a reading on the kanji. Kanji whose reading depends on the word, such as 行 (いく or おこなう), 出, 生 and 難, are left out on purpose.
- Readings can be missing. The dictionaries are trimmed by frequency and leave out ambiguous readings. Use course word lists and inline markup for proper nouns, rare words and anything else they miss.
- Text in code samples, preformatted text, existing ruby and areas marked nolink is not changed.
- Moodle does not cache filtered text, so the filter runs each time a page is shown. The word lists themselves are cached.
Capabilities
The plugin adds no capabilities. Changing a course's or activity's filter settings needs the core capability moodle/filter:manage.
Privacy
The plugin stores one user preference: whether a reader has turned furigana on in the Reader toggle (button) mode. Word lists are site and course settings, not personal data. The plugin implements the Privacy API, so the preference is included in data exports, and Moodle deletes it with the user's other preferences. See Data privacy.
Word lists are stored in Moodle's own filter settings, so course backup and restore carry them with the course.
Credits
The tier dictionaries are made from the JMdict/EDICT and KANJIDIC2 files. These files are the property of the Electronic Dictionary Research and Development Group and are used under the Group's licence, Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0).
