Universal UI Translator

by feifei
5
4
3
2
1
Score: 50/100

Description

Category: Customization & UI

The Universal UI Translator plugin intercepts interface text from core features and community plugins, sends it through a translation provider you configure and writes the translated text back into the UI. It covers command palette entries, context menus, settings panels and a DOM fallback for notices, status bar text, modals and custom views. It supports OpenAI compatible endpoints, DeepL, Google Cloud Translation, Azure Translator and custom HTTP endpoints, with local cache, bilingual or translated display modes, skip rules, glossary overrides and per plugin scope controls. The plugin also adds on demand translation for community plugin marketplace items and full marketplace detail panels instead of continuous automatic translation. It does not translate user content, WebWorker or iframe text, Canvas or WebGL surfaces and it is desktop only.

Reviews

No reviews yet.

Stats

4
stars
573
downloads
0
forks
49
days
7
days
7
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
0
total issues
0
open issues
0
closed issues
27
commits

RequirementsExperimental

  • A configured translation provider or custom HTTP translation endpoint

  • API credentials for the chosen provider unless using a local endpoint

Latest Version

7 days ago

Changelog

用自己的翻译 API 翻译 Obsidian 界面:核心、社区插件,以及社区插件市场本身。 Translate the Obsidian UI — core, community plugins, and the community-plugin browser itself — with your own translation API.

✨ 为什么选它 / Why

  • 🧩 社区插件全覆盖:命令面板、右键菜单、设置面板、弹窗通知——外加社区插件市场条目级的「译」按钮,点哪条译哪条,缓存命中零成本
  • 🌐 目标语言任意:默认简体中文,设置 → 基础 → 目标语言 可填 ja / zh-Hant / ko / fr 等任意语言代码;缓存按语言隔离,随时切换互不影响
  • 💰 零成本可行:DeepL/Google/Azure 免费额度足够覆盖界面文本量;接 Ollama 本地模型则完全免费、离线可用
  • 🔒 隐私优先:无遥测,唯一外发是你自己配置的翻译端点;笔记正文永不翻译;API Key 经系统钥匙串加密

🚀 推荐引擎 / Recommended provider — DeepSeek

  • 引擎选「OpenAI 兼容接口」,Base URL 填 https://api.deepseek.com,模型填 deepseek-v4.1-flash——快速经济,界面文本秒回,成本约几分钱
  • ⚠️ 记得打开「关闭思考模式」开关(API 配置页):V4 系列默认开启思考模式,不关的话每条短文本都会长篇推理——又慢又费 tokens
  • DeepSeek model deepseek-v4.1-flash works great here — just toggle ON "关闭思考模式" (disable thinking) in API settings, otherwise thinking mode burns tokens on every tiny UI string

落盘加固与专名保护:翻译结果不再因关闭 Obsidian 而丢失;市场页插件名/作者名保留原文;换模型不再全量重译(可选)。设计依据:文档/1022-1408-1.5迭代问题分析与设计_v1.0.md,真机实证:文档/1022-1427-1.5前置真机测试报告_v1.0.md。

Added

  • 卸载同步落盘(F1):onunload 改走 Node fs 同步写 + 原子 rename——真机实证旧版 void flush() 在强杀与优雅关闭下都来不及完成,翻译成功未落盘的译文即丢失;同步路径同时根治覆盖写一半崩溃的文件损坏窗口
  • 批次结算节流落盘(F2):批量队列结算归零且有脏数据时 5 秒节流落盘——"翻译完成→落盘"窗口从 30~60s 压缩到 ≤5s
  • 市场弹窗重开自动回写(F3):详情面板重渲染时自动跑 cache-only 回写(只查缓存与术语表,未命中不发任何 API)——翻译中途关弹窗后重开,已译内容自动呈现,无需重点按钮
  • 技术标识符形态过滤(G1):整串 kebab-case / snake_case(如 obsidian-git)不再送译
  • 市场条目专名保护(G2):条目卡片的插件显示名/作者名(1~4 个首字母大写词形态)跳过送译保留原文,便于按名搜索与对照;简介句子正常翻译;详情 README 不受影响
  • 宽松缓存键(B3,默认关):设置页缓存 Tab 新增「跨模型/引擎复用缓存」开关——开启后键退化为 原文+目标语言,换模型/引擎不再全量重译(真机实测一库 9 个模型键、8213 条重复副本);开启期间「清理失效条目」禁用

Changed

  • README 免费教程(火山方舟奖励计划,活动已结束)替换为低成本模型推荐:qwen-flash 首选(输入约 0.183 元/百万 tokens)+ DeepSeek 备选,价格为 2026-10 快照并附官方价格页链接
  • 测试 245 → 257(新增 flushSync 原子写/回落、宽松键、cacheOnly 零 API、标识符形态、专名跳过、自动回写)

README file from

Github

Universal UI Translator

用自己的翻译 API 翻译 Obsidian 核心与社区插件界面。 Translate Obsidian core and community plugin UI with your own translation API.

中文 · English

问题反馈 / Feedback:使用中遇到任何问题(翻译异常、功能建议、Bug)请发邮件至 [email protected]——请附上 Obsidian 版本、插件版本与控制台报错截图,便于定位。 Found a bug or have a suggestion? Email [email protected] — please include your Obsidian version, plugin version and any console errors.

GitHub release Build License: MIT

双语命令面板


中文

