# LLM Translator
功能特性 •
快速开始 •
推荐配置 •
使用指南 •
其他翻译服务 •
Windows 注意事项 •
常见问题 •
开发
一款基于本地大模型驱动的 Obsidian 划词翻译插件，支持 PDF 和 Markdown 文件的实时翻译。
---
## 功能特性
### 📌 多源翻译支持
- **本地大模型（Ollama）** — 隐私安全，离线可用，无调用限制
- **云端 API（OpenAI 兼容格式）** — 接入 DeepSeek、OpenRouter 等服务商
- **Google 翻译 / Bing 翻译** — 无需配置，一键切换
### 📄 多格式文档支持
- **PDF 文档** — 默认支持，选中文本自动翻译
- **Markdown 文档** — 在设置中开启"全局"模式后支持
### 🎯 智能交互
- 选中文本自动弹出翻译窗口
- 侧边栏翻译面板，支持手动输入
- 复制译文 / 重试翻译 / 一键切换语言
- 自定义翻译 Prompt，满足专业需求
### 🌐 多语言界面
- 自动跟随 Obsidian 系统语言
- 支持简体中文 / English 界面
### ✏️ 原生 PDF 高亮注释
- **持久化高亮** — 写入标准 PDF 注释，跨 PDF 阅读器可见
- **5 种颜色** — 黄、红、蓝、绿、紫，可配置默认颜色
- **高亮批注** — 点击高亮可添加备注，随 PDF 文件保存
- **切换与撤销** — 再次点击移除高亮，Cmd+Z / Ctrl+Z 撤销
---
## 快速开始
```bash
# 1. 安装 Ollama（macOS / Linux）
curl -fsSL https://ollama.com/install.sh | sh
# 2. 拉取翻译模型（推荐 HY-MT2-1.8B）
ollama pull RogerBen/HY-MT2-1.8B:latest
# 3. 安装插件后，在设置中选择 Local LLM
# 填入端口 http://localhost:11434 和模型名称
# 点击测试验证连接
```
> 💡 **Windows 用户**：请从 [Ollama 官网](https://ollama.com/) 下载安装包，安装后 Ollama 自动在后台运行。
### 安装插件
通过 Terminal 下载并安装：
```bash
# 创建插件目录
mkdir -p YourVault/.obsidian/plugins/llm-translator
# 下载 Release 文件
curl -sL https://github.com/KimFischer99/Obsidian-LLM-Translator/releases/download/0.3.0/main.js \
-o YourVault/.obsidian/plugins/llm-translator/main.js
curl -sL https://github.com/KimFischer99/Obsidian-LLM-Translator/releases/download/0.3.0/manifest.json \
-o YourVault/.obsidian/plugins/llm-translator/manifest.json
curl -sL https://github.com/KimFischer99/Obsidian-LLM-Translator/releases/download/0.3.0/styles.css \
-o YourVault/.obsidian/plugins/llm-translator/styles.css
```
将 `YourVault` 替换为你的 Obsidian 仓库路径。安装后重启 Obsidian，在 **设置 → 社区插件** 中启用 LLM Translator。
---
## 推荐配置
插件安装后，请按以下配置填写：
### 常规设置
| 设置项 | 推荐值 |
|--------|--------|
| 翻译范围 | 全局 |
| 自动翻译选中文本 | 开启 |
| 启用阅读器划词弹窗 | 开启 |
### 服务设置
| 设置项 | 推荐值 |
|--------|--------|
| 翻译服务 | Local LLM |
| 本地模型端口 | `http://localhost:11434` |
| 模型名称 | `hy-mt2-1.8b-q4:latest` |
| 源语言 | Auto |
| 目标语言 | 简体中文 |
### 高级设置
| 设置项 | 推荐值 |
|--------|--------|
| 最大选区长度 | 5000 |
| 选区触发延迟 | 350 毫秒 |
| 请求超时 | 30000 毫秒 |
| Top K | 20 |
| Top P | 0.6 |
| Repeat Penalty | 1.05 |
| Num Predict | 4096 |
---
## 使用指南
### 基本操作
1. **自动翻译** — 选中 PDF 或 Markdown 文本，翻译弹窗自动出现
2. **侧边栏** — 点击左侧工具栏语言图标，打开右侧翻译面板
3. **手动翻译** — 在侧边栏输入文本，点击 Translate 按钮
### 翻译范围设置
- **全局** — PDF 和 Markdown 文件均可划词翻译
- **仅 PDF** — 只在 PDF 文件中启用（默认）
### 侧边栏功能
- **翻译服务切换** — 快速切换 Local LLM / Cloud API / Google / Bing
- **语言选择** — 设置源语言和目标语言
- **Auto-Trans** — 开启/关闭自动翻译
- **Copy** — 复制原文（Raw）、译文（Result）或全部（Both）
- **Clear** — 清空当前翻译记录
### 自定义 Prompt
在 **设置 → 高级 → 自定义 Prompt** 中修改翻译提示词：
```
Translate the following academic text. Preserve technical terminology,
citations, and formulas. Output only the translation.
```
---
## 其他翻译服务
### 云端 API（OpenAI 兼容格式）
支持任意兼容 OpenAI 格式的 API：
| 配置项 | 说明 |
|--------|------|
| API 地址 | 服务商提供的接口地址 |
| API Key | 服务商分配的密钥 |
| 模型名称 | 服务商支持的模型标识 |
### Google 翻译 / Bing 翻译
无需任何配置，在翻译服务下拉菜单中直接选择即可使用。
> ⚠️ 免费翻译服务存在调用频率限制，大量使用建议切换至本地模型或云端 API。
---
## Windows 注意事项
### Ollama 安装
- 从 [Ollama 官网](https://ollama.com/) 下载 Windows 版安装包
- 安装后自动在后台运行，端口与 macOS 相同：`http://localhost:11434`
- 如遇连接问题，检查 Windows 防火墙是否阻止了本地连接
### 路径格式
- URL 路径使用正斜杠 `/`：`http://localhost:11434`（正确）
- 不要使用反斜杠：`http://localhost:11434\`（错误）
---
## 常见问题
### 测试连接失败？
1. 确认 Ollama 已启动（任务栏应有 Ollama 图标）
2. 在浏览器访问 `http://localhost:11434` 确认服务正常
3. 检查是否有其他程序占用了 11434 端口
### 翻译弹窗不显示？
- 确认已启用"自动翻译选中文本"和"启用阅读器划词弹窗"
- 尝试重启 Obsidian
### Markdown 文件无法翻译？
- 将"翻译范围"设置为"全局"
---
## 开发
```bash
# 安装依赖
npm install
# 开发模式（监听文件变化）
npm run dev
# 生产构建
npm run build
```
构建后将 `main.js`、`manifest.json`、`styles.css` 复制到：
```
YourVault/.obsidian/plugins/llm-translator/
```
---
## 许可
MIT License © 2026