193 lines
7.6 KiB
Markdown
193 lines
7.6 KiB
Markdown
# Sakura Sensei 🌸 - AI Japanese Tutor
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
**Sakura Sensei** is an immersive, all-in-one Japanese learning platform powered by Google's latest Gemini models. It provides a personalized tutor, realistic roleplay scenarios, custom reading/listening materials, and creative tools to make learning Japanese engaging and effective.
|
||
|
||
[English](#english) | [日本語](#japanese) | [中文](#chinese)
|
||
|
||
---
|
||
|
||
<a name="english"></a>
|
||
## 🇬🇧 English
|
||
|
||
### ✨ Features
|
||
|
||
* **Tutor Dojo (Chat):**
|
||
* Free chat with Sakura (AI Tutor) using `gemini-3-pro-preview` (Reasoning) or `gemini-2.5-flash`.
|
||
* **Voice Interaction:** Real-time Speech-to-Text (STT) and high-quality Text-to-Speech (TTS).
|
||
* **Thinking Mode:** Visualize the AI's reasoning process for complex grammar explanations.
|
||
* **Share:** Export chat history as Text, File, or Image (screenshot).
|
||
* **Reading Hall:**
|
||
* Generates custom reading lessons based on your topic and JLPT level (Beginner N5 - Advanced N1).
|
||
* Includes vocabulary lists, grammar analysis, and translations.
|
||
* **Contextual Tutor:** Ask questions specifically about the generated text.
|
||
* **Listening Lab:**
|
||
* AI-generated conversations and monologues with comprehension quizzes.
|
||
* Audio playback with speed controls and transcript toggles.
|
||
* **Roleplay (Speaking):**
|
||
* Practice realistic scenarios (Cafe, Hotel, Immigration, etc.).
|
||
* **AI Feedback:** Receive instant scoring on pronunciation, fluency, and grammar corrections.
|
||
* **Creative Atelier:**
|
||
* **Paint:** Generate images using `imagen-4.0` to visualize vocabulary.
|
||
* **Dream Video:** Generate short videos using `veo-3.1` (requires specific API access).
|
||
* **Toolbox:**
|
||
* **Scanner (OCR):** Upload or snap photos of Japanese text for instant analysis and study notes.
|
||
* **Translator:** Text and Image translation with audio support.
|
||
* **Data Management:**
|
||
* Local storage for history (Chat, Reading, Listening, OCR).
|
||
* Backup and Restore functionality (JSON).
|
||
|
||
### 🚀 Getting Started
|
||
|
||
1. **Clone the repository:**
|
||
```bash
|
||
git clone https://github.com/yourusername/sakura-sensei.git
|
||
cd sakura-sensei
|
||
```
|
||
|
||
2. **Install dependencies:**
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
3. **Set up API Key:**
|
||
* Get your API key from [Google AI Studio](https://aistudio.google.com/).
|
||
* Create a `.env` file in the root directory:
|
||
```env
|
||
VITE_API_KEY=your_gemini_api_key_here
|
||
```
|
||
* *Alternatively, you can enter the API Key directly in the app's Settings menu.*
|
||
|
||
4. **Run the app:**
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
### 🛠 Tech Stack
|
||
|
||
* **Frontend:** React 19, TypeScript, Vite
|
||
* **Styling:** Tailwind CSS, Lucide React (Icons)
|
||
* **AI Integration:** `@google/genai` SDK
|
||
* **Models Used:**
|
||
* Text/Reasoning: `gemini-3-pro-preview`, `gemini-2.5-flash`
|
||
* Audio: `gemini-2.5-flash-preview-tts`
|
||
* Vision/OCR: `gemini-2.5-flash`
|
||
* Image Gen: `imagen-4.0-generate-001`, `gemini-2.5-flash-image`
|
||
* Video: `veo-3.1-fast-generate-preview`
|
||
|
||
---
|
||
|
||
<a name="japanese"></a>
|
||
## 🇯🇵 日本語
|
||
|
||
**さくら先生**は、Googleの最新Geminiモデルを搭載した没入型の日本語学習プラットフォームです。文法解説、ロールプレイ、読解・聴解練習など、あらゆる学習ニーズに対応します。
|
||
|
||
### ✨ 主な機能
|
||
|
||
* **学習道場 (チャット):**
|
||
* `gemini-3-pro-preview` を活用した高度な推論能力を持つAIチューターとの会話。
|
||
* 音声入力・音声再生対応。思考モード（Thinking Mode）でAIの考え方を可視化。
|
||
* チャット履歴の画像共有機能。
|
||
* **読書の間:**
|
||
* トピックと難易度（N5〜N1）を指定して、オリジナルの読み物を生成。
|
||
* 単語リスト、文法解説、翻訳付き。テキストについてAIに質問可能。
|
||
* **聴解ラボ:**
|
||
* リスニング練習用の会話スクリプトとクイズを自動生成。
|
||
* 音声再生、スクリプトの表示/非表示切り替え。
|
||
* **会話道場 (ロールプレイ):**
|
||
* カフェ、駅、入国審査などのリアルなシナリオで会話練習。
|
||
* 発音、流暢さ、文法ミスに対する即時フィードバック機能。
|
||
* **アトリエ:**
|
||
* 画像生成 (`imagen-4.0`) や動画生成 (`veo-3.1`) で学習を視覚的にサポート。
|
||
* **ツールボックス:**
|
||
* **スキャナー (OCR):** カメラや画像から日本語テキストを抽出し、解説を生成。
|
||
* **翻訳機:** テキスト・画像の翻訳と音声再生。
|
||
* **設定・データ:**
|
||
* 学習履歴のローカル保存とバックアップ/復元機能。
|
||
|
||
### 🚀 始め方
|
||
|
||
1. **リポジトリのクローン:**
|
||
```bash
|
||
git clone https://github.com/yourusername/sakura-sensei.git
|
||
```
|
||
|
||
2. **依存関係のインストール:**
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
3. **APIキーの設定:**
|
||
* [Google AI Studio](https://aistudio.google.com/) でAPIキーを取得してください。
|
||
* `.env` ファイルを作成するか、アプリ内の「設定」メニューからキーを入力します。
|
||
|
||
4. **起動:**
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
---
|
||
|
||
<a name="chinese"></a>
|
||
## 🇨🇳 中文
|
||
|
||
**樱花老师 (Sakura Sensei)** 是一个基于 Google Gemini 模型的全能型 AI 日语学习助手。它集成了对话练习、阅读生成、听力训练和实时纠错功能，为您提供沉浸式的日语学习体验。
|
||
|
||
### ✨ 主要功能
|
||
|
||
* **学习道场 (Tutor Chat):**
|
||
* 与 AI 导师自由对话，支持 `gemini-3-pro` 深度推理模式。
|
||
* 支持语音输入 (STT) 和高质量语音朗读 (TTS)。
|
||
* 支持将对话记录导出为图片、文本或文件。
|
||
* **阅读室:**
|
||
* 根据您感兴趣的主题和 JLPT 等级 (N5-N1) 生成阅读文章。
|
||
* 自动提取词汇表、语法点和翻译。支持针对文章内容的提问。
|
||
* **听力实验室:**
|
||
* 生成包含理解测验的听力对话脚本。
|
||
* 支持音频播放控制和脚本隐藏/显示。
|
||
* **对话道场 (Roleplay):**
|
||
* 在真实场景（如便利店、机场、酒店）中进行角色扮演。
|
||
* AI 会对您的发音、流利度和语法进行打分并提供建议。
|
||
* **创意工作室:**
|
||
* 使用 AI 生成图片或视频来辅助记忆单词和场景。
|
||
* **实用工具:**
|
||
* **扫描仪 (OCR):** 拍照识别日语文本，生成学习笔记。
|
||
* **翻译机:** 支持文本和图片翻译，带发音功能。
|
||
* **数据隐私:**
|
||
* 所有聊天和学习记录均存储在本地浏览器中 (LocalStorage)。
|
||
* 支持数据的备份与恢复 (JSON 格式)。
|
||
|
||
### 🚀 快速开始
|
||
|
||
1. **克隆项目:**
|
||
```bash
|
||
git clone https://github.com/yourusername/sakura-sensei.git
|
||
```
|
||
|
||
2. **安装依赖:**
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
3. **配置 API Key:**
|
||
* 前往 [Google AI Studio](https://aistudio.google.com/) 获取 Gemini API Key。
|
||
* 在项目根目录创建 `.env` 文件，或直接在应用“设置”中输入 Key。
|
||
|
||
4. **运行应用:**
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
MIT License.
|
||
|
||
Powered by [Google Gemini API](https://ai.google.dev/).
|