# Japanese Reading Assistant

> Select Japanese in Obsidian, get a clear explanation directly in Chinese or
> English with vocabulary and grammar, then save useful results to a compact daily study note.

[![Latest release](https://img.shields.io/github/v/release/Normanchine/obsidian-japanese-reading-assistant?display_name=tag&sort=semver)](https://github.com/Normanchine/obsidian-japanese-reading-assistant/releases/latest)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Obsidian 1.11.5+](https://img.shields.io/badge/Obsidian-1.11.5%2B-7c3aed)](https://obsidian.md)

[中文说明](#中文说明) · [Releases](https://github.com/Normanchine/obsidian-japanese-reading-assistant/releases) · [Issues](https://github.com/Normanchine/obsidian-japanese-reading-assistant/issues)

## Start in three steps

1. Install the plugin, choose **Chinese** or **English** under **Explanation language**, then choose a model in **Settings → Japanese Reading Assistant**.
2. Use local **Ollama**, or a cloud **OpenAI-compatible API** (DeepSeek is prefilled).
3. Hold <kbd>Ctrl</kbd> and select Japanese in an editor, Live Preview, or Reading view.

That is enough for everyday Markdown reading. PDF OCR is deliberately optional:
configure it only if you want to select an image region in a PDF.

## What it does

| When you read | What you get |
| --- | --- |
| Select a word or phrase | Direct Chinese or English meaning, reading, dictionary form, part of speech, and a concise note |
| Select a sentence | One translation shared by vocabulary and grammar views |
| Review a sentence | Source-backed vocabulary, sentence structure, and up to four key grammar points |
| Save a result | A compact Markdown record under that day's heading, without timestamps |
| Need PDF text | <kbd>Alt</kbd> + drag → OCR extracts text → the same sentence analysis flow |

The non-modal popup can be pinned, moved, resized, and copied from. Grammar
fragments are color-linked to their position in the original sentence.

## Install

### Community plugins

When the listing is available in your client, search for **Japanese Reading
Assistant** under **Settings → Community plugins → Browse**, then install and enable it.

### Manual installation

Download `main.js`, `manifest.json`, and `styles.css` from the matching
[GitHub Release](https://github.com/Normanchine/obsidian-japanese-reading-assistant/releases).
Place all three files in:

```text
<Vault>/.obsidian/plugins/japanese-reading-assistant/
```

Reload Obsidian and enable **Japanese Reading Assistant** in Community plugins.

### BRAT beta

Add this repository to [BRAT](https://github.com/TfTHacker/obsidian42-brat):

```text
https://github.com/Normanchine/obsidian-japanese-reading-assistant
```

## Model configuration

### Explanation language

Choose **Chinese** or **English** in Settings. The selected language controls
the interface, saved study-note labels, and—most importantly—the system prompt:
the model explains Japanese directly in that language rather than translating
through Chinese or English first. Existing installations keep Chinese after the
upgrade; a fresh installation defaults to the device language. The default
study-note path also follows the explanation language (`Japanese Study/Reading
Notes.md` for English), while a custom path is never overwritten.

| Option | Best for | What to enter |
| --- | --- | --- |
| Ollama | Local and private use | An Ollama address (default `http://127.0.0.1:11434`) and an installed chat model |
| Cloud API | A managed remote model | API key, `/chat/completions`-compatible address, and model name |

Use **Test current model** after configuration. The default Ollama model name is
`qwen3-8b-nothink:latest`; choose any installed text model that reliably returns structured JSON.

## Optional PDF OCR

Open **Settings → Japanese Reading Assistant → PDF OCR (optional)** and choose one path:

- **PP-OCRv5 (local CPU, recommended)** — does not occupy Ollama GPU memory.
  Download this repository's **Source code (zip)**, open PowerShell in the
  extracted folder, and run:

  ```powershell
  powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\setup-paddle-ocr.ps1
  ```

  The script creates an isolated Python 3.11 environment and installs PP-OCR.
  Select PP-OCRv5 in settings and paste the absolute path to
  `tools\start-paddle-ocr.ps1`. It starts only when you initiate PDF OCR or retry it.

- **Ollama vision model** — choose this if you already have a compatible local
  vision/OCR model. Enter its model name; Python and PP-OCR are not needed.

In an Obsidian PDF, hold <kbd>Alt</kbd> and drag a region. OCR extracts text only;
translation, vocabulary, and grammar use your configured text-analysis model.

## Shortcuts

| Action | Default |
| --- | --- |
| Analyze selectable Japanese text | Hold <kbd>Ctrl</kbd> while selecting |
| OCR an Obsidian PDF region | Hold <kbd>Alt</kbd> and drag |
| Open the manual input assistant | <kbd>Alt</kbd> + <kbd>M</kbd> |
| Save a finished result | **Save to study note** in the popup |

## Privacy and permissions

The plugin has no telemetry and never uploads an entire vault or note.

| Component | Data sent | Destination |
| --- | --- | --- |
| Ollama analysis | Current selection and the fixed analysis prompt | Your configured Ollama endpoint |
| Cloud analysis | Current selection and the fixed analysis prompt | Your configured OpenAI-compatible endpoint |
| PDF OCR | Only the image region you explicitly draw | Your configured local PP-OCR or Ollama vision endpoint |

- Filenames, vault paths, surrounding note content, and full vault contents are not sent.
- PDF images are not saved by the plugin; cloud API keys use Obsidian Secret Storage.
- PP-OCR is disabled until configured. The plugin starts only the exact PowerShell
  script path you provide and never installs OCR dependencies by itself.
- **Copy translation** writes to the system clipboard only after you click it;
  the plugin never reads clipboard content.

## Boundaries and development

- Desktop-only: optional PP-OCR integration starts a Windows process.
- Supports the Markdown editor, Live Preview, Markdown Reading view, and visible
  page canvases in Obsidian's built-in PDF view.
- PDF OCR does not support EPUB, Canvas, or third-party iframe readers. Zoom small print before selection.

```powershell
npm ci
npm run check
```

`npm run check` runs strict TypeScript checks, unit tests, and a production build.
Release assets are created by GitHub Actions from committed source.

## License

[MIT](LICENSE) © 2026 [Yicong Zhang](https://github.com/Normanchine)

---

## 中文说明

> 在 Obsidian 里读日语时直接划选：获得简明中文或英文解释、贴合原文的词汇和语法，并把真正值得复习的内容按天保存。

### 三步开始

1. 安装插件后，进入“设置 → 日语阅读助手”，先选择“中文”或“English”解释语言，再配置一个解析模型。
2. 选择本地 **Ollama**，或填写云端 **OpenAI 兼容 API**（默认值适用于 DeepSeek）。
3. 在编辑器、实时预览或阅读视图中按住 <kbd>Ctrl</kbd> 划选日文。

到这里就已经可以读 Markdown 文本。PDF OCR 默认关闭，只有需要在 PDF 图片上框选时才需要额外配置。

### 能做什么

| 阅读动作 | 得到的结果 |
| --- | --- |
| 划选单词或短语 | 翻译、假名、原形、词性和必要用法 |
| 划选句子 | 一份统一译文，以及共享该译文的词汇页与语法页 |
| 复习句子 | 少量可背词汇、句子主干和最多 4 个关键语法点 |
| 点击“保存到学习笔记” | 以日期归档的紧凑 Markdown 记录，不写精确时间 |
| 需要 PDF 内容 | <kbd>Alt</kbd> + 拖框 → OCR 提取正文 → 进入同一套句子解析 |

弹窗支持固定、拖动、缩放和复制；语法片段会和原句中对应位置以颜色关联。

### 安装

#### Obsidian 社区插件

当插件条目出现在你的客户端后，在“设置 → 第三方插件 → 浏览”中搜索完整英文名：
**Japanese Reading Assistant**，安装后启用即可。

#### 手动安装

从对应版本的 [GitHub Release](https://github.com/Normanchine/obsidian-japanese-reading-assistant/releases) 下载：

```text
main.js
manifest.json
styles.css
```

放入：

```text
<Vault>/.obsidian/plugins/japanese-reading-assistant/
```

重新加载 Obsidian 后，在“第三方插件”中启用插件。

#### BRAT 测试版

在社区插件列表显示前，可以通过 [BRAT](https://github.com/TfTHacker/obsidian42-brat) 添加仓库：

```text
https://github.com/Normanchine/obsidian-japanese-reading-assistant
```

### 配置模型

### 解释语言

在设置中选择“中文”或“English”。该选项同时控制界面、学习笔记栏目，以及最关键的模型提示词：模型会直接使用所选语言解释日语，不会先生成中文或英文再进行二次翻译。旧用户升级后会保持中文；首次安装则按设备语言预选。英文默认学习笔记路径为 `Japanese Study/Reading Notes.md`；已经自定义过的路径不会被改动。

| 方案 | 适合谁 | 需要填写 |
| --- | --- | --- |
| Ollama | 希望在本地运行、注重隐私 | Ollama 地址（默认 `http://127.0.0.1:11434`）和已安装的文本模型 |
| 云端 API | 使用托管大模型 | API Key、兼容 `/chat/completions` 的地址、模型名 |

配置完成后点击“测试当前模型”。默认 Ollama 模型名为
`qwen3-8b-nothink:latest`；也可以填写任何能够稳定输出结构化 JSON 的已安装文本模型。

### PDF OCR（可选）

普通划词、阅读视图和 <kbd>Alt</kbd> + <kbd>M</kbd> 手动输入都不需要 OCR。
如需在 Obsidian 内置 PDF 阅读器上框选，进入“设置 → 日语阅读助手 → PDF OCR（可选）”，选其中一种：

- **PP-OCRv5（本机 CPU，推荐）**：不会占用 Ollama 的显存。从本仓库下载 **Source code (zip)** 并解压，在解压目录运行：

  ```powershell
  powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\setup-paddle-ocr.ps1
  ```

  脚本会创建独立 Python 3.11 环境并安装 PP-OCR。完成后，在插件设置中选择 PP-OCRv5，并填写 `tools\start-paddle-ocr.ps1` 的绝对路径。它只会在你发起 PDF OCR 或手动重试时启动，不会随 Obsidian 启动。

- **Ollama 视觉模型**：若你已经安装兼容的本地视觉/OCR 模型，只需选择该引擎并填写模型名，不需要 Python 或 PP-OCR。

在 PDF 中按住 <kbd>Alt</kbd> 拖框即可识别。OCR 只负责提取文字，翻译、词汇和语法仍由上方配置的文本模型处理。

### 快捷方式与隐私

| 动作 | 默认方式 |
| --- | --- |
| 解析可选中的日文 | 按住 <kbd>Ctrl</kbd> 划选 |
| OCR PDF 局部 | 按住 <kbd>Alt</kbd> 拖框 |
| 打开手动输入助手 | <kbd>Alt</kbd> + <kbd>M</kbd> |
| 保存结果 | 弹窗中的“保存到学习笔记” |

本插件没有遥测，不会上传整篇笔记或整个 Vault。只会发送当前选中文字与固定提示词给你配置的 Ollama 或云端地址；PDF OCR 只发送你主动框选的一小块图片。文件名、Vault 路径、周边笔记内容不会发送，OCR 图片也不会被保存。云端 API Key 使用 Obsidian Secret Storage 保存，不写入 `data.json`。

PP-OCR 默认关闭；插件只会启动你明确填写的那一份 PowerShell 脚本，不会自行下载或安装 OCR 依赖。“复制译文”仅在你点击后写入剪贴板；插件不会读取剪贴板。

### 边界与开发

- 仅支持桌面版；可选 PP-OCR 集成需要启动 Windows 进程。
- 支持 Markdown 编辑器、实时预览和 Markdown 阅读视图。
- PDF OCR 仅支持 Obsidian 内置 PDF 的可见页面画布，不支持 EPUB、Canvas 或第三方 iframe 阅读器；小字请先放大 PDF。

```powershell
npm ci
npm run check
```

`npm run check` 会执行严格 TypeScript 检查、单元测试和生产构建。GitHub Actions 会从已提交源码构建发布资产。

### 许可证

[MIT](LICENSE) © 2026 [Yicong Zhang](https://github.com/Normanchine)