JPractice (日本語五十音)

English • 繁體中文

---

🇯🇵 JPractice - Learn Japanese Hiragana & Katakana Easily

🤖 Google Play: 日本語五十音 (JPractice)

---

JPractice is a modern, efficient, and beautifully designed Android application tailored for Japanese beginners to learn and test their Hiragana and Katakana skills.

Built with Clean Architecture, the MVVM design pattern, Jetpack Compose (Material 3), and a 100% offline local pronunciation engine, this project serves as a production-ready showcase of modern Android development best practices.

Important

This app is completely ad-free, providing a clean, focused, and distraction-free learning environment. All audio resources are embedded locally within the application package, allowing zero-latency offline playback without requiring an internet connection—saving user data and ensuring smooth learning anywhere, anytime.

---

📸 Screenshots

Hiragana & Katakana Chart & Quiz

🏠 Home Screen	⚙️ Quiz Settings	✍️ Kana Quiz	❌ Mistake Review & Analysis

Vocabulary Learning & Quiz

📖 Vocabulary & Pronunciation	⚙️ Vocabulary Quiz Settings	✍️ Vocabulary Quiz

---

✨ Key Features

• 🇯🇵 Complete Kana Charts
  • Covers Seion, Dakuon, and Yoon for both Hiragana and Katakana. Highly legible fonts with instant native pronunciation playback on click.
• ✍️ Customizable Quizzes
  • Customize quiz scope based on learning progress (e.g., Hiragana only, Katakana only, mixed; Seion, Dakuon, Yoon).
  • Supports granular filtering by rows (e.g., practicing only the first few rows or specific rows), perfect for step-by-step beginners.
• 📖 Comprehensive Vocabulary Library
  • Built-in vocabulary list categorized by Verbs, Adverbs, Nouns, i-Adjectives, and na-Adjectives.
  • Provides Furigana annotations, Romaji transliterations, native audio pronunciations, and spelling quizzes for words and example sentences.
• 🔇 100% Offline Audio
  • All pronunciation assets are embedded inside the res/raw folder. Zero loading time, zero internet required, providing instant audio feedback.
• 🎨 Modern Material 3 Design
  • Built using Jetpack Compose with responsive layouts, delightful micro-animations, and a soft, harmonious color palette for an optimal visual experience.

---

🛠️ Architecture & Tech Stack

This project strictly separates business logic from the UI presentation layer to ensure maintainability, testability, and scalability.

🏗️ Software Architecture: Clean Architecture

The project is divided into three core layers:

1. Presentation Layer: Implements the MVVM (Model-View-ViewModel) pattern, leveraging ViewModels to manage UI state (StateFlow) in harmony with Jetpack Compose's Uni-directional Data Flow (UDF).
2. Domain Layer: Contains pure Kotlin business logic, Use Cases, and Domain Entities.
3. Data Layer: Handles data persistence and audio playback, including Room Database, SharedPreferences, and a CSV parser (ReadCSVFileUtils).

🧰 Core Tech Stack

• UI Framework: Jetpack Compose (Declarative UI) with Material 3 components and Compose Navigation.
• Dependency Injection: Koin 4.0.0 for lightweight, clean modular injection.
• Local Database: Room 2.6.1 – automatically parses and populates the vocabulary database from CSV on the first launch, enabling high-performance offline access.
• Audio Control: Android's MediaPlayer integrated with local raw resources.
• Serialization: Kotlinx Serialization for type-safe JSON conversion.
• Unit Testing: JUnit 4 and Mockito for testing data sources and ViewModels.

---

🚀 Getting Started

📋 Prerequisites

• Android Studio Ladybug (2024.2.1) or newer.
• JDK 17 (required by Android Gradle Plugin 8.7.3).
• Android SDK: compileSdk 35 / targetSdk 36 / minSdk 24.

💻 Build & Run Locally

1. Clone the repository:

   git clone https://github.com/encorex32268/JPracticePublic.git
   cd JPracticePublic

2. Create a local configuration file local.properties in the root directory and specify your Android SDK path:

   sdk.dir=/path/to/your/android/sdk

3. Open the project in Android Studio.
4. Wait for Gradle Sync to complete, then click Run to launch the app on an emulator or physical device.

---

🇯🇵 日本語五十音 - 輕鬆學習日語基礎 (JPractice)

🤖 Google Play 下載連結： 日本語五十音

---