第一次接触 Obsidian?推荐阅读面向新手的详细图文说明:docs/使用说明.md

这是什么

Obsidian 社区插件生态以英文为主,汉化依赖插件作者自觉。本插件是一个界面文本中间件:拦截 Obsidian 核心与社区插件输出的界面文本,调用你自己配置的翻译 API 完成翻译,再按你的偏好写回界面——无需等待插件作者汉化。

插件本体不含任何翻译引擎或词库,翻译质量与成本由你选择的 API 决定。

功能特性

  • 四条拦截通道:命令面板(含核心命令)、右键菜单、设置面板、MutationObserver 全局兜底(Notice、状态栏、Modal、自定义视图)
  • 五种翻译引擎:OpenAI 兼容接口(含自定义 Base URL / 本地模型)、DeepL、Google Cloud Translation、Azure Translator、自定义 HTTP 端点(Ollama / LM Studio,零成本)
  • 合批高速翻译(v1.2):OpenAI 兼容通道把单行短文本编号合批(40 条/请求),首译请求数 ÷30+、token ÷5–8,核心界面全量首译从分钟级降到秒级;解析失败自动降级逐条,结果永远可靠
  • 本地缓存(升级不清空):内存 LRU + 磁盘 JSON 同一上限(默认 5 万条、可调至 20 万,磁盘另有 64MB 字节硬顶),键含原文 + 引擎 + 语言 + 模型——同一界面二次打开零 API 调用;v1.2 起 Obsidian / 插件升级不再清空缓存(文本未变即命中),按最近访问淘汰,另有 .bak 兜底副本(主文件损坏可恢复)
  • token 实测统计与费用(v1.3):直接采集 API 返回的 usage 字段(账单口径,含每请求 system prompt 开销)——主窗口状态栏常驻 ▲ 速率 · 今日 tokens · ≈费用,社区市场弹窗右下角同源徽标;用量页有会话速率/峰值、今日/本月费用(填入你的单价即显示)与近 30 天双口径图表
  • 市场翻译进度反馈(v1.2):「译」按钮显示确定型 已译/总数 计数,弹窗右下角悬浮进度条(多趟聚合、完成即淡出)——长 README 翻到哪一目了然
  • 三种显示模式:纯译文 / 双语对照 / 原文,随时切换,另有「临时显示原文/恢复译文」命令
  • 智能过滤:跳过代码、路径、URL、数字、已本地化文本;占位符保护 + 译后校验(占位符不一致的译文直接丢弃、不进缓存);嵌套重译防线已泛化至全部目标语言(v1.4)——译文含目标语言文字 ≥2 字符即拒绝送译,双语回写产物另设结构防线
  • 成本控制:100ms 批量聚合、全局真实在途并发限制(v1.2 起设置值=实际请求数)、单请求超时(可配置)、月度字符预算自动熔断;429 限流不计入熔断(v1.2),熔断期间状态栏常驻倒计时
  • 缓存治理(v1.1.9):缓存分页逐项写清"是什么 / 什么时候用 / 代价"——立即落盘、按当前引擎/语言/模型一键清理失效条目、磁盘文件实况、导出/导入共享
  • 作用域控制:核心/社区开关、插件白名单/黑名单、拦截器独立开关、自定义跳过正则与术语表(固定译法优先于缓存与 API)
  • 社区插件市场按需翻译(核心功能):列表条目与详情面板(README 全文)各有「译」按钮,点哪条译哪条,缓存命中零成本——v1.1.5 起市场默认不再自动全量翻译(滚动列表会持续消耗 API),逐条按需是唯一推荐路径
  • 费用透明:设置页逐项标注 API 消耗风险与量级估算;完整折算模型见下方「费用估算」专节
  • 目标语言任意:默认简体中文,可填 ja / zh-Hant / ko / fr 等任意语言代码,常用 12 语言快速下拉即选即存;缓存按语言隔离,随时切换互不影响
  • 插件界面语言(v1.4):跟随 Obsidian / 中文 / English 三档可选——英文界面为全量覆盖包(250 键),命令名、状态栏、设置页与错误消息全覆盖;默认跟随 Obsidian,中文默认体验零回归
  • 配置热生效:改配置即重置熔断并全量重扫界面,无需重启;落盘三保险(v1.5)——每批翻译结算后约 1~5 秒即写盘、退出 Obsidian 时同步落盘(正常关闭零丢失)、临时文件原子替换防写坏;崩溃/强杀最多丢最后几秒
  • 隐私优先:无遥测、无外发请求(除你配置的翻译端点);API Key 经 safeStorage 加密

安装

  • 官方社区插件目录(已上架):设置 → 第三方插件 → 社区插件 → 搜索「Universal UI Translator」
  • BRAT(beta 渠道):安装 BRAT 插件 → 「Add Beta plugin」→ 粘贴本仓库地址
  • 手动安装:将 main.js、manifest.json、styles.css 复制到 <库>/.obsidian/plugins/universal-ui-translator/

配置

  1. 打开 设置 → Universal UI Translator → API 配置 页
  2. 选择引擎并填入 API Key(加密存储于 secrets.bin,绝不写入 data.json)
  3. 点击「测试连接」——成功后拦截层自动激活
