alex/yomichan
1
Fork 0
Code Releases Activity
1,570 Commits 1 Branch 0 Tags 84 MiB
JavaScript 82.4%
HTML 10.7%
CSS 6%
Handlebars 0.9%
fd17a0fccd
Go to file
sabs fd17a0fccd Remove Download check when resolving Audio data 
There is a bug (seemingly unreported) in Yomichan where an Anki card
will not contain any audio if the JapanesePod101 audio source trumps
a secondary audio source (e.g. JapanesePod101-alternate) where
the jpod101 source can't find the word requested.

For example, そして has an audio entry in the alternate source but not
the standard source.

(Alternatively, there may be a bug in the jpod101 audioUrlBuilder,
because I've only noticed this problem with hiragana-only expressions.
JPod101 may not host those on the same url scheme any more.  I'm not
sure how to fix that, though, and the bug I'm addressing here does
still persist).

The reason this happens is that audioGetFromUrl uses downloaded audio
to effectively check for a 404 (by examining the audio duration), but
that check doesn't happen when an Anki card is being created (i.e.
"download" is set, which I've changed to "willDownload" here).

This change removes that check, but retains the will-download intent
information to prevent attempts to download tts data, which AnkiConnect
cannot do. I've also added a short explanation as to why the download
check happens where it does.

I think the unused audio object will get garbage collected since it's
not referenced again, but I've explicitly unset it as well.
2019-11-09 20:58:09 -05:00
ext Remove Download check when resolving Audio data 2019-11-09 20:58:09 -05:00
resources Create SVG icons 2019-10-06 21:28:42 -04:00
tmpl Use HTML templates for anki fields 2019-11-09 14:31:13 -05:00
.gitattributes Force LF line endings for template files 2019-10-28 17:33:30 -04:00
.gitignore Zip deploy script 2016-05-18 16:39:27 -07:00
.gitmodules file management 2016-12-23 16:25:14 -08:00
build_tmpl_auto.sh File reorg 2016-05-08 12:01:43 -07:00
build_tmpl.sh adding docs for mozilla review 2017-02-26 15:35:11 -08:00
build_zip.sh updating license, distro script 2017-03-23 20:07:22 -07:00
LICENSE update license file 2019-04-28 11:47:01 -07:00
README.md Fix order of {screenshot} tag 2019-10-11 19:44:13 -04:00

README.md

Yomichan

Yomichan turns your web browser into a tool for building Japanese language literacy by helping you to decipher texts which would be otherwise too difficult tackle. This extension is similar to Rikaichan for Firefox and Rikaikun for Chrome, but it stands apart in its goal of being a all-encompassing learning tool as opposed to a mere browser-based dictionary.

Yomichan provides advanced features not available in other browser-based dictionaries:

  • Interactive popup definition window for displaying search results.
  • On-demand audio playback for select dictionary definitions.
  • Kanji stroke order diagrams are just a click away for most characters.
  • Custom search page for easily executing custom search queries.
  • Support for multiple dictionary formats including EPWING via the Yomichan Import tool.
  • Automatic note creation for the Anki flashcard program via the AnkiConnect plugin.
  • Clean, modern code makes it easy for developers to contribute new features.

Table of Contents

Installation

Yomichan comes in two flavors: stable and testing. Over the years, this extension has evolved to contain many complex features, which have become increasingly difficult for me to test across different browsers, versions, and environments. All new changes are initially introduced into the testing version, and when I am reasonably confident that they are bug free, they will get promoted to the stable version. If you are technically savvy and don't mind submitting issues on GitHub, try the testing version, otherwise the stable version will be your best bet.

Dictionaries

There are several free Japanese dictionaries available for Yomichan, with two of them having glossaries available in different languages. You must download and import the dictionaries you wish to use in order to enable Yomichan definition lookups. If you have proprietary EPWING dictionaries that you would like to use, please see the Yomichan Import page to learn how to convert and import them into Yomichan.

Please be aware that the non-English dictionaries contain fewer entries than their English counterparts. Even if your primary language is not English, you may consider also importing the English version for better coverage.

Basic Usage

  1. Click on the icon in the browser toolbar to open the Yomichan actions dialog.

  2. Click on the spanner/monkey wrench icon in the middle to open the options page.

  3. Import the dictionaries you wish to use for term and Kanji searches. If you do not have any dictionaries installed (or enabled), Yomichan will warn you that it is not ready for use by displaying an orange exclamation mark over its icon. This exclamation mark will disappear once you have installed and enabled at least one dictionary.

  4. Hold down the Shift key or the middle mouse button as you move your mouse over text to display a popup window containing term definitions. This window will only be shown if definitions were found and it can be dismissed by clicking anywhere outside of it.

  5. Click on the icon to hear the term pronounced by a native speaker. If an audio sample is not available, you will hear a short click instead. You can configure the sources used to retrieve audio samples in the options page.

  6. Click on individual Kanji in the term definition results to view additional information about those characters including stroke order diagrams, readings, meanings, as well as other useful data.

Custom Dictionaries

