zotero/translators · 上手攻略

  • 仓库：zotero/translators
  • 链接：https://github.com/zotero/translators
  • 分类：学术写作 / 文献管理 / 元数据抓取
  • 作者：spark
  • 更新：2026-08-21

是什么

zotero/translators 是 Zotero 官方维护的翻译器（translator）仓库——它是 Zotero 文献管理工具生态里"网页抓取 / 格式互转 / 标识符查询"三件能力的中央实现。每个 translator 是一个独立的 JavaScript 文件，由 Zotero Connector 在浏览器侧或 Zotero 桌面端在运行时加载。

如果你见过 Zotero 浏览器插件的图标在期刊网站、Amazon、YouTube、JSTOR 等页面亮起，让图标亮起 + 把条目抓进库的就是 translator；如果你用过"从 .bib 导入 / 把库导出成 RIS"，跑的就是 import / export translator；如果你在 DOI / PMID / arXiv ID 上右键"Retrieve Metadata for…"，触发的是 search translator。

仓库本身是 Zotero 主项目（zotero、zotero-connectors）的附属子仓，日常由官方 bot 与社区贡献者共同维护。

解决什么问题

学术用户日常有三类"格式问题"：

  1. 从网页抓元数据：很多期刊主页、Amazon 详情页、机构知识库没有标准化的 OAI / Dublin Core，但 Zotero 能识别，因为有人为该站写了一份网页翻译器。
  2. 不同文献管理工具之间迁移：EndNote、RefWorks、Mendeley、纯文本 BibTeX、RIS、CSL JSON 之间互转。translator 仓库包含一整套 import / export translator。
  3. 基于标识符批量补全：拿到一堆 DOI / PMID / arXiv ID，希望一键回填标题、作者、期刊、卷期页——这是 search translator 的活（如 DOI Content、Crossref REST、PubMed、arXiv）。

单独写一个站点的抓取脚本当然能解决（1），但社区需要一个集中维护 + 自动分发 + 测试覆盖的地方，这就是这个仓的角色。

快速"上手"

⚠️ 注意：这里的"上手"不是"npm install 一下就能跑"——translator 仓是给 Zotero 客户端读取的脚本库，最终用户通常不需要直接操作它。

用户视角：保持 translator 自动更新

Zotero 默认会自动从中央仓更新 translator（数据目录的 translators/ 子目录）。多数场景下你什么都不用做。如果你想强制刷新：

  • 桌面端：菜单 Edit → Preferences → Advanced → Files and Folders 打开数据目录，定位 translators/，删掉某个 .js 文件后重启 Zotero，会触发重新拉取。
  • 浏览器 Connector：在扩展设置里点"Update Translators"。

贡献者视角：从 fork 到本地调试

按官方文档，贡献流程是：

  1. Fork zotero/translators，克隆到本地。
  2. 安装 Scaffold（Zotero 提供的 translator 开发工具）：按 Scaffold 文档 装好后，它会让你指向刚才克隆的目录。
  3. 用 Scaffold 新建 translator、改 metadata、跑测试。
  4. 提 PR 到主仓。官方 bot 会跑 translator 测试套件，并把结果反馈到 PR。

核心用法

四类 translator

按 Zotero 官方文档，translator 分为四种，互相可组合：

类型 用途 例子
Web 从网站抓条目（浏览器 Connector 主用） IEEE Xplore、Springer Link、CNKI、Amazon
Import 从文件导入条目到 Zotero BibTeX、RIS、Refer、CSA
Export 从 Zotero 导出到文件 BibTeX、RIS、CSL JSON、Note HTML
Search 给一个标识符回填元数据 DOI Content、Crossref REST、PubMed、arXiv、ISBN

一个 translator 可以同时属于多类，例如 RIS.js 同时是 import + export，arXiv.js 既是 web 也是 search。大多数 web translator 只做 web。

一个 translator 文件的三个段

按官方结构约定，每个 .js 文件固定三段：

  1. JSON metadata 头：声明 translatorID（GUID，唯一且不可变）、label、creator、target、minVersion、priority 等；
  2. JavaScript body：必须根据 translator 类型实现顶层函数（detectWeb / doWeb / doImport / doExport / doSearch 等）；
  3. var testCases = ...; 末尾附 JSON 测试用例数组。

⚠️ 不要手写 translatorID；点 Scaffold 的「Generate」让工具生成 GUID，一旦发布就不能换（Zotero 用它做 translator 的自动更新与跨 translator 调用）。