引擎 说明
OpenAI 兼容接口 推荐 DeepSeek:Base URL https://api.deepseek.com + 模型 deepseek-v4.1-flash,并打开「关闭思考模式」开关;默认 gpt-4o-mini;支持自定义 Base URL(如接本地 Ollama:http://localhost:11434/v1)
DeepL Free/Pro 端点自动识别(Free 版 Key 以 :fx 结尾);免费档 50 万字符/月
Google Cloud Translation API Key;语言覆盖最广;免费档 50 万字符/月
Azure Translator Key + Region;免费档 200 万字符/月
自定义端点 URL + 请求体模板 + 响应 JSONPath——Ollama / LM Studio / 任意本地模型,零成本

典型成本:接近零——各厂商免费额度足以覆盖界面文本量;本地模型仅费电。付费引擎下的精确估算见下节。

设置面板

费用估算(以 DeepSeek flash 为基准,2026-09-10 新定价)

DeepSeek flash 系列自 2026-09-10 12:00(北京时间)起的定价(每百万 tokens):

空闲时段 高峰时段(= 空闲 × 2)
输入(缓存命中) ¥0.02 ¥0.04
输入(缓存未命中) ¥1 ¥2
输出 ¥4 ¥8

折算模型(界面文本 → tokens):输入 tokens ≈ 英文字符数 / 4;输出 tokens ≈ 字符数 / 2.5(中文译文 1 token ≈ 1.5 汉字、长度约为原文 60%)。即每 1 万字符界面 ≈ 2,500 输入 + 4,000 输出 tokens → 高峰约 ¥0.037,空闲半价。

每个动作花多少钱(高峰 / 空闲):

动作 字符量 tokens(入+出) 费用
市场列表单条目「译」(条目右上角按钮) ≈150 38 + 60 < ¥0.001,可忽略
插件详情 README「译」(详情区顶端按钮) ≈4,000 1,000 + 1,600 ≈ ¥0.015 / ¥0.007
核心界面全量(一次性,之后走缓存) ≈8 万 2 万 + 3.2 万 ≈ ¥0.30 / ¥0.15
市场全列表自动翻译(默认关闭的高风险开关) ≈30 万/轮 7.5 万 + 12 万 ≈ ¥1.1 / ¥0.55 每轮

token 耗费速率:批量聚合窗口 100ms + 全局在途并发(默认 3、可调 5)+ 合批 40 条/请求(v1.2);一键翻译整篇 README(≈2,600 tokens)通常数秒完成。界面翻译不是持续流量——本地缓存命中即零请求,只有"第一次见到"的文本才消耗 tokens,且 v1.2 起 Obsidian / 插件升级不清空缓存(无周期性重译)。

怎么用到接近零成本:① 译文本地缓存,同一内容永不再发请求;② 设置页「月度字符预算」超限自动熔断;③ 术语表命中的词条不走 API;④ 用 Ollama 本地模型则完全免费、数据不出本机。

用量统计与缓存管理(v1.1.9 起,v1.3 实测口径)

「用量统计」分页(设置 → Universal UI Translator)回答"我到底调用了多少 API、烧了多少 tokens":

  • 双口径:v1.3 起 OpenAI 兼容通道直接记录 API 返回的 usage(账单口径实测,含每请求 system prompt 开销);字符折算估算(输入 ≈ 字符/4、输出 ≈ 字符/2.5)保留服务历史数据与非 token 计费引擎,图表可一键切换两种口径,悬停同显双数值
  • 本月汇总:送译条数、输入/输出字符、实测与估算 tokens(入/出分列)、按 DeepSeek 基准价折算的费用;填入自己的单价(API 配置页 输入价/输出价)后另显今日/本月实测费用
  • 会话实时:本会话 tokens / 送译条数 / 近 1 分钟与 5 分钟速率 / 峰值速率;主窗口状态栏常驻 ▲ 速率 · 今日 · ≈费用 段(10 分钟无活动自动隐藏),社区市场弹窗右下角有同源常驻徽标——独立窗口内也能盯住消耗
  • 近 30 天柱状图:每天一根堆叠条(下=输入、上=输出),鼠标悬停查看当天精确数值;另有「今日 / 近 7 日」摘要
  • 口径说明:缓存命中与术语表命中不消耗 API、不计入此统计;逐日明细自 v1.1.9 起记录(usage.json 向后兼容扩展,日桶保留近 62 天,月度预算判定口径不变)

「缓存」分页功能速查(设置页内每个功能均为"是什么 / 什么时候用 / 代价"三段式说明):

功能 是什么 什么时候用
启用本地缓存 译文持久化到 translation-cache.json,同一文本只付一次费 只有排查翻译异常时才需要关
缓存条目上限 内存=磁盘同一容量(默认 5 万,可调 1000–20 万;磁盘另有 64MB 硬顶),超出淘汰最久未用条目 市场 README 翻得多就往宽设——纯文本不占空间,上限太低会提前淘汰译文、重复消耗 API;调小立即生效
缓存统计 条数、命中率、磁盘文件实际大小、最后落盘时间 命中率越高越省钱
立即落盘 新译文先在内存,v1.5 起每批翻译结算后约 1~5 秒自动写盘、退出 Obsidian 时同步落盘(正常关闭零丢失)、原子替换防写坏,另有 .bak 兜底副本;点此立即写入磁盘 应急/图安心用——v1.5 起关机重启前不再需要手动点;崩溃/强杀最多丢最后几秒新译文
清理失效条目 删除与当前「引擎+语言+模型」不匹配的条目(缓存键含这三维,换模型后旧条目永不命中,纯占空间) 换过模型/引擎/目标语言之后点一次;v1.1.9 前的旧条目无模型标记,只能按引擎+语言判定
清空缓存 删除全部缓存译文并重置界面译态 译文异常(如嵌套乱码)排查、换术语表后重来;⚠️ 之后全部界面重译一遍(核心界面 ≈ ¥0.30 以内)
导出 / 导入 缓存与库根目录 JSON 文件互转(FR-12) 换机迁移、把译文词表分享给他人(对方导入后零成本复用)

