阅读 1804

前端技术翻译 - 从 Acorn.js 的 README 看阅读英文技术文档的障碍

前言

我一直在思考对于一份纯英文的文档, 以中文为母语的我们究竟如何理解或者如何去翻译, 或者说阅读英文文档的障碍在哪? 词汇么? 我们有道, 语法? 不像一些文学著作, 英文文档并没有特别复杂的语法, 因为最近想搞个代码分析器, 需要一个解析器来帮忙, 我在 webpack 的依赖中看到了这个项目 Acorn, 先不说后面关于使用 Acorn 实现代码分析的那个项目吧, 我试着对 README 做了翻译, 然后我发现了一些问题 😑

Acorn.js / README.md 翻译内容

简介

Acorn 是一个完全用 JavaScript 编写的精巧的高效的 JavaScript 语法解析器

就这一行原文是 A tiny, fast JavaScript parser, written completely in JavaScript. 直接翻译就成了 "一个小巧, 快速的 JavaScript 解析器, 完全用 JavaScript 编写" 我不知道老外看原文是什么感觉, 翻译过来有点像广告

包结构

仓库中包含三个主要的 Package

  • acorn: 主解析器
  • acorn-loose: 一个 error-tolerant 解析器(高容错)
  • acorn-walk: 语法树的 walker & worker

这一部分的问题主要是对 acorn-loose 的解释 error-tolerant 我想来想去只能翻译成高容错...

关于 acorn-walk 的 walker 你完全无法在中文翻译中找到这个词的具体含义, 如果用中文解释, 这个 walker 是对语法树的每个节点进行操作, 递归的或者迭代的进行操作, 就像沿着树走路, 带有遍历的含义, 但是又缺少了 work 的含义, 因此中文不好搞啊... 想来想去只能英文了

插件开发模式

第一遍翻译

Acorn is designed to support plugins which can, within reasonable bounds, redefine the way the parser works. Plugins can add new token types and new tokenizer contexts (if necessary), and extend methods in the parser object. This is not a clean, elegant API—using it requires an understanding of Acorn's internals, and plugins are likely to break whenever those internals are significantly changed. But still, it is possible, in this way, to create parsers for JavaScript dialects without forking all of Acorn. And in principle it is even possible to combine such plugins, so that if you have, for example, a plugin for parsing types and a plugin for parsing JSX-style XML literals, you could load them both and parse code with both JSX tags and types.

Acorn 在设计上支持在合理的范围内定义插件, 以便于重新定义解析器的工作方式. 插件可以添加新的词法和词法分析器(如果有必要的话), 并且在解析器对象上扩展新的方法, 这听起来不是个干净优雅的 API, 使用它你必须对 Acorn 的内部非常了解, 另外插件很有可能崩溃, 每当这些内部内容发生重大变更时. 但即便如此, 我想这依然是一种行之有效的方式, 通过这种方式, 当我们想为 JavaScript 某种方言创建一种解析器, 就不需要复刻整个 Acorn, 在原则上, 我们甚至只需要将一些插件组合起来, 如果你愿意的话, 比如有一个插件是用来解析类型, 另一个插件用来解析 JSX 风格的 XML 标记, 你可以同时读取他们, 并将其解析成 JSX tags 和 类型

这部分就比较有意思了, 第一遍翻译下来, 我觉得我是完全遵循了原文的内容, 然而通读一遍就会觉得很别扭, 总感觉像个机器人...可能这就是机翻的本质吧, 没有情感, 没有灵魂

Acorn 通过插件来重新定义解析器的工作方式, 利用插件, 我们可以添加新的词法和词法分析器, 也可以添加自己想要的方法来扩展解析器, 不过这些都是通过一个不太干净优雅的 API 来实现的, 这意味着使用这个 API 对于开发者而言必须对 Acorn 的内部实现非常了解, 并随时要做好插件不可用的准备, 尤其是当内部实现发生重大变更的时候, 但即便如此, 这种方式依然是非常有必要的, 通过这种方式我们可以灵活组合插件来实现一个 JavaScript DSL 解析器, 比如对于 JSX 和 Types 用两个插件就能搞定.

于是我对以上中文内容进行了重组, 读起来就像个人了

