D 的个人博客

开源程序员,自由职业者

小而美的 Java 博客系统 Solo
Golang 在线 IDE Wide
黑客与画家的社区 Sym
  menu
402 文章
1,930 评论
3419894 浏览
10 当前访客
ღゝ◡╹)ノ❤️

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

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 的网站

评论
  • 有空提这个不如提“批判的武器不能代替武器的批判” 😂

    Reply
  • 外国人不用百度云,就算用了也得看中文,没什么必要。

    Reply
  • 我从 2006 年开始写博客,Solo 博客系统本身是从 2009 年开始写的。说来也惭愧,10 多年也就只做到现在这样的程度 🤣

    Reply
  • 我最喜欢 GitHub 一点就是不强制注册,
    再看看 gitee😭

    Reply
  • 信息技术到了初三才学有点用的单片机,以前是 Scratch,Office,vb6,IE,然而初三没副课 😭

    Reply
  • 看看计算机考级内容,就明显不可能的,wps 和 IE 使用方法还考试,英语换编程不可能的,唉。😭

    Reply
  • 你的博客真的很酷,崇拜大佬!做个这样的博客难度大吗?

    Reply
  • 不转不是中国人,最炫民族风! 🤣

    Reply
  • 没人提提文化自信,名族自信吗

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

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

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

    有什么想法都欢迎讨论

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

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

    Reply
  • 我也并没有反对用英语
    我用中文解释了异常详情, 又特意用有道翻译了一遍英文的, 翻译完根本不是原话意思, 然后再修改, 弄了一遍翻译, 用括号备注在了中文下面, 提了个 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, 并且删除了最后面的两句话
    今天真是白白浪费时间了

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

    Reply
  • 主创有洁癖可以理解。有意思的是我遇到和你相反的情况,有国人用英文给我提 issue 还有 PR,本来我想说一句“大家用中文吧,沟通起来更方便”,但又碍于面子没说,结果我和对方用憋足的英语讲了半天,你说尴尬不尴尬 😂

    后来再碰到类似情况,只要我觉得对方是国人(比如根据 GitHub 个人主页位置信息以及参与或者收藏的仓库判断),他即使用英文我也还是用中文。他对项目可能是出于国际化考虑,而我出于简单高效考虑,尽快解决问题优先。当然,对方如果是外国人,肯定就用英文和他交流了,不然就真的太不友好了。

    总的来说,我不是在反对用英文,只是目前来说我觉得中文更高效。相信以后随着项目的逐步发展,语言的问题也会慢慢磨合解决的,语言毕竟只是个工具,不是项目的内核。我希望的是一个包容开放的项目生态,而不是自以为正确的独裁专断。

    Reply
  • 今天第一次提 PR 就感觉很失望, 吐槽一下 ...
    一个中国人的开源项目, 发现一个 bug, 修改了一下提了一个 PR, 使用中文提的, 并且在每句中文下面添加了英文翻译, 结果被要求必须删除中文, 全部用英文写, 一度感觉很愤怒 ...
    感觉汉语被侮辱了, 也感觉自己没有被尊重 ...
    只能默默留下了没有技术的眼泪 ...

    只能默默为 D 佬点个大大的赞

    Reply
  • 其实国际化开源也有其一定的好处,有个开源前端 UI 框架叫 IView ,作者提到过“瑞典法律规定企业如果使用开源项目在生产环境中,要先帮助开源项目修 bug”,所以他的开源作品其实包含各界人士的共同努力,哈哈。
    话说这位朋友还蛮陈恳的。

    Reply
  • 这个想法可以的

    Reply
  • 老外看不懂,难道不能学中文吗?

    Reply
  • 我!拿钱

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

    支持 Ding 总!😄

    Reply
  • 就烦那种天天伸手要自己又不干啥的

    Reply
  • 支持 D 大。现在翻译软件的功能都不错,应该能做把中文翻译成明了的英文。

    Reply
  • 中文象征团体暗号

    Reply
  • wgh

    支持大 D

    Reply
  • 如果代码放在国内托管(例如 码云)只中文完全是没有问题的,但是放在 GitHub 这种国际平台,英文文档我觉得是必要的(可以慢慢搞)。个人见解

    Reply
  • 如果从小学、初中、高中起的英语课都改为编程,国内现在得有多少 大佬啊

    Reply
  • 顶你!

    Reply
    • 用什么语言取决于你想把项目做到什么程度。
    • 国内开源环境的确很差,很多人对开源的理解仅限于免费。

    Reply
  • 说到我心坎上了

    不过其实话又说回来,还希望国产 GitHub 给力啊……

    Reply
    • 其实这个问题是多数人对于困难更多的是寄希望于别人的帮助,是一个索取的过程,而不是自己去实践、去解决、去贡献。

    • 语言不通,但是现在有很多的翻译软件不是,虽然翻译软件翻译的不会 100% 准确,但至少是能帮助理解。

    • 不管是什么语言,那都不重要。

    • 开源不只是帮助用户,也帮助项目本身。同时用户的贡献也是在帮助自己。😄

    Reply
  • gmt

    其实最关键的还是要项目得有用。某些 markdown 网红工程师的文档可以说是秀得上天了,实际上项目全是一些玩具 demo 毫无价值。我认为只要你的项目对大家有用,文档啥的都无所谓了,又不是商业服务还包培训。

    Reply
    1. 他要求提得很理直气壮,其实很没礼貌。
      2.嘿嘿,中文起码也是世界范围内流通的第二大语言吧。还是应该加强学习。
      3.当初都是我们把英语国家的优秀作品翻译成中文,现在轮到他们了。感谢开源的中国程序员们。
      4.* 国人可以啃英文,为什么外国友人不能啃啃中文--为答主点赞,程序没有国界,程序员是有国界的。

    Reply
  • 人数不是范围的全部,一个开源项目要能跨越不同的自然语言、跨越不同的文明才算成功。目标是这样,但是现阶段只能顾“少数人”了,小目标实现后再追求大目标。

    Reply
  • 全球使用中文的人已经达到 17 亿了快,你还嫌范围不够大吗trollface

    Reply
  • @suesunss

    专业不专业我觉得和用什么语言来写代码注释关系不大,代码注释也是软件文档的一部分,用中文写代码注释的目的和项目相关文档用中文写是一样的,都是为了让周围的人更好理解。这能保证项目在整体上的一致性,不然文档、社区用户都是中文的,代码注释又用英文就有点尴尬了(现在我这边项目就是这样的情况,所以我想做一些改变)。

    当然,这样做目前来看是“难登大雅之堂”的,也不利于项目在更大范围的传播,也许以后某个阶段到达后会再进行调整和总结吧(也许以后中文更流行了也就不用调整了)。文中最后提到,这个话题延伸下去的话会很悲哀,目前只能叹息我们软件整体产业落后,开源方面也会导致一些冲突。怎么说呢,我觉得一步到位和国际接轨太难了,慢慢发展吧。

    感谢分享交流 😄

    Reply
  • 说的是太绝对了,但是也提到了,我们的开源环境有一定的问题。我也跟欧洲的开发者接触过,他们也有很多优秀的项目,但是他们很多并不是上来就用自己的母语去写代码注释,这样肯定是不利于项目走出去的。并不是说我们的项目中不能用英语,而是说使用英语有几点好处:

    1. 计算机科学毕竟欧美发展的历史要领先我们,很多词汇、表达用英语表达更能够方便开源社区去理解。
    2. 编程语言本身是英文的,如果函数名、变量名、注释都是各国母语,这样的项目到时候如果要推广出去好改吗?
    3. 开源社区需要有自己的交流语言、习惯与惯例,然后用这种『共同性』去交流,比如代码,比如注释,话说回来,如果真的是好东西,我们请社区中的活跃者去翻译成自己地语言,这样的路径不是更好吗?
    Reply
    • 放在国外,人家的开源项目也并不是用自己的母语写注释。

    这句话太绝对,表示不认同。

    Reply
  • 你可以用中文写 readme,但是用中文写代码注释就很不专业了。放在国外,人家的开源项目也并不是用自己的母语写注释。
    这背后的原因是:

    1. 注释,你准备让谁给你翻译?readme 倒是可以让国外社区去翻译。
    2. 你写代码是用中文的吗?如果是,你可以用中文写注释。
    Reply
  • 以后我写汉语拼音

    Reply
  • 以前高考英语 150 分,现在只有 100 分。以前很多资料都是英文写的,现在很多资料都能找到中文的。
    用中文写文档我觉得不仅仅面向国人,更重要的是可以丰富资料,当我想学习比较好的项目的时候,为了学这个项目,还要把英文学好。如果可以有中文文档的项目,无论是学习还是交流什么的都很方便。

    Reply
  • 代码注释写甲骨文

    Reply
  • 我们都啃英文,外国友人啃啃中文。没毛病

    Reply
  • 表示完全赞同

    Reply
  • 既然用中文的人多,那开源项目文档用中文就能帮助到更多的人,这样岂不是更好。

    Reply
  • 针对后两点提问:Why not Gitee but GitHub ?

    Reply
  • 中国人用中文写文档没毛病,支持、感谢。 👍

    Reply
  • 写文档也是一门技术活啊。

    Reply
    • 开源项目的翻译由开源社区自己完善这也是开源社区的一个特性,如果是要求开源项目作者做翻译的话,有点不太合适了
    • 翻译的软件、插件这么多,稍微翻译一下不至于看不懂
    • 我们都啃英文,外国友人啃啃中文的确没啥毛病

    Reply
  • 做为开源项目,在许可下,各国的开源者之间都可以相互翻译。话说感觉现在的翻译工具已经翻译的很不错了,自己再稍微看看应该不成问题。

    不知道是否有国人要求把英文项目翻译成中文的 issue 的?好像有,而且貌似还被自己的同胞 diss。

    不知道要求翻译成英文的 issue 会被英文同胞怎么看待?可能会为自己的母语是英语而有一丝丝自豪?感觉无论怎么,至少不会 diss 这个 issue 的发起者

    Reply
  • 英文?不存在

    Reply
  • 理由就是:我就是不想写,不服顺着网线来打我呀。

    Reply
  • 英语毫无疑问比汉语流传更广,汉语是因为我们人多啊
    毕竟大汉语学起来比英语要难

    Reply
  • 吓得我赶紧去百度百科了一下...
    image.png
    目前的国际通用语言有好几种trollface

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

    Reply
  • 我看有个起因是因为国产项目霸榜 trending,但是外国人看不懂这都是啥项目

    要我说也情有可原,国际平台上,也应该用国际通用语言

    Reply
  • 啃英文啃得我头疼

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

    为这句话疯狂点赞

    Reply