Yokome

Yokome is a web-based reading support system. Hovering over a webpage you are currently viewing, it looks up the words you read, giving you an idea which of the multiple word senses is most likely in the given context.

Right now, Yokome is restricted to Japanese text, but it was designed with multilinguality in mind.

This system was developed as a master project in the context of Web Interfaces for Language Processing Systems in summer semester 2019 at the University of Hamburg. It consists of two parts: A backend written in python and a frontend packaged as a Firefox WebExtension.

Learn how to use Yokome below or read the developer documentation for the backend or the WebExtension.

To see what can be improved, take a look at the future work section.

Requirements

The startup procedure below has been tested on Ubuntu 18.04.3 LTS. The explanations assume that the following programs are available on your system:

  • git

  • docker

  • tar

  • zip

  • bzip2

Yokome will most certainly not work on Windows < 6.0 (Vista).

How to start Yokome

From a terminal, download the project files:

git clone https://github.com/julianbetz/yokome.git

Start the background service:

cd yokome
docker-compose up

This will start the service on port 5003 on localhost. The plugin will expect that the service runs on this port.

The web extension is known to work with Firefox Developer Edition 70.0b1 (64-bit). To get this version, select the directory of your operating system and then en-US at https://github.com/julianbetz/yokome-browser/tree/master. Download the installation files and extract/run them to have the proper Firefox version on your system. Then start it.

The extension is unsigned, so you have to give Firefox permission to run it. There are two ways to do so:

  • Install the extension persistently:

    • Go to about:config. A warning will appear.

    • Click I accept the risk! and set the variable xpinstall.signatures.required to false.

    • Package the web extension from source: From the root of the project directory, run make plugin.

    • Locate the file bin/yokome.xpi and drag and drop it into Firefox’s address bar.

    • Yokome requires access to the docker service and to the browser tabs. In the popup that appears, click Add to grant those permissions.

    • In the next popup, you can choose whether you want Yokome to also run in private windows.

  • Alternatively, you can activate the extension for the current session only:

    • Go to about:debugging#/runtime/this-firefox.

    • Click Load Temporary Add-on... and locate the file yokome/deployment/plugin/manifest.json (relative to the git repository you downloaded).

How to Use Yokome

Open a page of your choice with target-language content (e.g. the Japanese Wikipedia main page). Yokome works on both HTTP and HTTPS web pages.

symbol in address bar

In the address bar, to its right side, you will find a symobol that looks like a circle. Click that symbol to activate Yokome on the current page. After you activated Yokome, a box will start to hover over the left lower corner of the page. This is where dictionary results will be displayed. The box is transparent as long as you do not interact with it. This is so that you can see what is displayed behind it on the web page. To see what is shown on the box, move the cursor over it.

multi-colored tabs

To look up a word, simply hover your mouse over it. After some time, the results appear in the box. If there are multiple dictionary entries that apply to the word you looked up, they show as tabs at the top of the box. The first one is selected and its entries are shown below. Click on any of the other tabs to show their information.

The tabs are colored based on how likely their entries represent the word in the text. The more intense the yellow coloring, the more likely the entry applies.

multi-colored connotations

In the space below the tabs, the different connotations of the selected entry appear. Again, the more intense the yellow coloring gets, the more likely is this connotation the one meant in the text.

In the About tab you can find more information on Yokome.

If you feel that Yokome disturbs your interaction with the page, you can move it to any of the other corners by clicking on one of the triangles around the box.

If you want to deactivate Yokome on the current page, you can click the symbol in the address bar again.

About the name

From the Japanese dictionary JMdict:

  • 横目【よこめ】 (yokome):
    noun: sidelong glance

Yokome tries to be as non-invasive as possible by reacting on mere mouse hovering, leaving the original text as-is and hovering above the page in a corner of your choice, so as to not obstruct your reading.

Instead of pulling out a physical dictionary, or doing the highlight-copy-paste combo, it allows you to find the meaning of a word merely by resting the mouse pointer over the word you are interested in.

Yokome’s goal is to make dictionary lookups as simple as possible, so that finding a word requires only a sidelong glance.

Licensing

Yokome is licensed under the Apache License, Version 2.0.

The following data is required for the Japanese version to work:

The required data can be downloaded using the command make data (requires git, tar, bzip2 and gzip).

Furthermore, the Japanese version makes use of the Japanese morphological analyzer JUMAN++ (Morita, Kawahara, Kurohashi 2015). JUMAN++ is distributed under the Apache License, Version 2.0. You can obtain it via download by issuing make lib/jumanpp-1.02.tar.xz.