我为什么要用中文写项目文档

本贴最后更新于 1952 天前,其中的信息可能已经时移世易

English Please

最近 B3log 开源社区下的项目 BND1 以及 30s2 被外国友人 hobolance3 贴了两条建议:

  1. English Please - BND4
  2. English Please - 30s5

这两个项目都是中文写的 README。他建议把中文换成英文,这样对外国友人更友好,也能为项目获得更多关注。

What is the problem with Chinese README's
What we want
How this will help you

结尾引用了 Richard Stallman 的名言:

Sharing knowledge is the most fundamental act of friendship. Because it is a way you can give something without loosing something.

hobolance 也给其他一些中文项目提过该建议,大部分处理是被直接关闭。因为这些项目和 BND、30s 一样都是面向国内用户的,比如 UnblockNeteaseMusic6、CS-Notes7

为什么要用中文

在 2014 年 B3log 开源社区的项目 Wide8 在 Hacker News 上就被外国友人吐槽过代码中使用中文注释9,后来我把这些注释改成英文的了。当时 Wide 的 README 及其主要的文档都是英文的,也算是一个国际化项目了。

今年年初我特意把 Wide 的 README 改成中文的了,因为这几年下来我逐步觉得用中文给项目写文档(包括代码注释)很有意义(这也是为什么要做协慌网10的动机之一):

  • 我的母语是中文,用中文写文档最熟悉,表达也能更言简意赅
  • 项目的国际化是个独立的软件过程,开源项目的国际化可以求助贡献者
  • 国人可以啃英文,为什么外国友人不能啃啃中文
  • 先切实帮助到国人,次要再考虑项目自身的传播
  • 社区用户以国人为主,我们都是用中文交流的

可能我个人能力有限,无法面面俱到。如果我有时间精力,那肯定是中英双语覆盖文档和代码注释。不过换个角度看,说明项目需要国际化方面的贡献者,这部分工作量交由贡献者来完成也更好一些。开源不只帮助用户,也帮助项目本身,这是相互促进的。

国人开源的现状

这个话题延伸下去会挺悲哀的,本质上是开源精神和现实的冲突。很多开发者或者用户对开源的理解只是停留在免费、安全、情怀这样的层面上,其实远不止这些。这可能也是有些主创直接选择国际化的原因,国内目前还不具备这样的环境。不过我觉得这一切正在改变,因为像我一样的主创也越来越多了。

从主创的角度,我们缺乏的是一片真正的开源土壤,这片土壤绝对不能以商业化盈利为首要目的,否则就会变成一个鸡蛋问题:平台还没做大就想着如何赚开发者的钱(在一些功能细节上设限,在一些产生资金流的地方设限);开源主创们本来就非常艰难了,在这样的平台上做开源简直是难上加难。所以只要以盈利为目的的开源平台都做不好,要做好只有一条路,由大公司注资兜底,不设置盈利目标。

大公司为什么要做这样的投入?因为他们想更好地实现业务整合,以备在更高维度上建立生态系统,最终提升整体竞争力。我们所处的是商业社会,开源这件“存在即合理”的事情也可以看成是商业活动。我感觉中国开源的春天不远了,以开源商业化为商业模式的公司将越来越多,国内的开源浪潮即将成型。

相关链接

  1. BND - 一款图形界面的百度网盘不限速下载器,支持 Windows、Linux 和 Mac
  2. 30s - 前端知识精选集,包含 HTML、CSS、JavaScript、React、Node、安全等方面,每天仅需 30 秒
  3. hobolance - 一个外国友人的 GitHub 账号
  4. English Please - BND
  5. English Please - 30s
  6. UnblockNeteaseMusic - 解锁网易云音乐客户端变灰歌曲
  7. CS-Notes - 技术面试必备基础知识、Leetcode 题解、Java、C++、Python、后端面试、操作系统、计算机网络、系统设计
  8. 一款基于 Web 的 Go 语言 IDE,随时随地玩 golang
  9. A Web IDE for Teams using Golang | Hacker News
  10. 协慌网,一个汉化 Stack Overflow 的网站
  • 开源

    Open Source, Open Mind, Open Sight, Open Future!

    407 引用 • 3578 回帖 • 1 关注
  • 中文
    6 引用 • 89 回帖
1 操作
88250 在 2019-08-19 13:52:56 置顶了该帖

相关帖子

优质回帖
  • InkDP 2 赞同

    国人可以啃英文,为什么外国友人不能啃啃中文

    为这句话疯狂点赞

  • csfwff 1

    啃英文啃得我头疼

  • someone756 1 赞同

    中英文无所谓,像我这种大神.