翻译速度怎么调

v1.2 起 OpenAI 兼容通道已合批(单行短文本 40 条合一次请求),首译速度与 token 消耗大幅下降;仍觉得慢时按见效程度依次检查(都在设置页内):

  1. 打开「关闭思考模式」(API 配置页,见效最大):DeepSeek V4、豆包等模型默认先"思考"再输出,UI 短文本无需推理——关掉后响应快一倍不止,还省 tokens。模型选 turbo / flash 档,别用 pro 档
  2. 最大并发请求数调到 5(高级页):v1.2 起该值就是真实在途请求数(全局信号量统一封顶;旧版内层还藏了一个并发 3,设 5 实际是 15 路)。⚠️ 不要贪大:并发 10 容易打爆账号每分钟请求限额(HTTP 429)——v1.2 起 429 不再触发 10 分钟熔断(限流是背压不是故障),但仍会被服务商限速拖慢;看到 429 就降回 3。若真触发熔断,状态栏会常驻显示「熔断中 mm:ss」倒计时
  3. 批量聚合窗口保持 100(高级页):窗口是攒批去重的等待时间,调大(如 455)会让每批白等近半秒,十几批就多等好几秒;调大只能略微减少重复请求,对总字符消耗无影响
  4. 显示模式用「纯译文」(基础页):双语对照的 LLM 输出长度约为纯译文 2 倍,生成时间直接翻倍;需要对照时再临时切换

预期管理:首次翻译某篇内容慢是正常的(v1.2 合批后一篇插件 README 约 2,600 tokens、数秒完成);进缓存后再次打开零延迟,速度问题只存在于"初见"。若 Console 持续刷 404/429,先解决模型配置(未开通/不存在的模型名会一直失败重试、拖慢整体),再谈提速。

消耗随时可见(v1.3):状态栏常驻用量段(▲ 34 tok/min · 今日 1.2k tok · ≈¥0.03,10 分钟无活动自动隐藏);数字为 API 返回的实测 usage(账单口径)。想看到费用:到 设置 → API 配置 → token 单价(每百万)填入你所用模型的输入/输出价格即可;用量统计页还有会话速率、峰值与近 30 天双口径图表。

推荐配置一览:关闭思考模式 = 开 | 模型 = flash/turbo 档 | 批量窗口 = 100 | 并发 = 5 | 超时 = 30000 | 显示模式 = 纯译文

低成本模型推荐:几厘钱翻完全部界面

下述价格为 2026-10 快照,各家调价频繁,以官方价格页为准:阿里云百炼价格 / DeepSeek 定价。本插件核心界面全量翻译一次约 1 万 tokens,之后全部走缓存且升级不清空——按下列价格,一次全量翻译成本在分厘级。

首选:qwen-flash(阿里云百炼) —— 便宜、速度快、国内直连,UI 短文本翻译质量绰绰有余:

  • 价格快照:输入约 0.183 元/百万 tokens(缓存命中 0.073),输出约 1.468 元/百万——全量翻完一次约几厘钱;百炼新用户通常另有各模型限时免费额度(以官网为准)
  • 接入(OpenAI 兼容通道):设置 → Universal UI Translator → API 配置 → 引擎选 OpenAI 兼容接口
    • Base URL:https://dashscope.aliyuncs.com/compatible-mode/v1
    • API Key:百炼控制台创建
    • 模型:qwen-flash
    • 打开「关闭思考模式」——UI 短文本无需推理,关掉更快、更省 tokens

备选:DeepSeek(deepseek-chat,V4.1 Flash 档):

  • 价格快照:非高峰输入 $0.15 / 输出 $0.60 每百万 tokens(美元计价、分时段 + 缓存计价,缓存命中极便宜;高峰约翻倍);Base URL:https://api.deepseek.com;务必打开「关闭思考模式」

完全免费:本地 Ollama / LM Studio(数据不出本机);DeepL / Google / Azure 传统翻译引擎的免费档(见上方引擎表)。另外,经常换模型试探的用户建议打开设置里的「跨模型/引擎复用缓存」(v1.5 起)——默认每换一次模型同一界面会整体重译一遍,这是最容易忽视的用量放大器。

术语表:想固定某些词条的译法(比如特定插件名保留英文),在设置的术语表里加一条即可,命中词条不走 API。

安全与隐私

  • 无遥测、无分析、无外发请求(除你配置的翻译端点)
  • API Key 经 Electron safeStorage(操作系统钥匙串)加密存储为 secrets.bin,密文只能在本机解密——请勿将该文件纳入 Obsidian Sync / git 同步;换机后按设置页提示重新输入即可
  • 翻译缓存存于本地插件目录,可自由导出/导入
  • 所有原型劫持均做特征检测、可独立开关,并在卸载时完整还原(含实例级补丁)

