Obsidian 插件汉化经验分享

谈到 obsidian，不能忽略的是他庞大的第三方社区插件。通过下载社区插件，我们可以为我们的库新增非常多的附加功能。众所周知，大部分插件都只有英文，例如插件的设置面板，或者是插件增加的右上角的提示等。如果你点进这篇文章，想必阅读中文对你来说比读英文更加轻松。

可行的汉化方法

方法一：直接在 main.js 中搜索插件中出现的英文然后替换为中文

优点：可以达到汉化的效果，且门槛较低，只需要你能够找到插件的 main.js 文件，能够使用有全局搜索功能的编辑器打开 main.js（例如 vscode），会全局搜索英文并且替换为中文。

缺点：每次更新插件时都得重新把英文替换为中文。并且无法实现插件的语言跟随 obsidian 设置的语言。

如果插件很久才更新一次，或者你觉得当前插件的功能已经足以满足你的需求且你后续不会再更新该插件，那么这个方法没啥毛病。但是如果你一看到插件更新了就想要更新，那么不建议使用这种方法。

方法二：使用第三方截图翻译软件

优点：使用方便，只需要下载一个具有截图翻译功能的软件就行，例如网易有道翻译、DeepL 翻译、quickadd 等。建议给截图翻译设置一个快捷键，随时都可以截图翻译。可以自己框选翻译的范围，避免了全文翻译的性能消耗和文字偏移。同时由于这是第三方软件，你在其他的地方也都可以使用，并不局限在 obsidian 中。

缺点：不是内置在 obsidian 中，需要手动点快捷键，需要手动框选范围，需要联网使用。翻译的质量取决于翻译软件，插件本身的专有名词可能翻译错误。

方法三：类似『沉浸式翻译』

沉浸式翻译是一款浏览器插件，可以一键将网页上的英文替换为中文，给用户沉浸式的翻译体验。它提供了多种翻译方式，例如直接替换英文为中文、在英文下方显示中文翻译、在英文下方显示有一定透明度的中文鼠标触碰去除透明度等。另外，沉浸式翻译还提供了 pdf, epub 等类型文件的翻译，效果也挺不错的。
个人觉得好用才介绍的，插件有付费功能，但是免费的功能对我来说已经足够。

优点：如果只是要汉化插件的设置面板，那么这个方法应该是很有效的，因为大部分插件的设置面板的样式都是类似的。

缺点：目前没有具体的实现了这个功能的插件，因此需要个人写一款在 obsidian 中使用的『沉浸式翻译』插件，对于个人能力有要求。所幸可以借助的项目还挺多的，例如 i18next, jquery-translate, translate.js。同时，如果借助了各个翻译平台的 api，那么用户需要联网才能使用。翻译的质量取决于翻译软件，插件本身的专有名词可能翻译错误。

方法四：彻底汉化插件 pr 提交

优点：一劳永逸，翻译的质量取决于翻译者，语言可随 obsidian 语言切换。

缺点：需要获得插件作者的同意，翻译过程比直接替换 main.js 中的插件文本多了许多准备工作。插件更新设置的话需要有人继续维护。

这种方法也是目前很多插件使用的方法，例如下载量稳居第一的 excalidraw, kanban, floating-toc 等插件都是使用的这种方法。具体汉化的步骤见下文。

汉化教程

下面的流程尽量写成白话文，旨在让门槛降低到会翻译文本即可汉化插件。但是至少你需要能够打开 GitHub 网站，知道如何找到插件的 GitHub 仓库。

准备工作

我将准备工作分为了五步，准备工作不比添加中文简单。

准备一：获得翻译资格

添加中文前需要先给插件作者询问是否愿意接收你为插件添加的中文，你需要打开想要翻译的插件的 Github 仓库，点击上方的 Issues，再点击右上角的 New issue 即可向插件作者提建议。

如果作者同意你为该插件添加中文，那么你添加好中文后可以给插件作者提交 pr，等待作者合并了你的 pr 后，该插件后续的版本都可以看到中文了，你也可以在该插件的 Contributers 中找到你的名字。一般给已经添加了其他语言的插件发申请比较容易通过。

如果作者拒绝了，那就没辙，可以选择其他汉化方式。如果你实在想插件语言跟随 obsidian 变换，那么还是可以继续往下操作的，只不过插件更新的话，新版本插件还需要重新汉化，无法一劳永逸

准备二：安装 vscode，git，npm

网上能搜索到很多安装教程，安装过程中没有什么坑，因此这里就不过多赘述。

准备三：下载插件源码

到你准备汉化的插件的 Github 仓库中，点击右上角的 fork 按钮，根据提示操作即可将插件仓库 fork 到你的 Github 仓库中，这一步是把插件源码从作者那边克隆了一份到你的 GitHub 中

下一步需要把我们复制的这份插件源码下载到本地，你可以使用 git 将插件源码克隆到本地，也可以直接用 vscode 提供的克隆功能（这种方法比较适合不了解 git 的人使用），可以在欢迎页面找到，也可以使用快捷键 ctrl shift p 打开命令面板找到。

你也可以选择直接在 GitHub 中下载你克隆的那份插件源码

准备四：安装插件所需依赖

打开项目：使用 vscode 打开刚刚下载好的插件源码：右键下载的插件源码的文件夹，点击『通过 Code 打开』。
npm install：点击 vscode 上方的『终端 => 新建终端』，输入 npm install 即可自动安装所需依赖。可以理解为插件里面需要用到的一些东西没放在源码里面，需要你下载下来他才可以用，例如你随便打开一个源码中的文件，应该会出现很多报错。安装完依赖以后他们就不报错了。

