V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
amery2010
V2EX  ›  Node.js

花了 8 个月的闲暇时间完成 Node.js API 文档的翻译(初版)

  •  
  •   amery2010 · 2016-11-25 18:46:40 +08:00 · 4759 次点击
    这是一个创建于 2680 天前的主题,其中的信息可能已经有所发展或是发生改变。

    起因

    年初,我学习 Node.js 的过程中需要查询一些最新版本的 Node.js API ,加之自己并不能向很多英文熟练的人那样直接阅读英文原版 API 文档,所以选择去阅读中文版的文档。虽然在网上很容易找到 Node.js API 的中文版文档,但我也同时发现了一个比较严重的问题。那几份文档都是基于一年前的版本(甚至更早)进行的翻译,文档中的大部分内容都已经过时或缺失。想到大部分人应该都遇到了和我类似的情况,于是我便萌生了翻译 Node.js API 文档的想法。

    翻译过程

    翻译文档是件痛苦的事,特别是当你遇到一些你自己都不懂的甚至都没法准确 Google 出来的专业术语时,你会非常抓狂。原本我只是单纯的认为,旧版的和新版的文档应该不会有太大的差异吧...一开始,我通过 Google 机翻加自己调整语序进展的很顺利,而且最初的几章基础核心模块的文档变化并没有那么大,对于一些自己无法理解的部分还可以查阅前人的翻译。但蜜月期很快就过去了,在翻译了最初的几个小章节之后,我发现新版的 API 开始发生了些变化:

    • 所有的示例代码都通过 ES2015 的语法进行重写了

    • 有一些类的部分方法已被废弃,但文档并未将其删除,只添加了稳定度提示。为了保持文档的一致性,我只能选择继续翻译...

    • 有大部分章节的内容都进行了重写(可能是开发者换人或觉得之前阐述不够详细),增加了很多翻译量

    • 新增了很多新的 API ,这部分的翻译量最大,翻译工作最难(无从参考)。

    期间有过多次放弃的想法,但当我回想起已经翻译的那部分文档时,不想让自己之前所做的工作付之一炬,毅然坚持下来了。

    目前的文档内容较之前旧版文档而言,内容量大概是其 2.5~3 倍,导出的 PDF 文档目前有 650 多页(我是怎么办到的...)。

    我还额外增加了一个函数速查表章节(之后会做调整),以方便大家快速查找想要找的 API 。

    虽然从今年 4 月初截止今天( 11 月 25 日)为止,终于完成了初版的翻译,但这也是项目的起点。一个人是无法持续完成如此大量的工作的,如果你愿意,欢迎你一起加入到我的翻译队伍中来,帮助和完善 Node.js API 中文版文档的翻译工作。

    项目地址

    文档分为 Markdown 版本和 Gitbook 版本:

    GitHub 项目地址:Node.js API 中文版

    Gitbook 项目地址:Node.js API 中文版

    阅读文档的话,我建议直接在我放在国内的网站上的 Gitbook 版本 也可以直接访问 http://nodejs.xiangfa.org/

    第 1 条附言  ·  2016-11-26 08:11:43 +08:00

    我修改了 Github 库的名称,如果原网址无法访问的话,可以访问以下网址

    Node.js API 中文版

    28 条回复    2016-12-11 22:27:46 +08:00
    ob
        1
    ob  
       2016-11-25 19:00:05 +08:00 via Android
    强烈支持,虽然我自己还没用过。
    kidlj
        2
    kidlj  
       2016-11-25 19:02:42 +08:00   ❤️ 3
    这个节点主题谁设定的,求去掉,要闪瞎眼了。
    Duluku
        3
    Duluku  
       2016-11-25 19:06:06 +08:00
    真是挺厉害的
    shiny
        4
    shiny  
       2016-11-25 19:28:16 +08:00   ❤️ 1
    LZ 厉害。我在维护 PHP 手册中文版,可以多多交流经验。
    keeley
        5
    keeley  
       2016-11-25 19:35:33 +08:00
    随手看了章翻译的这么不通畅、
    ···
    异步和同步的控制台

    console 函数默认是异步执行的,除非目标对象是一个文件。这应该是一种罕见的写块( write blocks ),但是的确有可能出现,因为高速硬盘和操作系统通常采用回写式的缓存。
    mikicomo
        6
    mikicomo  
       2016-11-25 19:58:23 +08:00
    @keeley 其实翻得挺好的了啊....
    Gem
        7
    Gem  
       2016-11-25 20:52:41 +08:00
    是 6.9.1 的 lts ,还是最新的的 7 的版本?
    wikinee
        8
    wikinee  
       2016-11-25 21:46:42 +08:00 via iPhone
    任何有助于国内程序员学习的都支持
    amery2010
        9
    amery2010  
    OP
       2016-11-25 21:54:13 +08:00
    @keeley 感谢你的批评指正哈,因为本人英文水平不佳加上对 Node.js 中的部分术语至今无法准确定义,因此会存在不少翻译上的错误,我会在之后的一段时间内对稳定进行校正。
    amery2010
        10
    amery2010  
    OP
       2016-11-25 21:58:51 +08:00
    @Gem ,目前版本基本上是基于 5.x 的版本进行翻译的,但之后版本的变化对文档内容的影响应该不会有特别大的出路。根据目前文档的编写逻辑来看,官方只会 Add ,而不会 Delete 内容,废弃的章节或函数官方是以稳定度提示来处理的(也就是废弃的内容依然存在文档内)。

    我会在校正当前版本的基础上,尽快得同步官方的文档内容。如果没有用到最新增加的一些 API ,应该不会对你的阅读造成太大影响。
    forreally
        11
    forreally  
       2016-11-25 22:32:42 +08:00
    支持,👍
    amery2010
        12
    amery2010  
    OP
       2016-11-25 22:36:18 +08:00
    @shiny 与君共勉!

    想到我当年入门编程的第一门语言就是 PHP ,那时还对 PHP 非常热爱,但工作后从事了前端开发的岗位,对 PHP 的接触便越来越少了,但我认为 PHP 依然是一门非常活跃的语言。
    mingyun
        13
    mingyun  
       2016-11-25 23:34:27 +08:00
    @shiny php 手册可谓详尽,赞
    herozzm
        14
    herozzm  
       2016-11-26 00:06:06 +08:00 via Android
    lz 你的付出值得肯定
    anewg
        15
    anewg  
       2016-11-26 00:34:38 +08:00
    @shiny 我之前记得 namespace 那块跟英文版对比有错 不知道现在改了没
    shiny
        16
    shiny  
       2016-11-26 00:52:48 +08:00
    @amery2010 PHP 手册对多语言非常友好(当然 XML 格式也蛮难懂)

    PHP 手册的经验是,可以在翻译后在文件头部注释 en 的版本号,更新起来就会容易很多,可以追踪到对应的 diff 。

    格式方面,中英文要有空格;中译要用中文标点;特殊名词可以不翻译。

    还有刚翻译的时候喜欢把英文惯用表达方式翻译出来,比如「你可以」,「一个」。
    像这个句子「停止一个之前通过 setTimeout() 创建的定时器。」可以把「一个」去掉,也不影响意思。
    参考「余光中:怎样改进英式中文?——论中文的常态与变态」 http://open.leancloud.cn/improve-chinese.html

    有需要帮忙翻译的也可以找我。
    shiny
        17
    shiny  
       2016-11-26 00:57:19 +08:00
    @anewg 如果发现错误可以联系我,或者自己提交补丁。因为手册量实在太大了,但翻译的人非常少。
    一般有错误我会及时更新;补丁会定期审核;如果是文件过期不一定能顾得上,现在就有 1700 个文件等着更新。大多数情况下,原译者开了坑之后就不管了。
    amery2010
        18
    amery2010  
    OP
       2016-11-26 07:53:43 +08:00
    @shiny 感谢你的宝贵建议哈,我会努力改进的!
    wemore
        19
    wemore  
       2016-11-26 11:38:19 +08:00 via iPhone
    看 spring 的文档,翻了十几页。有道生词本里多了一百多新成员😂😂😂
    amery2010
        20
    amery2010  
    OP
       2016-11-26 11:48:46 +08:00 via iPhone
    @wemore 😂谷歌翻译是我的好朋友
    anewg
        21
    anewg  
       2016-11-26 11:52:01 +08:00
    @shiny 好的 感谢
    Arrowing
        22
    Arrowing  
       2016-11-26 15:57:18 +08:00   ❤️ 1
    @kidlj @Livid

    这主题背景和文字颜色确实很闪眼啊,能不能换成和其他板块一样的,这样根本读不下文章。
    belain
        23
    belain  
       2016-11-27 22:38:26 +08:00
    先谢再看
    heyheycici
        24
    heyheycici  
       2016-11-30 17:39:44 +08:00
    感觉很厉害 我想问楼主一个问题 为啥你的个人网站里用只用 canvas 放了张图 是不是我太蠢了 没有发先机密
    amery2010
        25
    amery2010  
    OP
       2016-11-30 17:50:58 +08:00
    @heyheycici O(∩_∩)O 哈哈~其实你点到的是当做背景的那个 canvas 层。我是一个简约主义者,个人觉得首页没必要做得太过复杂,简简单单即可。所以,首页只放了 logo 以及部分子网站的链接,并且这个页面的代码完全是用原始 JavaScript 编写的,没有引入任何的依赖库。你可以完全查看页面的源代码,来一窥你所说的机密...
    heyheycici
        26
    heyheycici  
       2016-12-01 08:15:37 +08:00
    哈哈哈 我没有把那个子言聆听当成是图片中的文字了 就没有点 我点的是下边的英文我认为那个是链接点了之后发现没有什么反应 现在明白了
    yunshansimon
        27
    yunshansimon  
       2016-12-10 21:11:03 +08:00
    楼主很有恒心,但真的不建议看中文翻译的文档,哪怕是原作者写的文档,比如 vue 的中文文档。英文文档更准确,中文文档再好,但中文本身有很多歧义,无端会给自己挖很多的坑。
    amery2010
        28
    amery2010  
    OP
       2016-12-11 22:27:46 +08:00 via iPhone
    @yunshansimon 所以我的初衷也并不是给可以看懂英文的那批人的。如果自己看不懂英文文档或比较难理解英文文档中的寓意,一知半解的话,那无非是给自己挖坑。我做这份文档,至少可以帮助部分人理解个大概,对于其中有问题的翻译,我会尽可能地去修正,至少给那批无助的人指个大概方向,而不是让他们自生自灭..
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   5235 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 29ms · UTC 09:25 · PVG 17:25 · LAX 02:25 · JFK 05:25
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.