已知限制

  • 不支持 Canvas/WebGL 渲染文本(如 Excalidraw 画布、Graph 关系图)
  • 不支持 WebWorker / iframe 内文本
  • 用户内容一律不译:笔记编辑器、阅读视图、文件名(文件管理器、标签页标题、快速切换器)、大纲、标签、悬浮预览、嵌入笔记、搜索摘录
  • 插件黑名单的边界:命令/菜单/设置通道严格生效;DOM 兜底通道无法识别文本归属,黑名单插件的自定义视图仍可能被翻译(可用跳过正则补充)
  • 仅桌面端(isDesktopOnly: true),本版本不支持移动端

开发

npm install
npm run build          # tsc 类型检查 + esbuild(刻意不做 minify)
npm test               # 257 个单元与集成测试
npm run test:coverage  # 核心模块行覆盖率 75.9%–100%

许可证

MIT,见 LICENSE。


English

What it does

Obsidian's community plugin ecosystem is mostly English-only, and localization depends on each plugin author. Universal UI Translator is a UI text middleware: it intercepts interface text from Obsidian core and community plugins, orchestrates translation through a translation API you configure, and writes results back to the UI — no waiting for plugin authors to localize.

The plugin ships no translation engine or glossary of its own. Translation quality and cost are determined by the API you choose; the plugin only standardizes interception, orchestration, caching, and write-back.

Features

  • Four interception channels: command palette (including core commands), context menus, settings panels, and a MutationObserver fallback for Notices, the status bar, modals and custom views
  • Five translation providers: OpenAI-compatible (incl. custom Base URL / local LLMs), DeepL, Google Cloud Translation, Azure Translator, and a fully custom HTTP endpoint (Ollama / LM Studio — zero cost)
  • Batched high-speed translation (v1.2): the OpenAI-compatible channel merges short single-line texts into numbered batches (40 per request) — first-time translation issues ÷30+ fewer requests and ÷5–8 fewer tokens; a full core-UI pass drops from minutes to seconds. Malformed batch responses auto-fall back to per-item requests, so results stay reliable
  • Local-first cache (survives upgrades): in-memory LRU + on-disk JSON under one shared cap (default 50k entries, adjustable up to 200k; 64 MB on-disk byte ceiling), keyed by text + provider + language + model — opening the same UI twice issues zero API calls. Since v1.2 Obsidian/plugin upgrades no longer invalidate the cache (unchanged text keeps hitting), eviction follows most-recent-use, and a .bak copy recovers from a corrupted file
  • Real token metering & cost (v1.3): captures the usage field returned by the API (billing basis, including per-request system-prompt overhead) — the main-window status bar shows ▲ rate · today · ≈cost, and the community-plugin browser popup carries the same live badge in its corner; the usage tab adds session rate/peak, today/month cost (enter your own per-million prices) and a dual-basis 30-day chart
  • Marketplace progress feedback (v1.2): the "译" button shows a deterministic done/total counter while translating, plus a floating progress bar in the popup window (multi-pass aggregate, fades on completion)
  • Three display modes: translated / bilingual (translation with original in brackets) / original, switchable anytime, plus a "temporarily show original / restore translation" command
  • Smart filtering: skips code, paths, URLs, numbers and already-localized text; placeholder protection with post-translation validation (mismatched placeholders are discarded, never cached); the nested re-translation guard now covers all target languages (v1.4) — text containing 2 or more characters of the target script is rejected, and bilingual write-back output is blocked by a structural rule
  • Cost controls: 100 ms batch aggregation, a global true in-flight concurrency limit (since v1.2 the setting equals actual requests in flight), per-request timeout (configurable), monthly character budget with automatic circuit-breaker; HTTP 429 no longer trips the breaker (v1.2) and an active breaker shows a live countdown in the status bar
  • Cache governance (v1.1.9): the cache tab explains every action in a what/when/cost format — manual flush, one-click purge of entries that no longer match the current provider/language/model, on-disk file size, export/import sharing
  • Scope control: core/community toggles, per-plugin whitelist/blacklist, per-interceptor switches, custom skip-regexes and a user glossary (fixed translations that bypass cache and API)
  • On-demand marketplace translation: a "译" button on each community-plugin item translates just that entry — cache hits cost zero API calls. Since v1.1.5 the marketplace no longer auto-translates while scrolling (that high-risk toggle ships off) — on-demand is the recommended path
  • Any target language: defaults to zh-CN; set ja / zh-Hant / ko / fr or any language code, with a quick dropdown of 12 common languages — the cache is keyed per language, switch anytime
  • Plugin UI language (v1.4): follow Obsidian / Chinese / English — the English UI is a full coverage pack (250 keys) spanning command names, the status bar, settings pages and error messages; defaults to following Obsidian, and the default Chinese experience is unchanged
  • Hot-applied settings: config changes reset the circuit breaker and rescan the rendered UI instantly — no restart needed. Triple flush safety (v1.5): each finished translation batch hits disk within ~1–5 s, quitting Obsidian flushes synchronously (clean exit loses nothing), and writes are atomic via temp-file rename; a crash loses at most the last few seconds
  • Privacy by design: no telemetry, no outbound calls except your configured translation endpoint; API keys encrypted with Electron safeStorage