然后第二段我试着用有道翻译翻译了下结果是这样的

A plugin is a function from a parser class to an extended parser class. Plugins can be used by simply applying them to the Parser class (or a version of that already extended by another plugin). But because that gets a little awkward, syntactically, when you are using multiple plugins, the static method Parser.extend can be called with any number of plugin values as arguments to create a Parser class extended by all those plugins. You'll usually want to create such an extended class only once, and then repeatedly call parse on it, to avoid needlessly confusing the JavaScript engine's optimizer.

然后我发现了另一个问题, 就是同样是中文, 同样是类似机器翻译的没有情感的结果, 我看自己翻译的内容感觉是一个一个字, 但是看有道翻译的内容, 我横看竖看, 这些内容在脑子里都是一张图, 类似一大块没有联系的文字

这个自我检测, 让我意识到通过手写或者手打出来的字在大脑中的留下的痕迹还是不太一样的, 但本着无感情机翻自己干的效率太低, 于是我想做另一个实验, 如果我直接对有道翻译的文字进行重组会对我理解英文原文产生什么影响呢?

于是我试着对有道翻译的结果进行了深入的理解, em...., 并对于机翻做了微调

插件是一个从解析器类到扩展解析器类的函数。可以通过简单地将插件应用到解析器类(或者其他插件已经扩展的版本)来使用插件。但是这里有点小尴尬, 从语法上讲, 当你使用多个插件的时候,Parser.extend 这个静态法法可能会随着任意数量的插件值作为参数去创建通过这些插件扩展得到的 Parser class 而被调用, 你通常应该只创建这样的扩展类一次, 并且通过它重复进行解析, 以避免对 JavaScript 引擎优化器的不必要的干扰

一如既往的没有感情, 但是第一句我是真看不懂, 于是我结合了下面的示例进行重组

const {Parser} = require("acorn")

const MyParser = Parser.extend(
  require("acorn-jsx")(),
  require("acorn-bigint")
)
console.log(MyParser.parse("// Some bigint + JSX code"))
复制代码
module.exports = function noisyReadToken(Parser) {
  return class extends Parser {
    readToken(code) {
      console.log("Reading a token!")
      super.readToken(code)
    }
  }
}
复制代码

插件其实是个函数, 包含了一个从 Parser 继承下来的类, 使用插件非常简单, 可以通过 Parser.extend 方法来集成你需要的插件, 不过比较尴尬的是, 如果你要使用多个插件, Parser.extend 会被反复调用, 建议最好是把相关插件合并到一起, 以避免对 JavaScript 引擎优化器不必要的干扰

这里其实会有一些疑惑, 关于 Parser.extend 的建议, 我觉得我需要进一步深入源码才能理解作者的意图

后话

我试着总结阅读英文技术文档的流程

  • 原文 → 机翻文(如果是非人肉机翻需要手工纠正)
  • 机翻文 → 可读文(可读未必可理解)
  • 可读文 → 可理解文(对于部分可读存疑的内容需要进行更深入的了解, 从而重新整理编程可理解的内容)

这个流程和我们通常认为的阅读障碍有很大不同, 我们通常认为阅读英文技术文档的障碍

  • 词汇
  • 语法
  • 英文综合水平

但实际上

  • 机翻可以解决词汇问题, 提供高效的机翻文, 即便你英文水平很高, 依然需要先机翻再理解, 考虑大多数人的英文水平, 词典机翻的效率远高于你自己, 因此词汇不是障碍
  • 关于语法, 文档中的语法普遍不复杂, 机翻足以解决, 因此语法也不是障碍
  • 英文综合水平, 具有专业英语水平的人也无法翻译这些内容, 看过很多翻译书的人应该有这种体会.

因此, 真实的阅读障碍

  • 技术概念词汇的积累程度
  • 机翻文对照原文快速纠正的能力
  • 对于机翻问的语言提炼能力, 提炼到可读可理解的能力

所以阻碍阅读英文技术文档的不是你的英语水平, 而是你天然对英文的恐惧加上糟糕的中文组织能力, 克服恐惧, 多练习中文写作, 大多数哑巴英语患者都可以顺畅的阅读英文技术文档.

文章分类
前端
文章标签