dictionaries.md

Dictionaries

Immersive currently supports two dictionary formats: Yomichan and Migaku. Both need to be configured slightly differently.

The first time a dictionary is accessed, it is imported, which can take some time. After that it is loaded into memory until the active mpv instance is closed. New instances of Immersive can load a cached version of the dictionary from disk which will take less time. By default, dictionaries are only loaded once they are used, however setting the script config option preload_dictionaries to yes/true will load all dictionaries every time mpv is started. This will cause Immersive (but not mpv) to be unresponsive for several seconds on startup.

Every dictionary has its own config section. Each one also has an exporter, which is responsible for turning its data into a format that is usable by Anki. Options that configure the exporter must be prefixed with export: in the config file, e.g. export:template. Exporters make heavy use of templates.

If desired, dictionaries can be divided into multiple groups (by giving each section a group entry) in order to limit which dictionaries are directly accessible during definition selection. The active dictionary group can be changed in the target/dictionary menu (Ctrl+A) at any time.

Common Options

• type: The type of the dictionary. Allowed values are yomichan and migaku.
• location: The location of the dictionary files. This needs to be an absolute path, so one starting with / on Unix or C:\/D:\/etc. on Windows.
• group: Which group the dictionary belongs to. The default value is default.
• preload: If set to yes/true, always preload this dictionary, regardless of the script setting preload_dictionaries. If set to no/false, never preload this dictionary. If unset (default), use the aforementioned script setting.
• exporter: The exporter used for generating the field template variable {{definitions}}. Currently only default is available for either dictionary type, which is also used if exporter is not set.
• quick_def_template: template used for rendering the definitions shown in mpv
• export:<exporter option>: config entries used by the exporter.
• transformations: Transformations to apply to the selected text when invoking lookup with Ctrl+⏎.
  See here for more details.

Yomichan

Yomichan dictionaries need to be unzipped into a directory first, which is then used as the value of location. For example, if you downloaded jmdict_english.zip from the Yomichan website and extracted it to a folder in your home directory, the location entry should look something like this: location=/home/<user name>/jmdict_english (Unix) or location=C:\Users\<user name>\jmdict_english (Windows), with jmdict_english being the folder that contains the file index.json and the term/tag banks of the dictionary.

The dictionary config entry insert_cjk_breaks inserts a soft line break after each of the following fullwidth characters before rendering the definition that is shown inside mpv: 。、，！？；：. This can be useful for monolingual Japanese dictionaries that have definitions which otherwise wouldn't fit on the screen.

quick_def_template for Yomichan has the following template variables:

Variable	Type	Description
quick_def_template
readings	list	all readings of the dictionary entry
variants	list	all variants of writing the word
definitions	list	all definitions of the entry

Its default value is:

{{readings:::・}}{{variants:【:】:・}}: {{definitions:::; }}

Exporter

The default Yomichan exporter can be configured with the following options:

• digits: Replacement digits for the definition number. The value should contain exactly ten characters. For example set this to ０１２３４５６７８９ if you want to use fullwidth digits. Unset by default, in which case regular ASCII numerals (0123456789) are used.
• reading_template: Template used for displaying each reading and its variants. Default:

{{reading}}{{variants:【:】:・}}

• definition_template: Template for each separate definition in an entry.

{{tags:<span style="font-size\: 0.8em">:</span><br>:, }}{{num}}. {{keywords:::; }}

• template: Template for the final exported entry.

{{readings[1]}}:{{readings[2:] (:):　}}<br>{{definitions:::<br>}}

• use_single_template: If set to yes/true, use single_template for rendering entries that only have a single definition. Enabled by default.
• single_template: Default:

{{readings[1]}}:{{readings[2:] (:):　}} {{keywords:::; }}

All defaults are set so that entries of the Yomichan version of JMdict are exported in a format somewhat similar to Jisho.org.

---

The Yomichan exporter works as follows:

1. Group all variants of the word by reading. These will be rendered using reading_template.

2. Go through the definitions of the dictionary entry one by one. If the tags for the definition are different from those of the previous one, insert them into the template data. Render the definition using definition_template, with the tags (if present), the keywords and the number. If it is set, the digits of the number are taken from digits.

3. Render template using the readings and definitions from steps 1. and 2. Alternatively, if use_single_template is true, render single_template using the readings and the keywords from the only definition. The result of either of these is what will be exported to Anki.

Template overview:

Variable	Type	Description
reading_template
reading	single	the reading itself; usually hiragana but sometimes katakana
variants	list	all variants of writing the word with this reading
definition_template
tags	list	all tags for the dictionary entry
num	single	the number of the definition, with the digits taken from digits
keywords	list	the keywords for the definition
template
readings	list	all readings as generated from reading_template
definitions	list	all definitions as generated from definition_template
single_template
readings	list	same as for template
keywords	list	keywords of the single definition

Migaku

For Migaku dictionaries location is simply the path of the dictionary's JSON file, so something like this: location=/home/<user name>/Migaku_Dictionary.json (Unix) or location=C:\Users\<user name>\Migaku_Dictionary.json (Windows).

quick_def_template for Migaku has the following template variables:

Variable	Type	Description
quick_def_template
terms	list	all terms associated with the definition
altterms	list	alternative versions of the above terms
definitions	list	all definitions of the entry

Its default value is:

{{definitions}}

Exporter

The Migaku format is much simpler than Yomichan's, and so is its exporter. It uses the template provided in the config option export:template directly on the dictionary data.

Variable	Type	Description
template
terms	list	terms associated with the definition
altterms	list	alternative versions of the above terms
definition	single	the definition itself; it should already be in an Anki-friendly format
pronunciations	list	pronunciations associated with the definition
positions	list	parts of speech associated with the definition
examples	list	example sentences

All list entries aside from terms (and possibly altterms) will most likely only contain a single item.

The default value of export:template is:

{{terms[1]}}{{terms[2:] (:):, }}:<br>
{{altterms::<br>:, }}{{pronunciations::<br>:, }}{{positions::<br>:, }}
{{definition}}
{{examples:::, }}