Installation

  • Community plugin directory (listed): Settings → Community plugins → Browse → search "Universal UI Translator"
  • BRAT (beta channel): install the BRAT plugin → "Add Beta plugin" → paste this repository's URL
  • Manual: copy main.js, manifest.json, styles.css into <vault>/.obsidian/plugins/universal-ui-translator/

Configuration

  1. Open Settings → Universal UI Translator → API 配置
  2. Pick a provider and enter your API key (encrypted and stored in secrets.bin, never in data.json)
  3. Click 测试连接 — on success, interception activates automatically
Provider Notes
OpenAI-compatible Recommended: DeepSeek — Base URL https://api.deepseek.com + model deepseek-v4.1-flash with "关闭思考模式" toggled ON; default gpt-4o-mini; custom Base URL supported (e.g. http://localhost:11434/v1 for Ollama)
DeepL Free/Pro endpoint auto-detected (free keys end with :fx); 500k chars/month free
Google Cloud Translation API key; broadest language coverage; 500k chars/month free
Azure Translator Key + region; 2M chars/month free
Custom endpoint URL + request template + response JSONPath — Ollama / LM Studio / any local model, zero cost

Typical cost: zero — the free tiers of all major providers cover UI-text volumes, and local models cost only electricity.

Cost estimation (DeepSeek flash basis, 2026-09-10 pricing)

Rules of thumb (UI text → tokens): input tokens ≈ English chars / 4; output tokens ≈ chars / 2.5 (a Chinese translation is ~60% of the source length). That is, every 10k chars of UI ≈ 2,500 input + 4,000 output tokens ≈ ¥0.037 at peak, half that off-peak (DeepSeek flash pricing since 2026-09-10: input ¥1 / output ¥4 per million tokens off-peak, ×2 at peak).

Action Chars Cost (peak / off-peak)
Translate one marketplace list entry ≈150 < ¥0.001, negligible
Translate one plugin README ≈4,000 ≈ ¥0.015 / ¥0.007
Full core UI, one-time (then cached forever) ≈80k ≈ ¥0.30 / ¥0.15
Auto-translate the whole marketplace list (off by default) ≈300k/round ≈ ¥1.1 / ¥0.55 per round

How it stays near zero: ① translations are cached locally — the same text is never billed twice; ② the monthly character budget trips an automatic circuit-breaker; ③ glossary hits bypass the API entirely; ④ a local model (Ollama / LM Studio) is completely free and never leaves your machine. Since v1.2, Obsidian/plugin upgrades no longer invalidate the cache, so there is no periodic re-translation cost.

For users in China, the 中文 section above has cheap-model picks (qwen-flash ~¥0.18 per million input tokens; DeepSeek flash tier) — a full one-time UI translation costs fractions of a cent. Since v1.5, an opt-in "loose cache key" reuses translations across models/engines, so switching models no longer re-translates everything.

Usage stats & cache management (v1.1.9+, real token basis in v1.3)

  • The 用量统计 (Usage) tab answers "how much API have I actually used" on two bases: since v1.3 the OpenAI-compatible channel records the usage field returned by the API (billing-basis, exact — including per-request system-prompt overhead), while character-based estimates (input ≈ chars/4, output ≈ chars/2.5) remain for historical data and non-token providers. The 30-day chart toggles between bases and hovering shows both. Monthly totals cover calls, characters and tokens (measured + estimated); enter your own per-million prices in the API tab to see today/month measured cost. Session cards show live rate (1/5-minute windows) and peak, mirrored by the always-on status-bar segment and the badge inside the community-plugin browser popup. Cache and glossary hits cost no API calls and are not counted; daily detail is recorded from v1.1.9 onward (usage.json stays backward-compatible; day buckets are kept for 62 days; monthly-budget accounting is unchanged).
  • The 缓存 (Cache) tab documents every action in a what / when-to-use / cost format:
    • 缓存条目上限 — one shared memory+disk capacity (default 50k entries, adjustable 1k–200k; 64 MB disk byte ceiling). Translations are plain text and cheap to keep: set it wide so marketplace README translations are not evicted early and re-billed.
    • 立即落盘 (Flush now) — new translations live in memory; since v1.5 each finished batch auto-flushes within ~1–5 s, quitting Obsidian flushes synchronously (clean exit loses nothing), writes are atomic, and a .bak copy guards against corruption. The button is for peace of mind — no longer required before quitting; a crash loses at most the last few seconds.
    • 清理失效条目 (Purge stale entries) — deletes cache entries that no longer match your current provider + language + model. The cache key embeds all three, so after switching models the old entries can never hit again and only waste space. Entries written before v1.1.9 carry no model marker and are judged by provider + language only.
    • 清空缓存 (Clear) — wipes all cached translations and resets the UI translation state; everything retranslates once on next view (core UI ≈ ¥0.30).
    • 导出 / 导入 (Export / Import) — move the cache to/from a JSON file in the vault root for migration or sharing; the recipient reuses your translations at zero API cost.

Tuning translation speed

