A flashcards companion app tailored for Minna no Nihongo Shokyū Ⅰ & Ⅱ textbooks.

^❄︎

🧭 Table of contents

1. Overview
2. Installation
3. Development
4. Notes
5. Contributing

☁ Overview

Got a vocab test looming in your Japanese class ? Feeling overwhelmed by the mountain of words in your Minna no Nihongo lessons and not sure where to start ?
Worry no more, there's an app for that !

This readme mostly discusses technical stuff 🧙‍♂️
Should you simply wish to give the app a whirl, your journey awaits beneath –

 ⥼ Web version ⥽  ⥼ Android version ⥽ 

^{Note – You may also use the web version on Android.}

hifumi was meant to be a replacement for Minna no Flashcards, reworked with the whole fifty lessons of the Minna no Nihongo Shokyū books.
And well, that is what it ended up being, but an overengineered one for sure !

It also packs additional quality of life features, such as being able to create custom lists of words to study (called decks), opening Jisho.org with the click of a button, and more !

📦 Installation

Web

The web app requires no particular installation.

A prebuilt version is also offered in the releases. It can be used locally by running something like python3 -m http.server in the root of the folder.

Android

1. Head over to the releases page.
2. Grab the right apk for you phone's CPU architecture. If unsure, get the arm64-v8a version, this corresponds to what most smartphones run on nowadays.
3. Install it like you would with any other apk file. Opening it from your device's file manager usually does the trick.

iOS & Others

At the moment, only precompiled binaries for Android and Web are offered. Therefore, the Web version should be used on all other platforms. If you'd like to see a platform added, you're welcome to open an issue :)

🛠️ Development

Interested in modifying the source or building the app yourself ?

You will need a working copy of the Dart SDK and Flutter SDK, with Web and Android development set up. If you're new to this don't worry, it is pretty straightforward to set up, check out Install | Flutter.

1. Clone the repository : git clone --recurse-submodules https://github.com/vitto4/hifumi.git && cd hifumi
2. Get dependencies : flutter pub get
3. You are now ready to flutter run 🎉

If you end up modifying an icon, you may also need to flutter pub run flutter_launcher_icons.

🏗️ Build & Release

For the detailed build process, take a look at the build workflows in .github/build-*.yml.
tl;dr your usual flutter business, except a few things are overwritten here and there.

As for the Pages, it is more of a rolling release and may be deployed whenever from the main branch.

📅 Wishlist

A couple of things I may get to someday

• For the Web release, compile to Wasm once compatibility spans all browsers (see Wasm | Flutter).
• Make use of macros to write the version number and commit hash to app_info.dart at compile time, instead of relying on external tools in the build workflows.
• Include a dark theme.
• Look into adding iOS as a build target (would need sideloading support first though).

🧱 Structure

I might have got a little carried away when deciding on filenames and folders, so here's a much-needed file structure overview !
The result should resemble a somewhat frankensteined folder by feature arrangement.

Show structure

.
lib/
├── abstractions/         # Mix of abstractions on concepts and building blocks for the rest of the code, as well as data classes.
│                         # Abstractions on APIs/packages are instead located in `services/`.
│
├── pages/                # Pages of the app and related widgets.
│
├── services/             # Utility services for the app, including interfacing with the dataset, data storage, layout management, and more.
│
├── widgets/              # Shared widgets.
│    │
│    ├── archipelago/     # Home for island-style widgets, including containers, buttons, segmented selectors, etc.
│    │
│    ├── overlays/
│    │
│    ├── seasoning/       # Catch-all for miscellaneous widgets sprinkled throughout the app.
│    │                    # Their purpose is purely to make the app look better, hence `seasoning`s.
│    │
│    └── *.dart           # Various widgets that didn't fit in categories described above.
│
└── main.dart

🔖 Notes

• I have come to the realisation that UI/UX design is very much not easy (ᴗ.ᴗ). Thus, I've « borrowed » the design language from a suspiciously intimidating owl.
  

  Dear Duo,
  Please don't come for me, I did my lesson today, and if the borrowing isn't fine I'll happily comply !
  Thankies :3

  (fancy reaching out ? claim your Free OSINT Technique™)

• The dataset from which all words are sourced lives on GitHub as a separate project : MinnaNoDS.

• Some of the files are prefixed with @. I wanted them grouped together. It may not be pretty, but it works c:
  Looking back, I believe these could have been categorised as models or data classes.

• To save on asset size, fonts have been subsetted.

  • Noto Serif Japanese to あ
  • New Tegomin to あ字言葉準備中.
  • Noto Sans Japanese to whatever noto_sans_JP ends up being.

  See also fonts_subsetting.py and fonts-subsetting.yml.

• Among the widgets are some that are just asking to be reused standalone in another app ! This includes swipeable.dart and island_container.dart. If these sound like they could be useful for your project, be sure to take a look !

🧩 Contributing

You're very welcome to pitch in !
That being said, as I'm still pretty new to everything flutter and app development, the code can be a bit all over the place ; so proceed at your own risk (:

Also I probably won't devote much time to this project in the near future, so please bear with me if I'm slow on the reply ^-^