登录 注册

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

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

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 回帖
我为什么要用中文写项目文档

欢迎来到这里！

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

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

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

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

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

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

    这样一个世界该多美好：

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

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

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

    1 回复
  • suesunss • • 1

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

    1. 计算机科学毕竟欧美发展的历史要领先我们，很多词汇、表达用英语表达更能够方便开源社区去理解。
    2. 编程语言本身是英文的，如果函数名、变量名、注释都是各国母语，这样的项目到时候如果要推广出去好改吗？
    3. 开源社区需要有自己的交流语言、习惯与惯例，然后用这种『共同性』去交流，比如代码，比如注释，话说回来，如果真的是好东西，我们请社区中的活跃者去翻译成自己地语言，这样的路径不是更好吗？
  • someone • • 1
    1. 他要求提得很理直气壮，其实很没礼貌。
    2. 嘿嘿，中文起码也是世界范围内流通的第二大语言吧。还是应该加强学习。
    3. 当初都是我们把英语国家的优秀作品翻译成中文，现在轮到他们了。感谢开源的中国程序员们。
    4. 国人可以啃英文，为什么外国友人不能啃啃中文--为答主点赞，程序没有国界，程序员是有国界的。
  • 查看全部回帖
88250
但行好事莫问前程 昆明
回帖
33773
 帖子
712
 积分
167971