登录 注册

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

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

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!

    408 引用 • 3574 回帖
  • 中文
    6 引用 • 89 回帖
1 操作
88250 在 2019-08-19 13:52:56 置顶了该帖
昆明 位置
5 感谢
16 关注
2 收藏
9 赞同
1 操作
65 回帖
2
16.2k 707 2.4k 2.3k 5 3.5k 1.1k 14 1.3k 4.7k

相关帖子

优质回帖
  • InkDP • • 2 赞同
    捐赠者

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

    为这句话疯狂点赞

  • csfwff • • 1
    捐赠者

    啃英文啃得我头疼

  • someone756 • • 1 赞同

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

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

欢迎来到这里！

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

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

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

    1 回复
  • 其他回帖
  • HaujetZhao • • 1 • 1 赞同
    订阅者 支持者 勇士

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

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

    这样一个世界该多美好：

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

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

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

    1 回复
  • someone48938 • • 1
    捐赠者

    写英文主要是因为英文写着更顺手，因为我从一开始学习 CS 相关技术就是看的全英文材料，很多名词都不知道中文翻译过来叫什么，如果硬要写中文不是不可以，但是会消耗较多时间，而且看上去可能会显得翻译腔太重。

    最主要的问题是我需要我的文档被更多的人看懂。英文的普及度很高了，基本上任何一个国家，搞技术的人或多或少都会懂一些英文。而中文在国外非华裔群体里的普及度是相当的低。设身处地的考虑，假设我看到一个项目的 README 或者 wiki 全是德文、俄文之类我不认识的文字，Google 翻译一下又狗屁不通（这很常见，目前机翻对于技术相关文章的局限性还是普遍存在的），我一定不会继续看下去。这样下来，不利于项目更好地为大众所用，也不是很符合开源软件或者自由软件的精神。因此，我的项目一般都会用英文写文档和注释，博客也用英文来写。localization 的事情，还是留给其他贡献者。

    当然有一个例外，就是当这个项目面向的群体是国人时。比如在公司做的项目，用户和与我合作开发的同事都是中国人，那我会选择用中文来写文档，注释也尽量用中文。对于开源项目而言也同理，如果面向的用户群体以国人为主（比如我要做一个黑客派的客户端，而黑客派是一个中文社区，几乎没有见到外国友人的访问），且他们不一定具有相关技术背景的话，那我会考虑使用中文来写文档，或者在英文文档之外提供精心翻译后的中文文档。

  • 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 回复
  • 查看全部回帖
88250
但行好事莫问前程 昆明
回帖
33774
 帖子
712
 积分
167961