If translation feels slow, check these in order (all in the settings tabs):

  1. Turn on "关闭思考模式" (disable thinking) — the biggest win. Models like DeepSeek V4 / Doubao "think" before answering, and short UI text needs no reasoning; disabling thinking roughly halves latency and saves tokens. Prefer flash/turbo-tier models over pro-tier ones.
  2. Set max concurrency to 5 (Advanced tab): since v1.2 this number is the true count of in-flight HTTP requests (a global semaphore caps every provider; older versions secretly multiplied it by 3). ⚠️ Don't max it out: concurrency 10 easily trips your account's per-minute rate limit (HTTP 429) — since v1.2 a 429 no longer opens the 10-minute circuit breaker (rate limiting is back-pressure, not a fault), but the provider will still throttle you. Drop back to 3 if you see 429s; if the breaker does open, the status bar shows a live mm:ss countdown.
  3. Keep the batch window at 100 ms (Advanced tab): the window is how long the plugin waits to dedupe and merge texts into one batch; raising it (e.g. 455) makes every batch wait nearly half a second longer — a dozen batches means several wasted seconds — while only marginally reducing duplicate requests and not changing total characters sent.
  4. Use "纯译文" (translation-only) display mode (General tab): bilingual output roughly doubles LLM output length and generation time; switch to bilingual only when you need it.

Expectations: first-time translation of new content normally takes a moment (a plugin README ≈ 2.6k tokens, typically 2–5 s); once cached, reopening is instant — speed only matters for first encounters. If the console keeps logging 404/429, fix the model configuration first (an unavailable or unactivated model name retries forever and drags everything down).

Recommended: thinking off · flash/turbo-tier model · batch window 100 · concurrency 5 · timeout 30000 · translation-only mode.

Security & privacy

  • No telemetry, no analytics, no outbound requests except the translation endpoint you configure
  • API keys are encrypted via Electron safeStorage (the OS keychain) and stored as secrets.bin. The ciphertext can only be decrypted on the same machine — do not sync secrets.bin across devices (Obsidian Sync / git). If decryption fails (e.g. after syncing to a new machine), re-enter the key in settings
  • The translation cache lives locally in the plugin directory and can be exported/imported by you
  • All prototype hooks are feature-detected, individually switchable, and fully restored on unload (including instance-level patches)

Known limitations

  • Canvas / WebGL rendered text (e.g. Excalidraw canvas, Graph view) cannot be intercepted
  • WebWorker / iframe content is out of reach by design
  • User content is never translated: note editor, reading view, file names (explorer, tab titles, quick switcher), outline, tags, hover previews, embedded notes, and search excerpts
  • Blacklist boundary: strictly honored in command/menu/settings channels; the DOM fallback cannot attribute text to a plugin, so a blacklisted plugin's custom views may still be translated (use skip-regexes as a supplement)
  • Desktop only (isDesktopOnly: true); mobile is not supported in this release

Development

npm install
npm run build          # tsc type-check + esbuild (deliberately not minified)
npm test               # 257 unit & integration tests
npm run test:coverage  # core modules 75.9%–100% line coverage

License

MIT — see LICENSE.

Similar Plugins

