# 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)
---
## 🇬🇧 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`
---
## 🇯🇵 日本語
**さくら先生**は、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
```
---
## 🇨🇳 中文
**樱花老师 (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/).