diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 108 |
1 files changed, 70 insertions, 38 deletions
@@ -1,61 +1,47 @@ -# Yomitan <!-- omit from toc --> +# Yomitan [>)](https://chrome.google.com/webstore/detail/yomitan/likgccmbimhjbgkjambclfkhldnlhbnn) [>)](https://addons.mozilla.org/en-US/firefox/addon/yomitan/) [](https://securityscorecards.dev/viewer/?uri=github.com/themoeway/yomitan) [](https://discord.gg/UGNPMDE7zC) -:wave: **This project is a community fork of Yomichan** (which was [sunset](https://foosoft.net/posts/sunsetting-the-yomichan-project/) by its owner on Feb 26 2023). We have made a number of foundational changes to ensure **the project stays alive, works on latest browser versions, and is easy to contribute to**: +:wave: **Yomitan is [the successor](https://foosoft.net/posts/passing-the-torch-to-yomitan/) to Yomichan** ([migration guide](./docs/yomichan-migration.md#migrating-from-yomichan)) which was [sunset](https://foosoft.net/posts/sunsetting-the-yomichan-project/) by its owner on Feb 26, 2023. We have made a number of [foundational changes](#changes) to ensure **the project stays alive, works on latest browser versions, and is easy to contribute to**. -- Completed the Manifest V2 โ V3 transition, [read why here!](https://developer.chrome.com/blog/resuming-the-transition-to-mv3/). -- Switched to using ECMAScript modules and npm-sourced dependencies. -- Implemented an end-to-end CI/CD pipeline. -- Switched to standard testing frameworks, vitest and playwrights. +๐ข **New contributors [welcome](#contributing)!** -In addition, we are beginning to make important bug fixes and minor enhancements: +๐ข **Interested in adding a new language to Yomitan? See [here](./docs/development/language-features.md) for thorough documentation!** -- Improve dictionary import speeds by 2x~10x. -- Add functionality to import/export multiple dictionaries, enabling portability across devices. -- And [more](https://github.com/themoeway/yomitan/pulls?q=is%3Apr+is%3Amerged+-label%3Aarea%2Fdependencies+-label%3Akind%2Fmeta). +## What is Yomitan? -Since the owner requested forks be uniquely named, we have chosen a new name, _yomitan_. (_-tan_ is an honorific used for anthropomorphic moe characters.) While we've made some substantial changes, the majority of the extension's functionality is thanks to hard work of foosoft and numerous other open source contributors from 2016-2023. +Yomitan turns your web browser into a tool for building Japanese language literacy by helping you **read** texts that would otherwise be too difficult to tackle. -## Contributing - -Since this is a distributed effort, we **highly welcome new contributors**! Feel free to browse the [issue tracker](https://github.com/themoeway/yomitan/issues), and read our [contributing guidelines](./CONTRIBUTING.md). If you want to add or improve support for a language, read the documentation on [language features](./docs/development/language-features.md). You can also find us on [TheMoeWay Discord](https://discord.gg/UGNPMDE7zC) at [#yomitan-development](https://discord.com/channels/617136488840429598/1081538711742844980). - -## What's Yomitan?<!-- omit from toc --> - -Yomitan turns your web browser into a tool for building Japanese language literacy by helping you to decipher texts -which would be otherwise too difficult to tackle. This extension is similar to [10ten Japanese Reader (formerly Rikaichamp)](https://addons.mozilla.org/en-US/firefox/addon/10ten-ja-reader/) for Firefox and [Rikaikun](https://chrome.google.com/webstore/detail/rikaikun/jipdnfibhldikgcjhfnomkfpcebammhp) for Chrome, but it stands apart in its goal of being an all-encompassing learning tool as opposed to a mere browser-based dictionary. +Yomitan provides powerful features not available in other browser-based dictionaries: -Yomitan 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](https://ja.wikipedia.org/wiki/EPWING) via the [Yomitan Import](https://github.com/themoeway/yomitan-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/themoeway/yomitan/blob/master/CONTRIBUTING.md) new features. +- ๐ฌ Interactive popup definition window for displaying search results. +- ๐ Built-in native audio sources for Japanese words with the ability to add your own [custom audio sources](./docs/audio.md). +- โ๏ธ Kanji stroke order diagrams are just a click away. +- ๐ [Automatic flashcard creation](./docs/anki-integration.md#anki-integration) for the [Anki](https://apps.ankiweb.net/) flashcard program via the [AnkiConnect](https://foosoft.net/projects/anki-connect) plugin. +- ๐ Custom search page for easily executing custom search queries. +- ๐ Support for multiple dictionary formats including [EPWING](https://ja.wikipedia.org/wiki/EPWING) via the [Yomitan Import](https://github.com/themoeway/yomitan-import) tool. +- โจ Clean, modern code makes it easy for developers to [contribute](#contributing) new features and languages. [](img/ss-terms.png) [](img/ss-kanji.png) [](img/ss-dictionaries.png) [](img/ss-anki.png) -## Helpful information<!-- omit from toc --> +## Helpful information - [Migrating from Yomichan (legacy)](./docs/yomichan-migration.md#migrating-from-yomichan) -- [Importing standardised and custom dictionaries](./docs/dictionaries.md#dictionaries) -- [Anki integration and flashcards creation](./docs/anki-integration.md#anki-integration) -- [Advanced options, including MeCab](./docs/advanced-options.md#advanced-options) - [Frequently asked questions](./docs/faq.md#frequently-asked-questions) +- [Recommended and custom dictionary import guide](./docs/dictionaries.md#dictionaries) +- [Anki integration and flashcard creation guide](./docs/anki-integration.md#anki-integration) - [Keyboard shortcuts](./docs/keyboard-shortcuts.md) +- [Advanced options, including MeCab](./docs/advanced-options.md#advanced-options) ## Installation -Yomitan comes in two flavors: _stable_ and _testing_. New changes are initially introduced into the _testing_ version, and after some time spent ensuring that they are relatively bug free, they will be 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. +Yomitan comes in two flavors: _stable_ and _testing_. New changes are initially introduced into the _testing_ version, and after some time spent ensuring that they are relatively bug free, they will be promoted to the _stable_ version. If you are technically savvy and don't mind [submitting issues](https://github.com/themoeway/yomitan/issues/new/choose) on GitHub, try the _testing_ version; otherwise, the _stable_ version will be your best bet. Check [contributing](#contributing) for more information on how to help. - **Google Chrome** @@ -66,9 +52,7 @@ Yomitan comes in two flavors: _stable_ and _testing_. New changes are initially - [stable](https://addons.mozilla.org/en-US/firefox/addon/yomitan/) - [testing](https://github.com/themoeway/yomitan/releases) โป -โป Unlike Chrome, Firefox does not allow extensions meant for testing to be hosted in the marketplace. -You will have to download a desired version and side-load it yourself. You only need to do this once and will get -updates automatically. +โป Unlike Chrome, Firefox does not allow extensions meant for testing to be hosted in the marketplace. You will have to download the desired version and side-load it yourself. You only need to do this once, and you will get updates automatically. ## Basic Usage @@ -81,7 +65,7 @@ updates automatically. - The <img src="ext/images/question-mark-circle.svg" width="16" height="16" alt="question mark symbol"> _question mark_ button will open the Information page. - The <img src="ext/images/profile.svg" width="16" height="16" alt="profile icon"> _profile_ button will appear when multiple profiles exist, allowing the current profile to be quickly changed. -2. Import the dictionaries you wish to use for term and kanji searches, head over to the [the dictionary docs](./docs/dictionaries.md) to get set up! If you do not have any dictionaries installed or enabled, Yomitan 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. +2. Import the dictionaries you wish to use for term and kanji searches; head over to the [dictionary docs](./docs/dictionaries.md) to get set up! If you do not have any dictionaries installed or enabled, Yomitan 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. <img src="resources/images/settings-dictionaries-popup.png" width="300" alt="custom dictionaries list"> @@ -91,12 +75,60 @@ updates automatically. 4. Click on the <img src="ext/images/play-audio.svg" width="16" height="16" alt="loudspeaker icon"> _speaker_ button to hear the term pronounced by a native speaker. If an audio sample is not available, you will hear a short click instead. For more options, see [Audio Configuration](./docs/audio.md). -5. 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. +5. Click on individual kanji in the term definition results to view additional information about those characters, including stroke order diagrams, readings, meanings, and other useful data. <img src="resources/images/search-popup-kanji.png" width="300" alt="popup with kanji details"> To further enhance your Yomitan experience, it's worth [integrating with Anki](./docs/anki-integration.md), a spaced-repetition flashcard program to help solidify the words you encounter. +## Changes + +> While we have made some substantial changes, the majority of the extension's functionality is thanks to hard work of [FooSoft](https://foosoft.net/) and many other incredible open source contributors from 2016-2023. + +Major changes: + +- ๐ Added multi-language support! +- ๐ช Completed the Manifest V2 โ V3 transition, [read why here](https://developer.chrome.com/blog/resuming-the-transition-to-mv3/). +- โก Switched to using ECMAScript modules and npm-sourced dependencies. +- ๐ง Implemented an end-to-end CI/CD pipeline. +- ๐งช Switched to standard testing frameworks, vitest and playwrights. + +In addition, we have made important bug fixes and minor enhancements: + +- โก Improved dictionary import speeds by 2x~10x. +- ๐ Added functionality to import/export multiple dictionaries, enabling portability across devices. +- โจ And [more](https://github.com/themoeway/yomitan/pulls?q=is%3Apr+is%3Amerged+-label%3Aarea%2Fdependencies+-label%3Akind%2Fmeta). + +Since the owner requested forks be uniquely named, we have chosen a new name, _Yomitan_ (_-tan_ is an honorific used for anthropomorphic moe characters). + +## Contributing + +๐ **Dip your toes into contributing by looking at issues with the label [good-first-issue](https://github.com/themoeway/yomitan/issues?q=is%3Aopen+is%3Aissue+label%3Agood-first-issue).** + +Since this is a distributed effort, we **highly welcome new contributors**! Feel free to browse the [issue tracker](https://github.com/themoeway/yomitan/issues), and read our [contributing guidelines](./CONTRIBUTING.md). + +Here are some ways anyone can help: + +- Try using the Yomitan dev build. Not only do you get cutting edge features, but you can help uncover bugs and give feedback to developers early on. +- Document any UI/UX friction in Github Issues. We're looking to make Yomitan more accessible to non-technical users. +- All the issues in `area/bug` older than 2 months need help reproducing. If anything interests you, please try to reproduce it and report your results. We can't easily tell if these issues are one-off, have since been resolved, or are no longer relevant. + +> The current active maintainers of Yomitan spend a lot of their time debugging and triaging issues. When someone files a bug report, we need to assess the frequency and severity of the bug. It is extremely helpful if we get multiple reports of people who experience a bug or people who can contribute additional detail to an existing bug report. + +If you're looking to code, please let us know what you plan on working on before submitting a Pull Request. This gives the core maintainers an opportunity to provide feedback early on before you dive too deep. You can do this by opening a Github Issue with the proposal. + +Some contributions we always appreciate: + +- Well-written tests covering different functionalities. This includes [playwright tests](https://github.com/themoeway/yomitan/tree/master/test/playwright), [benchmark tests](https://github.com/themoeway/yomitan/tree/master/benches), and unit tests. +- Increasing our type coverage. +- More and better documentation! + +Information on how to setup and build the codebase can be found [here](./CONTRIBUTING.md#setup). + +If you want to add or improve support for a language, read the documentation on [language features](./docs/development/language-features.md). + +Feel free to join us on [TheMoeWay Discord ๐](https://discord.gg/UGNPMDE7zC) at [#yomitan-development](https://discord.com/channels/617136488840429598/1081538711742844980). + ## Licenses Required licensing notices for this project follow below: |