info
• Similar plugins are suggested based on the common tags between the plugins.
Icon Shortcodes
5 years ago by AidenLx
Obsidian Plugin: Insert emoji and custom icons with shortcodes
Media DB Plugin
4 years ago by Moritz Jung
A plugin that can query multiple APIs for movies, series, anime, games, music and wiki articles, and import them into your vault.
User Plugins
4 years ago by mnowotnik
Allows user scripts to use plugin API
Ninja Cursor
4 years ago by vorotamoroz
Obsidian to Flomo
4 years ago by Xiaoyu Li
Quickly share content to Flomo.
DeepL
4 years ago by Till Friebe
DeepL for Obsidian.
Emoji Magic
4 years ago by simplgy
Makes it easier to add emojis using an improved keyword search
File Publisher
4 years ago by Devin Sackett
Auto Hide Cursor
3 years ago by Mo Ismat
A simple plugin for https://obsidian.md
Blur
3 years ago by @gapmiss
A plugin for creating obfuscated blocks of text in Obsidian.md
APIRequest
3 years ago by rooyca
Obsidian plugin that allows you to integrate API data into your notes with request caching, variable support, and precise JSON extraction.
Background Image
3 years ago by shmolf
Editor Width Slider
3 years ago by @MugishoMp
With this plugin you can set the line width of the editor in obsidian.
CSS Editor
3 years ago by Zachatoo
Edit CSS snippets in Obsidian.
Tokei
3 years ago by HiroMike
A simple clock for Obsidian
Auto Reading Mode
3 years ago by Kelvin Cao
Backlink Cache
3 years ago by mnaoumov
Retired. Use Advanced Metadata Cache, which carries this backlink cache.
Datetime Language Changer
3 years ago by Zetab_S
This is a Obsidian plugin that allows you to customize the language used for datetime formatting by changing moment.js's locale.
Canvas Card Background Remover
3 years ago by luxmargos
This Obsidian plugin allows you to make the background of cards transparent in the Canvas for specific embed types, including Image (png), Canvas, and even Markdown.
Additional Icons
3 years ago by Matthew Turk
Add additional iconsets to Obsidian
Full Screen Toggle
3 years ago by Donkey Pacific
Fullscreen toggle plugin across all platforms for Obsidian.
Font Size Adjuster
3 years ago by Ryota Ushio
An Obsidian.md plugin to adjust font size via commands.
Beautitab
3 years ago by Andrew McGivery
A plugin for Obsidian.MD that creates a customizable new tab view with beautiful backgrounds, quotes, search, and more.
Status Bar Organizer
3 years ago by Kacper Darowski
Arrange and hide status bar elements.
Tag Formatter
3 years ago by snsvrno
Configurable Obsidian plugin that hides parent tags.
Color cycler
3 years ago by Taylor Brennan
Plugin for Obsidian to dynamically change the accent color
Multilingual
3 years ago by leolazou
An plugin for Obsidian that translates note names to ease linking across many languages.
Dictionary translator
3 years ago by Grover
我可以帮助你翻译单词或句子,听新单词或句子的录音,甚至录下自己的发音,以内部链接的形式保存到你的笔记中。
Fontsource
3 years ago by Ayuhito
A plugin to load custom fonts from Fontsource into Obsidian.
Close Window When Empty
2 years ago by Taylor Jadin
Node Auto Resize
2 years ago by Boninall
Shrink pinned tabs
2 years ago by Nicolas Lœuillet
Obsidian plugin to shrink pinned tabs in order to save screen space
Iconic
2 years ago by Holo
Customize your icons and colors directly from the Obsidian UI, including tabs, files & folders, bookmarks, tags, properties, and ribbon commands.
Latex Render
2 years ago by jvsteiner
An Obsidian plugin that renders `label` code blocks to `<svg>` for viewing in notes. Make sure to bring your own command!
Unofficial Fabric Integration
2 years ago by Chasebank87
Integrate fabric by danielmiessler/fabric into Obsidian
OpenAPI Renderer
2 years ago by Sentiago
Integrate OpenAPI specification management into Obsidian with features for version control, visualization, editing, and easy navigation of API specs.
Hider
6 years ago by @kepano
Hide Obsidian UI elements such as tooltips, status, titlebar and more
Homepage
5 years ago by mirnovov
An Obsidian plugin that opens a specified note, canvas, or workspace on startup, instead of the most recent one.
File Explorer Markdown Titles
5 years ago by Dylan Elliott
Obsidian Plugin that adds the the markdown title within your notes to the file explorer
Zen Mode
2 years ago by paperbenni
Magiedit
2 years ago by Matteo Gassend
Theme Controller
2 years ago by Binaris
Set when and how the themes will be displayed
Backgroundset
2 years ago by daonali
similar as vscode background
Context Command Hider
2 years ago by Mara-Li
This plugin allows you to hide every command from the Obsidian's right-click context menu.
Explorer Colors
2 years ago by Scott Van der Zwet
Set cascading colors for files and folders in Obsidian.
Memodack
2 years ago by Pavlo Kobyliatskyi
Your second language memory tool
Papyrus
2 years ago by André Silva, Daniel Guerra, Diogo Ferreira, Eduardo Barrancos
Hide Commands in Menu
2 years ago by bomian98
Obsidian Plugin, hide different commands in different menus.
Collapsible Code Blocks
2 years ago by Bradley Wyatt
Obsidian Plugin that makes code blocks collapsible in reading and edit view as well as enabling scroll-able code blocks.
Data Fetcher
2 years ago by qf3l3k
Fetch data from multiple sources (REST APIs, RPC, gRPC, GraphQL) and insert results into notes.
Theme by Folder
a year ago by Jinmu Go
Automatically switch Obsidian themes based on the folder of the opened note
Monokakido Copilot
a year ago by NoHeartPen
Double press the Option key to search with Dictionaries by Monokakido.This plugin is not affiliated with MONOKAKIDO Co. Ltd. (JAPAN).
VaultAI
a year ago by Tharushka Dinujaya
An AI chatbot plugin for Obsidian using the Gemini API for note summarization, content generation, and more. Enhance your workflow with AI assistance like the Notion AI bot.
API Designer
a year ago by Ruveyda Yilmaz
A plugin for Obsidian that lets you design and document API endpoints visually without leaving your notes.
Hide Traffic Lights
7 months ago by Ben Phillips
Local REST API with MCP
5 months ago by Adam Coddington
A secure REST API and Model Context Protocol (MCP) server for your vault.
Excalidraw Extras
5 months ago by zsviczian
Companion Obsidian.md plugin hosting extra add-on optional features for the main Excalidraw-Obsidian plugin
Callout Studio
3 months ago by niv20
Callout Studio is the only callout plugin you'll ever need to download. It offers regular callouts, inline callouts, and callout headings. Plus, you can easily design your own custom styles!
Bible Reference
3 months ago by tim-hub
Take Bible Study notes easily in the popular note-taking app Obsidian, with automatic verse and reference suggestions.
Browser Note
3 months ago by fengshuzi
Obsidian plugin: localhost HTTP API for vault notes with a built-in browser UI.
Granola Meetings Simple Sync
3 months ago by philfreo
"Granola Meetings Simple Sync" Plugin for Obsidian
FleurPDF
2 months ago by JC5
Smart PDF reading and annotation plugin for Obsidian with AI-powered features
ICOR for Life - Interface
2 months ago by Paperless Movement S.L.
The vault's chrome in one place: hide the ribbon and Obsidian's own controls, and give any folder a colour, an icon and a label. Writes no CSS; the INKLINE theme draws it. Part of the ICOR for Life suite.
Qiaomu AI RSS
2 months ago by 向阳乔木
在 Obsidian 中阅读乔木 RSS、中文 AI 改写与翻译,并保存为 Markdown 笔记。
FleurEPUB
2 months ago by JC5
Advanced Metadata Cache
a month ago by Michael Naumov
Maintains the vault indexes that are otherwise rebuilt on every call, and answers the built-in lookups from them, so backlinks come from an index instead of a fresh scan of every note.