登录 注册

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

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

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 引用 • 3575 回帖 • 1 关注
  • 中文
    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 回帖
我为什么要用中文写项目文档

欢迎来到这里！

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

注册 关于
请输入回帖内容 ...
  • InkDP • • 2 赞同
    捐赠者

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

    为这句话疯狂点赞

    1 回复
  • csfwff • • 1
    捐赠者

    啃英文啃得我头疼

  • Zephyr •

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

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

    1 回复
  • someone756 • • 1 赞同

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

  • chengzime •

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

    1 回复
  • Zephyr •

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

    1 回复
  • someone27889 • • 1
    捐赠者

    理由就是：我就是不想写，不服顺着网线来打我呀。

  • JssDream •
    捐赠者

    英文？不存在

  • Vanessa •
    订阅者 付费者

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

    不知道是否有国人要求把英文项目翻译成中文的 issue 的？好像有，而且貌似还被自己的同胞 diss。找了一下没找到，但找到了 https://help.github.com/cn 这个

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

    1 操作
    Vanessa 在 2019-08-19 18:27:18 更新了该回帖
  • Blackman99 • • 1
    捐赠者
    • 开源项目的翻译由开源社区自己完善这也是开源社区的一个特性，如果是要求开源项目作者做翻译的话，有点不太合适了
    • 翻译的软件、插件这么多，稍微翻译一下不至于看不懂
    • 我们都啃英文，外国友人啃啃中文的确没啥毛病
  • lvtaos •
    捐赠者

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

  • iTanken • • 1 赞同
    捐赠者

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

  • xflash •

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

  • jenphyjohn •
    订阅者 支持者 勇士

    表示完全赞同

  • kuailexs •

    我们都啃英文，外国友人啃啃中文。没毛病

  • yuanhenglizhen •
    捐赠者

    代码注释写甲骨文

  • hjljy • • 1

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

  • someone9891 •
    捐赠者

    以后我写汉语拼音

  • suesunss •

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

    1. 注释，你准备让谁给你翻译？翻译注释的难度比翻译 readme 的难度高太多了，需要理解代码。readme 倒是可以让国外社区去翻译。
    2. 你写代码是用中文的吗？如果是，你可以用中文写注释。
    1 回复
  • someone9891 •
    捐赠者
    • 放在国外，人家的开源项目也并不是用自己的母语写注释。

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

    1 回复
  • suesunss • • 1

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

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

    @suesunss

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

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

    感谢分享交流 😄

    1 回复
  • someone9891 •
    捐赠者

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

    1 回复
  • 88250 •
    订阅者 作者

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

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

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

    1 回复
  • destiny0 • • 1

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

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

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

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

  • Zephyr • • 1

    说到我心坎上了

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

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

    顶你！

  • someone9891 •
    捐赠者

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

    2 回复
  • someone • • 1

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

  • wgh • • 1

    支持大 D

  • vinasis • • 1

    中文象征团体暗号

  • zyk • • 1
    订阅者 支持者 捐赠者 勇士

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

  • tiangao • • 1 赞同
    捐赠者

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

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

    支持 Ding 总！😄

    放佛听见了 一生 Ding ~~~~
    someone9891 •
  • someone27889 •
    捐赠者

    我！拿钱

  • lxp135 •
    付费者

    老外看不懂，让他们去学中文。trollface

  • someone •

    这个想法可以的

  • josephyoung • • 1

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

  • chengzime •

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

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

    2 回复
  • 88250 •
    订阅者 作者

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

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

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

    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 回复
  • 88250 •
    订阅者 作者

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

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

  • someone • • 1

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

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

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

    有什么想法都欢迎讨论

  • wuwb •

    没人提提文化自信，民族自信吗

    2 回复
  • 88250 •
    订阅者 作者

    不转不是中国人，最炫民族风！ 🤣

  • someone •

    你的博客真的很酷，崇拜大佬！做个这样的博客难度大吗？

    1 回复
  • someone48034 •

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

请输入回帖内容 ...
88250
但行好事莫问前程 昆明
回帖
33796
 帖子
712
 积分
167996