target 字段的细节

  • 对 web translator：target 是 JS 正则（匹配页面 URL），比如 ^https?://(www\.)?example\.com/。只匹配域时记得末尾加 /，Zotero 会自动去掉代理后再传给你。
  • 对 import：target 是文件扩展名（不带点），比如 BibTeX 是 bib。
  • 对 export：target 是导出文件的扩展名。
  • 空 target 的 web translator（如 DOI translator）会匹配所有网页，但通常 priority 数字很高（数字越小越优先），只在没有更具体的 translator 命中时才出场。

优先级与冲突

当多个 web translator 都匹配同一个 URL，priority 数字最小者胜出。如果你想让自己的 translator 在某站优先被选中，记得给它一个低 priority 数（同时遵守现有约定，避免覆盖核心站点）。

多 translator 协作

一个 web translator 抓到页面后，可以调用另一个 translator 处理它的中间产物。典型例子：

某个图书馆的网页 translator 先下载 MARCXML，再调用 MARCXML import translator 解析成 Zotero item，最后做一次站点特化的字段修正。

这种"translator-of-translator"模式让复杂站点也能复用通用解析逻辑。

Scaffold 不仅是个脚手架

按 README 与官方文档，Scaffold 还负责：

  • 管理 metadata（增删改字段）；
  • 创建/更新/运行 test case；
  • 跑 translator test framework；
  • 把改动打包成符合规范的 PR。

即便你只是改一个老 translator 的元数据，也建议走 Scaffold，避免手工编辑破坏字段约束。

典型适用场景

  1. 日常学术用户：基本不用碰这个仓库；只要 Zotero 自动更新开着，它就是透明的。
  2. 高校 / 机构 IT：想给自家 IR（机构知识库）写一份抓取脚本——直接照一个现成 web translator 改。
  3. 跨工具迁移：需要把 EndNote 库迁出——找到对应的 EndNote import / Refer / RIS / Refer/BibIX import translator 即可。
  4. 批量补全元数据：手上有一堆只有 DOI 的条目，新建条目时选 DOI Content 即可触发 search。

坑与注意

  • 不要直接编辑 translators/ 数据目录：Zotero 启动时若发现本地版本与中央不一致，会自动覆盖。
  • GitHub Issues 不接受 bug 报告：README 明说 Zotero 不用 GitHub Issues 处理 bug / 功能请求 / 支持问题——所有这些都走 Zotero Forums。Confirmed bug 才会由开发者创建 issue。
  • 不要复用 / 伪造 GUID：translatorID 是公开承诺，乱用会让 Zotero 把你的代码误识别成别的 translator，从而触发诡异的更新覆盖。
  • 不要在 metadata 里写网页没暴露的信息：官方文档建议站点方先把元数据按 Exposing Metadata 的方式暴露出来，再考虑写 translator；靠扒 JavaScript 渲染的页面通常很脆弱。
  • 测试是必须的：每个 translator 都带 testCases，跑不通过的 PR 通常会被拒。
  • translator 错误是公开的：recent translator errors 列出了真实失败案例，修某个站点的"图标不亮 / 抓不全字段"问题，可以从这里挑一个高频错误来修。

与同类对比

维度 zotero/translators Mendeley Web Importer EndNote Import Filters 直接写 Python 爬虫
维护方 Zotero 官方 + 全球社区 Mendeley（已并入 Elsevier） Clarivate 自己
维护节奏 高（bot + 贡献者） 中 中-低 看你
测试框架 ✅ translator test framework ❌ ❌ 自己写
自动分发到客户端 ✅ Zotero 自带 ✅ Mendeley 自带 ⚠️ EndNote 安装
覆盖站点广度 极高（数千站点） 中 中（侧重 EndNote 兼容性） 任意
学术格式互转 ✅ BibTeX / RIS / CSL JSON / Refer 等 ⚠️ 主要支持 Mendeley 自身格式 ⚠️ EndNote 风格 自己实现
适合"为新站点写抓取" ✅ ❌ ❌ ✅（更灵活但要自己兜底）

一句话推荐结论

绝大多数用户只要保持 Zotero 自动更新就行；只有当你需要"给一个新站点写抓取"或"批量以标识符补全元数据"时，这个仓库才是你直接面向的入口——那时走 Scaffold、按测试驱动、不要伪造 GUID。

参考链接（已核验）：

  • https://github.com/zotero/translators
  • https://www.zotero.org/support/dev/translators
  • https://www.zotero.org/support/dev/translators/coding
  • https://www.zotero.org/support/dev/translators/scaffold
  • https://www.zotero.org/support/dev/translators/testing
  • https://zotero-translator-tests.s3.amazonaws.com/index.html
  • https://www.zotero.org/support/dev/exposing_metadata