Updating README.md

This commit is contained in:
Alex Yatskov 2017-03-14 21:10:48 -07:00
parent 94af149040
commit ed710ed71c

142
README.md
View File

@ -1,80 +1,100 @@
# Yomichan #
Yomichan turns your browser into a tool for building Japanese language literacy by helping you to decipher texts which
would be otherwise too difficult tackle. This extension was inspired in part by
[Rikaichan](https://addons.mozilla.org/en-US/firefox/addon/rikaichan/) and
[Rikaikun](https://chrome.google.com/webstore/detail/rikaikun/jipdnfibhldikgcjhfnomkfpcebammhp?hl=en), but it stands
apart in its goal of being a all-encompassing learning tool as opposed to a mere browser-based dictionary. It is the
evolution of the [Yomichan](https://foosoft.net/projects/yomichan-anki) plugin that I developed for Anki when I began studying Japanese.
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](https://addons.mozilla.org/en-US/firefox/addon/rikaichan/) for Firefox and
[Rikaikun](https://chrome.google.com/webstore/detail/rikaikun/jipdnfibhldikgcjhfnomkfpcebammhp?hl=en) for Chrome, but it
stands apart in its goal of being a all-encompassing learning tool as opposed to a mere browser-based dictionary.
## Requirements ##
Yomichan provides advanced features not available in other browser-based dictionaries:
For basic functionality:
* 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](https://ja.wikipedia.org/wiki/EPWING) via
the [Yomichan Import](https://foosoft.net/projects/yomichan-import) tool.
* Automatic note creation for the [Anki](https://apps.ankiweb.net/) flashcard program via
the [AnkiConnect](https://foosoft.net/projects/anki-connect) plugin.
* Clean, modern code makes it easy for developers to [contribute](https://github.com/FooSoft/yomichan) new features.
* [Google Chrome](https://www.google.com/chrome/browser/desktop/) (versions 45+)
* [Mozilla Firefox](https://www.mozilla.org/en-US/firefox/new/) (versions 51+)
## Browser Support ##
For development:
* Google Chrome (versions 45+)
* [Git LFS](https://git-lfs.github.com/)
* [Go](https://golang.org/)
* [Handlebars](http://handlebarsjs.com/)
* [Node.js](https://nodejs.org/)
[![](https://foosoft.net/projects/yomichan/img/chrome-web-store.png)](https://chrome.google.com/webstore/detail/yomichan/ogmnaimimemjmbakcfefmnahgdfhfami)
## Installation ##
* Mozilla Firefox (versions 51+)
Yomichan can downloaded free of charge from the [Chrome Web
Store](https://chrome.google.com/webstore/detail/yomichan/ogmnaimimemjmbakcfefmnahgdfhfami) and the [Firefox
Marketplace](https://addons.mozilla.org/en-US/firefox/addon/yomichan/). If you find this extension helpful and
appreciate the time that was spent developing it, I would kindly ask that you leave a positive review. Your support and
feedback encourages continued development of this tool.
[![](https://foosoft.net/projects/yomichan/img/firefox-marketplace.png)](https://addons.mozilla.org/en-US/firefox/addon/yomichan/)
[![](https://foosoft.net/projects/yomichan/img/store.png)](https://chrome.google.com/webstore/detail/yomichan/ogmnaimimemjmbakcfefmnahgdfhfami)
[![](https://foosoft.net/projects/yomichan/img/market.png)](https://addons.mozilla.org/en-US/firefox/addon/yomichan/)
Yomichan is sitting in a queue to be reviewed and signed by Mozilla. This process can take months; if you wish to
use this extension today:
At present, Yomichan is sitting in a queue to be reviewed and signed by Mozilla. If you don't want to wait for several
weeks for approval and wish to use this extension in Firefox today, you can follow the steps below:
1. Type `about:config` into the browser address bar.
2. Skip past the "voiding your warranty" nag screen.
3. Type `xpinstall.signatures.required` into the search bar on top.
4. Double-click the displayed entry to set its value to `false`.
5. Install extension as usual from the [Firefox Marketplace](https://addons.mozilla.org/en-US/firefox/addon/yomichan/).
1. Type `about:config` into the browser address bar.
2. Skip past the "voiding your warranty" nag screen.
3. Type `xpinstall.signatures.required` into the search bar on top.
4. Double-click the displayed entry to set its value to `false`.
5. Install extension as usual from the [Firefox Marketplace](https://addons.mozilla.org/en-US/firefox/addon/yomichan/).
## Basic Features ##
## Basic Functionality ##
1. Click on the ![](https://foosoft.net/projects/yomichan/img/logo.png) icon in the browser toolbar to open the Yomichan actions dialog.
1. Click on the ![](https://foosoft.net/projects/yomichan/img/logo.png) icon in the browser toolbar to open the Yomichan options page.
2. Import the dictionaries (bundled or custom) you wish to use for term and Kanji searches.
3. Hold down <kbd>Shift</kbd> (or the middle mouse button) as you hover over text to see term definitions.
4. Click on the ![](https://foosoft.net/projects/yomichan/img/play-audio.png) icon to hear the term pronounced by a native speaker (if audio is available).
5. Click on Kanji in the definition window to view additional information about that character.
[![Actions dialog](https://foosoft.net/projects/yomichan/img/ui-actions-thumb.png)](https://foosoft.net/projects/yomichan/img/ui-actions.png)
2. Click on the *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.
[![Dictionary importer](https://foosoft.net/projects/yomichan/img/ui-import-thumb.png)](https://foosoft.net/projects/yomichan/img/ui-import.png)
4. Hold down the <kbd>Shift</kbd> 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.
[![Term search results](https://foosoft.net/projects/yomichan/img/ui-terms-thumb.png)](https://foosoft.net/projects/yomichan/img/ui-terms.png)
5. Click on the ![](https://foosoft.net/projects/yomichan/img/button-play-audio.png) icon to hear the term pronounced by a native speaker. If an audio sample is not
available, you will hear a short click instead.
6. Click on individual Kanji in the term definition results to view additional information about those characters
including readings, meanings, and a stroke order diagram.
[![Kanji search results](https://foosoft.net/projects/yomichan/img/ui-kanji-thumb.png)](https://foosoft.net/projects/yomichan/img/ui-kanji.png)
## Custom Dictionaries ##
Yomichan supports importing of custom dictionaries including the esoteric but popular
[EPWING](https://ja.wikipedia.org/wiki/EPWING) format. For more information about how to use this feature, please see
the [Yomichan Import](https://foosoft.net/projects/yomichan-import) project page.
Yomichan supports the use of custom dictionaries including the esoteric but popular
[EPWING](https://ja.wikipedia.org/wiki/EPWING) format. 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](https://foosoft.net/projects/yomichan-import). Please see the project page for additional details.
[![Pocket dictionaries](https://foosoft.net/projects/yomichan/img/dictionary-thumb.png)](https://foosoft.net/projects/yomichan/img/dictionary.jpg)
## Anki Integration ##
Yomichan features automatic flashcard creation for [Anki](http://ankisrs.net/), a free application designed to help you
retain knowledge. This functionality requires prior installation of the
[AnkiConnect](https://foosoft.net/projects/anki-connect/) plugin. The installation process can be done in three steps:
1. Open the *Install Add-on* dialog by selecting *Tools* &gt; *Add-ons* &gt; *Browse &amp; Install* in Anki.
2. Input *2055492159* into the text box labeled *Code* and press the *OK* button to proceed.
3. Restart Anki when prompted to do so in order to complete the installation of AnkiConnect.
When using AnkiConnect, Anki must be kept running in the background for automatic flashcard creation to function.
retain knowledge. This feature requires the prior installation of an Anki plugin called [AnkiConnect](https://foosoft.net/projects/anki-connect).
Please see the respective project page for more information about how to set up this software.
### Flashcard Configuration ###
Before flashcards can be automatically created through Yomichan, Anki must be configured as follows:
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](http://ankisrs.net/docs/manual.html). In short, you must specify what information should be included in the
flashcards that Yomichan creates through AnkiConnect. This can be accomplished with the following steps:
1. In your web browser, open the Yomichan options page by clicking the ![](https://foosoft.net/projects/yomichan/img/logo.png) icon.
2. Activate the *Terms* or the *Kanji* tab, depending on the type of card template you wish to configure.
3. Select the Anki deck and model to use when creating new flashcards (see the [Anki Manual](http://ankisrs.net/docs/manual.html) for more details).
4. Populate the model fields with markup representing contextual properties for the current vocabulary term or Kanji:
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](https://foosoft.net/projects/anki-connect) 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 out the displayed model fields with markers representing the information you wish to include:
#### Markers for Term Cards ####
@ -101,12 +121,18 @@ Before flashcards can be automatically created through Yomichan, Anki must be co
`{onyomi}` | Onyomi (Chinese reading) for the Kanji expressed as Hiragana.
`{url}` | Address of the web page in which the Kanji appeared in.
5. Click on the ![](https://foosoft.net/projects/yomichan/img/add-expression.png) icon to add the current expression using Kanji (e.g. 食べる). If the icon
appears grayed out, this means that a new flashcard cannot be created with the current configuration (please verify
your Anki deck and model settings).
6. Click on the ![](https://foosoft.net/projects/yomichan/img/add-reading.png) icon to add the current expression using the reading alone (e.g. たべる). If
the icon appears grayed out, this means that a new flashcard cannot be created with the current configuration
(please verify your Anki deck and model settings).
### 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 ![](https://foosoft.net/projects/yomichan/img/button-add-expression.png) adds the current expression as Kanji (e.g. 食べる).
* Clicking ![](https://foosoft.net/projects/yomichan/img/button-add-reading.png) adds the current expression as Hiragana or Katakana (e.g. たべる).
These icons will appear grayed out if a flashcard cannot be created for the current definition (it already exists in the
deck, for example). If all of the buttons appear grayed out then you should double-check your deck and model
configuration settings (see the Flashcard Configuration section above). If no icons appear at all, please make sure that
Anki is running in the background.
## Frequently Asked Questions ##