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.

中文说明 · Releases · 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 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.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 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 里读日语时直接划选：获得简明中文或英文解释、贴合原文的词汇和语法，并把真正值得复习的内容按天保存。

三步开始

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