日本語五十音 (JPractice) 是一款專為日語初學者打造的現代化、高效且精美的五十音學習與測驗 Android 應用程式。

本專案採用 Clean Architecture (乾淨架構)、MVVM 設計模式、Jetpack Compose (Material 3) 與 100% 離線本地發音機制 開發，旨在展示生產等級 (Production-Ready) 的現代 Android 移動端開發最佳實踐。

Important

本應用程式完全不含任何廣告元件，提供乾淨、專注且純粹的學習環境。所有發音音訊檔皆內嵌於 App 本地資源包內，無需連網即可秒速播放，為使用者節省流量且隨時隨地皆可流暢學習。

---

📸 應用程式截圖 (Screenshots)

五十音圖與測驗

🏠 五十音首頁	⚙️ 測驗條件設定	✍️ 五十音測驗	❌ 答錯提示與解析

單字學習與測驗

📖 單字庫與發音	⚙️ 單字測驗設定	✍️ 單字測驗

---

✨ 重點功能特點 (Key Features)

• 🇯🇵 完整五十音對照
  • 收錄平假名與片假名的清音、濁音、拗音，字體清晰，點擊即可即時聆聽真人發音。
• ✍️ 自訂分段測驗 (Custom Quiz)
  • 使用者可依學習進度自訂測驗範圍（如：僅測驗平假名/片假名/全部混合；清音/濁音/拗音）。
  • 支援精細的「行數」測驗範圍篩選（如：僅練習「前幾行」或指定「第幾行」的假名），完美切合初學者進度。
• 📖 多元單字學習庫
  • 內建豐富的單字表，分為動詞、副詞、名詞、い形容詞、な形容詞等類別。
  • 提供單字與例句的平假名標注（Furigana）、羅馬拼音對照、真人發音以及單字拼寫測驗。
• 🔇 100% 離線本地發音
  • 核心假名與單字發音音檔全部內嵌於 res/raw，完全離線使用，無需載入等待，提供無縫發音反饋。
• 🎨 現代化 Material 3 設計
  • 採用 Jetpack Compose 打造 Material 3 響應式排版，搭配流暢的微動畫 (Micro-Animations) 與粉嫩和諧的配色，提升視覺舒適感。

---

🛠️ 開發架構與技術棧 (Architecture & Tech Stack)

本專案將業務邏輯與介面展示層嚴格分離，以確保代碼的可維護性、可測試性與可擴展性：

🏗️ 軟體架構：Clean Architecture

專案分為三大核心模組層：

1. Presentation 層：使用 MVVM (Model-View-ViewModel) 模式，利用 ViewModel 管理介面狀態 (State Flow)，並配合 Jetpack Compose 實現單向數據流 (UDF, Uni-directional Data Flow)。
2. Domain 層：包含專案純 Kotlin 的業務邏輯、Use Cases 與數據實體模型 (Entities)。
3. Data 層：負責數據持久化與音訊播發，包括 Room Database、SharedPreferences、CSV 檔案解析器 (ReadCSVFileUtils) 等實作。

🧰 核心技術棧

• UI 框架：Jetpack Compose (聲明式 UI) 搭配 Material 3 組件庫與 Compose Navigation。
• 依賴注入 (DI)：Koin 4.0.0，提供乾淨、輕量的模組化物件注入。
• 本地資料庫 (Database)：Room 2.6.1，首次啟動時自動解析 CSV 寫入單字庫，提供高效的離線存取。
• 音訊控制：Android MediaPlayer 整合本地 raw 資源檔播放。
• 序列化：Kotlinx Serialization，用於型別安全的 JSON 資料轉換。
• 單元測試：JUnit 4 & Mockito 框架實作數據源與 ViewModel 測試。

---

🚀 快速開始 (Getting Started)

📋 編譯要求

• Android Studio Ladybug (2024.2.1) 或更新版本。
• JDK 17 (Android Gradle Plugin 8.7.3 要求)。
• Android SDK compileSdk 35 / targetSdk 36 / minSdk 24。

💻 本地建置步驟

1. 複製本專案至本地：

   git clone https://github.com/encorex32268/JPracticePublic.git
   cd JPracticePublic

2. 建立本地配置檔案 local.properties 並指定您的 Android SDK 路徑：

   sdk.dir=/path/to/your/android/sdk

3. 使用 Android Studio 開啟本專案。
4. 等待 Gradle Sync 完成後，點擊 Run 即可在模擬器或實體裝置上運行專案！