Yomichan supports the use of custom dictionaries including the esoteric but popular EPWING format. They were often utilized in portable electronic dictionaries similar to the ones pictured below. These dictionaries are often sought after by language learners for their correctness and excellent coverage of the Japanese language.

Unfortunately, as most of the dictionaries released in this format are proprietary I am unable to bundle them with Yomichan. You will need to procure these dictionaries yourself and import them with Yomichan Import. Please see the project page for additional details.

Pocket EPWING dictionaries

Anki Integration

Yomichan features automatic flashcard creation for Anki, a free application designed to help you retain knowledge. This feature requires the prior installation of an Anki plugin called AnkiConnect. Please see the respective project page for more information about how to set up this software.

Flashcard Configuration

Before flashcards can be automatically created, you must configure the templates used to create term and/or Kanji notes. If you are unfamiliar with Anki deck and model management, this would be a good time to reference the Anki Manual. In short, you must specify what information should be included in the flashcards that Yomichan creates through AnkiConnect.

Flashcard fields can be configured with the following steps:

  1. Open the Yomichan options page and scroll down to the section labeled Anki Options.

  2. Tick the checkbox labeled Enable Anki integration (Anki must be running with AnkiConnect installed).

  3. Select the type of template to configure by clicking on either the Terms or Kanji tabs.

  4. Select the Anki deck and model to use for new creating new flashcards of this type.

  5. Fill the model fields with markers corresponding to the information you wish to include (several can be used at once). Advanced users can also configure the actual Handlebars templates used to create the flashcard contents (this is strictly optional).

    Markers for Term Cards

    Marker Description
    {audio} Audio sample of a native speaker's pronunciation in MP3 format (if available).
    {cloze-body} Raw, inflected term as it appeared before being reduced to dictionary form by Yomichan.
    {cloze-prefix} Text for the containing {sentence} from the start up to the value of {cloze-body}.
    {cloze-suffix} Text for the containing {sentence} from the value of {cloze-body} to the end.
    {dictionary} Name of the dictionary from which the card is being created (unavailable in grouped mode).
    {expression} Term expressed as Kanji (will be displayed in Kana if Kanji is not available).
    {furigana} Term expressed as Kanji with Furigana displayed above it (e.g. 日本語にほんご).
    {furigana-plain} Term expressed as Kanji with Furigana displayed next to it in brackets (e.g. 日本語[にほんご]).
    {glossary} List of definitions for the term (output format depends on whether running in grouped mode).
    {reading} Kana reading for the term (empty for terms where the expression is the reading).
    {screenshot} Screenshot of the web page taken at the time the term was added.
    {sentence} Sentence, quote, or phrase in which the term appears in the source content.
    {tags} Grammar and usage tags providing information about the term (unavailable in grouped mode).
    {url} Address of the web page in which the term appeared in.

    Markers for Kanji Cards

    Marker Description
    {character} Unicode glyph representing the current Kanji.
    {cloze-body} Raw, inflected parent term as it appeared before being reduced to dictionary form by Yomichan.
    {cloze-prefix} Text for the containing {sentence} from the start up to the value of {cloze-body}.
    {cloze-suffix} Text for the containing {sentence} from the value of {cloze-body} to the end.
    {dictionary} Name of the dictionary from which the card is being created.
    {glossary} List of definitions for the Kanji.
    {kunyomi} Kunyomi (Japanese reading) for the Kanji expressed as Katakana.
    {onyomi} Onyomi (Chinese reading) for the Kanji expressed as Hiragana.
    {screenshot} Screenshot of the web page taken at the time the Kanji was added.
    {sentence} Sentence, quote, or phrase in which the character appears in the source content.
    {url} Address of the web page in which the Kanji appeared in.

When creating your model for Yomichan, please make sure that you pick a unique field to be first; fields that will contain {expression} or {character} are ideal candidates for this. Anki does not require duplicate flashcards to be added to a deck and uses the first field in the model to check for duplicates. If, for example, you have {reading} configured to be the first field in your model and already have 橋はし in your deck, you will not be able to create a flashcard for 箸はし, because they share the same reading.

Flashcard Creation

Once Yomichan is configured, it becomes trivial to create new flashcards with a single click. You will see the following icons next to term definitions.

  • Clicking adds the current expression as Kanji (e.g. 食べる).
  • Clicking adds the current expression as Hiragana or Katakana (e.g. たべる).

Below are some troubleshooting tips you can try if you are unable to create new flashcards:

  • Individual icons will appear grayed out if a flashcard cannot be created for the current definition (e.g. it already exists in the deck).
  • If all of the buttons appear grayed out then you should double-check your deck and model configuration settings.
  • If no icons appear at all, please make sure that Anki is running in the background and that AnkiConnect has been installed.

Keyboard Shortcuts

The following shortcuts are globally available:

Shortcut Action
Alt + Insert Open search page.
Alt + Delete Toggle extension on/off.

The following shortcuts are available on search results:

Shortcut Action
Esc Cancel current search
Alt + PgUp Page up through results.
Alt + PgDn Page down through results.
Alt + End Go to last result.
Alt + Home Go to first result.
Alt + Up Go to previous result.
Alt + Down Go to next result.
Alt + b Go to back to source term.
Alt + e Add current term as expression to Anki.
Alt + r Add current term as reading to Anki.
Alt + p Play audio for current term.
Alt + k Add current Kanji to Anki.

Development

Working on Yomichan and related tools is very time consuming and I am always on the lookout for code contributions from other developers who want to help out. I take pride in the high quality of the codebase and ask you to follow the following basic guidelines when creating pull requests:

  • Please discuss large features before writing code.
  • Follow the conventions and style of the existing code.
  • Write clean, modern ES6 code (const/let, await, arrow functions, etc.)
  • Large pull requests without a clear scope will not be merged.
  • Incomplete or non-standalone features will not be merged.

Templates

Yomichan uses Handlebars templates for user interface generation. The source templates are found in the tmpl directory and the compiled version is stored in the ext/bg/js/templates.js file. If you modify the source templates, you will need to also recompile them. If you are developing on Linux or Mac OS X, you can use the included build_tmpl.sh and build_tmpl_auto.sh shell scripts to do this for you (inotify-tools required). Otherwise, simply execute handlebars tmpl/*.html -f ext/bg/js/templates.js from the project's base directory to compile all the templates.

Dependencies

Yomichan uses several third-party libraries to function. Below are links to homepages, snapshots, and licenses of the exact versions packaged.

Frequently Asked Questions

I'm having problems importing dictionaries in Firefox, what do I do?

Yomichan uses the cross-browser IndexedDB system for storing imported dictionary data into your user profile. Although everything "just works" in Chrome, depending on settings, Firefox users can run into problems due browser bugs. Yomichan catches errors and tries to offer suggestions about how to work around Firefox issues, but in general at least one of the following solutions should work for you:

  • Make sure you have cookies enabled. It appears that disabling them also disables IndexedDB for some reason. You can still have cookies be disabled on other sites; just make sure to add the Yomichan extension to the whitelist of whatever tool you are using to restrict cookies. You can get the extension "URL" by looking at the address bar when you have the search page open.
  • Make sure that you have sufficient disk space available on the drive Firefox uses to store your user profile. Firefox limits the amount of space that can be used by IndexedDB to a small fraction of the disk space actually available on your computer.
  • Make sure that you have history set to "Remember history" enabled in your privacy settings. When this option is set to "Never remember history", IndexedDB access is once again disabled for an inexplicable reason.
  • As a last resort, try using the Refresh Firefox feature to reset your user profile. It appears that the Firefox profile system can corrupt itself preventing IndexedDB from being accessible to Yomichan.

Why does the Kanji results page display "No data found" for several fields?

You are using data from the KANJIDIC dictionary that was exported for an earlier version of Yomichan. It does not contain the additional information which newer versions of Yofomichan expect. Unfortunately, since major browser implementations of IndexedDB do not provide reliable means for selective bulk data deletion, you will need purge your database and install the latest version of the KANJIDIC to see additional information about characters.

Can I still create cards without HTML formatting? The option for it is gone!

Developing Yomichan is a constant balance between including useful features and keeping complexity at a minimum. With the new user-editable card template system, it is possible to create text-only cards without having to double the number field of templates in the extension itself. If you would like to stop HTML tags from being added to your cards, simply copy the contents of the text-only field template into the template box on the Anki settings page (make sure you have the Show advanced options checkbox ticked), making sure to replace the existing values.

Will you add support for online dictionaries?

Online dictionaries will never be implemented because it is impossible to support them in a robust way. In order to perform Japanese deinflection, Yomichan must execute dozens of database queries per every single word. Factoring in network latency and the fragility of web scraping, I do not believe that it is possible to realize a good user experience.

Is it possible to use Yomichan with files saved locally on my computer with Chrome?

In order to use Yomichan with local files in Chrome, you must first tick the Allow access to file URLs checkbox for Yomichan on the extensions page. Due to the restrictions placed on browser addons in the WebExtensions model, it will likely never be possible to use Yomichan with PDF files.

Is it possible to delete individual dictionaries without purging the database?

Although it is technically possible to purge specific dictionaries, due to the limitations of the underlying browser IndexedDB system, this process is extremely slow. For example, it can take up to ten minutes to delete a single moderately-sized term dictionary! Instead of including a borderline unusable feature in Yomichan, I have chosen to disable dictionary deletion entirely.

Why aren't EPWING dictionaries bundled with Yomichan?

The vast majority of EPWING dictionaries are proprietary, so unfortunately I am unable to legally include them in this extension for copyright reasons.

When are you going to add support for $MYLANGUAGE?

Developing Yomichan requires a significant understanding of Japanese sentence structure and grammar. I have no time to invest in learning yet another language; therefore other languages will not be supported. I will also not accept pull request containing this functionality, as I will ultimately be the one maintaining your code.

Screenshots

Term definitions Kanji information Dictionary options Anki options