欢迎来到这里!

我们正在构建一个小众社区,大家在这里相互信任,以平等 • 自由 • 奔放的价值观进行分享交流。最终,希望大家能够找到与自己志同道合的伙伴,共同成长。

注册 关于
请输入回帖内容 ...
  • chengzime

    我也并没有反对用英语
    我用中文解释了异常详情, 又特意用有道翻译了一遍英文的, 翻译完根本不是原话意思, 然后再修改, 弄了一遍翻译, 用括号备注在了中文下面, 提了个 PR.
    结果项目发起者只关注你的内容中有 中文, Please use all English., 不关心提的 bug
    然后我删除了所有的中文, 只留下了英文
    然后我用英文问他 : I used the software to translate sentence by sentence. Why do I have to delete Chinese? I think this is not friendly to Chinese people, Besides, you're Chinese, very disappointed
    然后他回复: I'm the project owner. I decide the rules. The commit message is still not following the rule. I will close this PR for now.
    然后关闭了 PR, 并且删除了最后面的两句话
    今天真是白白浪费时间了

    两个中国人用蹩脚的英语互相交流确实很尴尬, 即没有效率, 也可能表达不清 😋

    1 回复
  • 其他回帖
  • someone 1

    挺好的。
    至少在我个人认为是这样的。
    不过也确实,一般来说我觉得这属于需要权衡的东西
    比如像其他评论里的客观化原因(贡献不足够大啊之类的)
    当上升到一定流量,或者说 OK,这是一个由多国人共同维护的项目的时候
    也许就需要国际化了。

    不过,有一点我个人是这么想的,并非歧义,客观上来说
    哪怕是做国际化
    也一定是多国语言版本都会有。

    我去看了一下 repo。
    按道理来说
    增加英文文档完全没问题
    但这时候考虑到开发人员及主创的效率来说。
    就像中文开发者经常会看到同胞贡献的中文翻译文档一样
    个人建议
    在时间不足以翻译并更新一份文档的时候
    这种任务我个人觉得
    是完全可以交给,懂中文的同胞帮忙一起翻译的(as a PR)
    实际上这也并不是什么问题
    我个人觉得。

    有什么想法都欢迎讨论

  • HaujetZhao 1 1 赞同

    从另外一点来看,开源软件界还缺少一种语言协同系统,后者需要:

    • 让一个项目拥有多语言版本的注释、变量名
    • 开发者可以随意切换查看不同语言的注释、变量名,选择自己的母语
    • 用户、开发者可以贡献注释翻译
    • 在不同注释语言下贡献的代码可以完美 commit merge 到主项目

    这样一个世界该多美好:

    • 一位中国开发者下载了 Linux 源码,用 IDE 打开时,根据系统的语言,自动显示中文版本的注释,将有翻译的变量自动转换成中文变量
    • 没有翻译的部分使用的是英文原文,这位开发者可以贡献注释的中文翻译,以后其他中文开发者可以看到这个翻译版本。
    • 全世界不同母语的开发者都能用他们自己的母语做注释、做开发。
    • 可以有不参与开发的多语言志愿者、爱好者(他们可能编程水平不行,但做翻译是小菜一碟,并且愿意做)帮助翻译,改进不同母语项目开发者之间的协同。
    • 当系统运行出错的时候,弹出的错误提示不再仅于英文,而是使用者的母语(只要这个信息有翻译)

    这样一个系统的话,大概像是这样的,所有的注释都会被一个系统归纳到一个 xml 文件。每个语言都有一个 xml ,每次一个开发者更新注释,都会以原语言结合其位置信息更新到所有的 xml ,其它语言的开发者看到这个注释,并用母语翻译后,自动更新到该语言的 xml 文件。

    这样一个系统的产生、多个开源的广泛参与,有生之年不知能不能见到。

    1 回复
  • 88250

    我也决绝过其他人的 PR(不是语言原因),仅从主创的角度上客观分析一波,主要原因是贡献不足够大,对于项目来说这个改进可有可无,甚至还可能会有潜在的副作用(比如代码贡献可能需要更完善的测试覆盖)。

    总之这个世界有的时候是有点冷漠的,“热脸贴冷屁股”的情况时有发生。但不要因此感到失落啊,完全没有这个必要。该贡献开源还是继续贡献,提交有价值的 PR 主创终将被你感化 💗

  • 查看全部回帖