Japanese Reading Assistant
zhangyicong58 downloadsOCR a selected PDF region locally, then translate Japanese with contextual vocabulary and concise, color-linked grammar notes.
- Overview
- Scorecard
- Updates9
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.
Start in three steps
- Install the plugin, choose Chinese or English under Explanation language, then choose a model in Settings → Japanese Reading Assistant.
- Use local Ollama, or a cloud OpenAI-compatible API (DeepSeek is prefilled).
- Hold Ctrl 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 | Alt + 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.
Place all three files in:
<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/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 -NoProfile -ExecutionPolicy Bypass -File .\tools\setup-paddle-ocr.ps1The 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 Alt 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 Ctrl while selecting |
| OCR an Obsidian PDF region | Hold Alt and drag |
| Open the manual input assistant | Alt + M |
| 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.
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 © 2026 Yicong Zhang
中文说明
在 Obsidian 里读日语时直接划选：获得简明中文或英文解释、贴合原文的词汇和语法，并把真正值得复习的内容按天保存。
三步开始
- 安装插件后，进入“设置 → 日语阅读助手”，先选择“中文”或“English”解释语言，再配置一个解析模型。
- 选择本地 Ollama，或填写云端 OpenAI 兼容 API（默认值适用于 DeepSeek）。
- 在编辑器、实时预览或阅读视图中按住 Ctrl 划选日文。
到这里就已经可以读 Markdown 文本。PDF OCR 默认关闭，只有需要在 PDF 图片上框选时才需要额外配置。
能做什么
| 阅读动作 | 得到的结果 |
|---|---|
| 划选单词或短语 | 翻译、假名、原形、词性和必要用法 |
| 划选句子 | 一份统一译文，以及共享该译文的词汇页与语法页 |
| 复习句子 | 少量可背词汇、句子主干和最多 4 个关键语法点 |
| 点击“保存到学习笔记” | 以日期归档的紧凑 Markdown 记录，不写精确时间 |
| 需要 PDF 内容 | Alt + 拖框 → OCR 提取正文 → 进入同一套句子解析 |
弹窗支持固定、拖动、缩放和复制；语法片段会和原句中对应位置以颜色关联。
安装
Obsidian 社区插件
当插件条目出现在你的客户端后，在“设置 → 第三方插件 → 浏览”中搜索完整英文名： Japanese Reading Assistant，安装后启用即可。
手动安装
从对应版本的 GitHub Release 下载：
main.js
manifest.json
styles.css
放入：
<Vault>/.obsidian/plugins/japanese-reading-assistant/
重新加载 Obsidian 后，在“第三方插件”中启用插件。
BRAT 测试版
在社区插件列表显示前，可以通过 BRAT 添加仓库：
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（可选）
普通划词、阅读视图和 Alt + M 手动输入都不需要 OCR。 如需在 Obsidian 内置 PDF 阅读器上框选，进入“设置 → 日语阅读助手 → PDF OCR（可选）”，选其中一种：
PP-OCRv5（本机 CPU，推荐）：不会占用 Ollama 的显存。从本仓库下载 Source code (zip) 并解压，在解压目录运行：
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 中按住 Alt 拖框即可识别。OCR 只负责提取文字，翻译、词汇和语法仍由上方配置的文本模型处理。
快捷方式与隐私
| 动作 | 默认方式 |
|---|---|
| 解析可选中的日文 | 按住 Ctrl 划选 |
| OCR PDF 局部 | 按住 Alt 拖框 |
| 打开手动输入助手 | Alt + M |
| 保存结果 | 弹窗中的“保存到学习笔记” |
本插件没有遥测，不会上传整篇笔记或整个 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。
npm ci
npm run check
npm run check 会执行严格 TypeScript 检查、单元测试和生产构建。GitHub Actions 会从已提交源码构建发布资产。
许可证
MIT © 2026 Yicong Zhang