npm run dev：构建插件，在刚刚的终端中继续输入 npm run dev，等待片刻会有提示告诉你“构建完成，你可以看看变化”类似的英文（具体不记得是啥了）。有的插件做的比较高级，他会让你选择构建后的 main.js 存放在哪里（例如 dataview, kanban），根据英文提示输入一个测试库的路径即可。

准备五：配置测试库

找到编译后的 main.js 文件。一般他会出现在几个地方：
1. 直接放在插件源码的根目录中，你在左侧的目录中找找看就行，如果是这种的话就比较麻烦，因为你需要手动新建一个测试库，然后每次修改完源码把构建好的 main.js 复制到测试库中。
2. 放在他设置好的测试库中，例如 home tab 插件。如果是这种，你需要找到他的测试库。可以在源码的根目录中找到 esbuild.config.mjs 文件，在里面找到一项 outfile，后面跟着的就是构建的 main.js 存放的位置，也就是测试库的位置。
在 obsidian 中打开你的测试库

正式汉化

一、新建翻译文件夹

一般插件都会有一个叫作 src 的文件夹，在这个文件夹中新建一个文件夹 lang（如果没有，则需询问作者将带有翻译内容的文件放在何处），然后在这个文件夹中新建以下图片中展示的文件和文件夹，他们代表了不同的语言（这不代表我们需要翻译所有语言），先不用在里面添加内容。helpers.ts 文件与 locale 文件夹同级。（如果不想手动创建，可以找一个有翻译语言文件夹的插件，下载那个插件的源码，再将这些文件夹复制过来）

解释一下这些文件，helpers.ts 相当于中转站，里面的内容是固定的（导出了一个函数 t() 用于根据语言转换文本为各个语言）。locale 文件夹中的文件存放的就是各种语言的翻译了。

把下面这段代码复制到 helper.ts 文件中，不需要做修改。我们需要修改的是 locale 文件夹中的各个文件。

import { moment } from "obsidian";
import ar from "./locale/ar";
import cz from "./locale/cz";
import da from "./locale/da";
import de from "./locale/de";
import en from "./locale/en";
import enGB from "./locale/en-gb";
import es from "./locale/es";
import fr from "./locale/fr";
import hi from "./locale/hi";
import id from "./locale/id";
import it from "./locale/it";
import ja from "./locale/ja";
import ko from "./locale/ko";
import nl from "./locale/nl";
import no from "./locale/no";
import pl from "./locale/pl";
import pt from "./locale/pt";
import ptBR from "./locale/pt-br";
import ro from "./locale/ro";
import ru from "./locale/ru";
import tr from "./locale/tr";
import zhCN from "./locale/zh-cn";
import zhTW from "./locale/zh-tw";

const localeMap: { [k: string]: Partial<typeof en> } = {
  ar,
  cs: cz,
  da,
  de,
  en,
  "en-gb": enGB,
  es,
  fr,
  hi,
  id,
  it,
  ja,
  ko,
  nl,
  nn: no,
  pl,
  pt,
  "pt-br": ptBR,
  ro,
  ru,
  tr,
  "zh-cn": zhCN,
  "zh-tw": zhTW,
};

const locale = localeMap[moment.locale()];

export function t(str: keyof typeof en): string {
  return (locale && locale[str]) || en[str];
}

接下来修改 locale 文件夹中的各个文件。主要需要修改的文件为 en.ts, zh-cn.ts 和 zh-tw.ts。分别代表插件的英文、简体中文和繁体中文。

先复制下面这段代码，放到 locale 文件夹中的所有文件中，然后替换语言名为各自的语言

// 语言名，需要替换为下方表格中的对应内容

export default {};

下表是不同语言文件开头放的注释

文件名	语言
ar.ts	`// العربية`
cz.ts	`// čeština`
da.ts	`// Dansk`
de.ts	`// Deutsch`
en.ts	`// English`
en-gb.ts	`// British English`
es.ts	`// Español`
fr.ts	`// français`
hi.ts	`// हिन्दी`
id.ts	`// Bahasa Indonesia`
it.ts	`// Italiano`
ja.ts	`// 日本語`
ko.ts	`// 한국어`
nl.ts	`// Nederlands`
no.ts	`// Norsk`
pl.ts	`// język polski`
pt-br.ts	`// Português do Brasil` `// Brazilian Portuguese`
pt.ts	`// Português`
ro.ts	`// Română`
ru.ts	`// русский`
tr.ts	`// Türkçe`
zh-cn.ts	`// 简体中文`
zh-tw.ts	`// 繁體中文`

二、添加中文翻译

接下来开始在 en.ts, zh-cn.ts 和 zh-tw.ts 文件中添加翻译。

翻译其实是一个映射，把键 key 替换成 value，因此不同语言需要使用相同的 key 值，然后 value 是各自语言的对应翻译。比如 excalidraw 插件所选用的 key 值为大写英文。为了不更多修改插件本身的源码，我们直接以所需翻译的英文作为 key，这样我们只需要添加 value 即可。

首先找到我们需要翻译的内容，这里以插件的设置面板举例。

想要找到设置的面板，你可以用 vscode 的全局搜索（快捷键 ctrl shift f 或者直接点击左边栏第二个搜索图标），搜索 display() 或者是 extends PluginSettingTab，搜索结果一般位于 settings.ts / main.ts / ...SettingTab.ts 文件中。这个 PluginSettingTab 就代表插件的设置面板，display 则是设置面板中展示的内容。如果还是找不到，直接搜索插件设置面板中的英文。