V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
EatMi
V2EX  ›  程序员

大家项目的 README 习惯放中文还是英文?

  •  2
     
  •   EatMi ·
    wy-luke · 182 天前 · 5225 次点击
    这是一个创建于 182 天前的主题,其中的信息可能已经有所发展或是发生改变。

    起因是写了一个开源的项目: https://github.com/wy-luke/StableDiffusion-Installer-For-Mac (原谅我打了个广告)

    在里面写了两份 README ,中文和英文的,纠结了好久,是中文放在首页还是英文放在首页

    会考虑很多因素

    一方面,这里毕竟是英文为主的社区嘛,作为程序员大家应该都理解,这个应该就不用多解释了

    另一方面,觉得自己作为中国人,用母语无可厚非,也能宣扬一下我们国家,同时也是怕被喷,我见过不止一次有人喷,作为中国人但是 README 放的却是英文这件事了

    我最终把英文放在首页是因为,看到阿里的一些仓库采用的也是英文,最终一狠心用了英文

    我确实是自己想的多,也知道不用太在意别人的看法,自己的项目想怎样就怎样

    这里我们不去说哪个对、哪个错,无论哪种都有一定的道理,只是想和大家理性地探讨一下,看看大家更倾向于哪种方式,出于好奇,也出于寻求解决方案

    可能有人没有做过相关工作哈,那就假设,如果你有一个开源项目,你会怎么选择,为什么?

    想做一个简单的投票,分别在 1 楼和 2 楼回复两个选项,如果你更倾向于某种方式,可以为其加个感谢

    (感觉有点像骗感谢来了。。。)

    第 1 条附言  ·  182 天前

    目前来看,其实大多数还是倾向于使用英文

    这个结果其实是意料之中,一来大家素质水平较高,都互相理解,不会因为这点小事喷人,二来程序员居多

    但有些回复还是有点跑偏了,“见人说人话,见鬼说鬼话”,这是固然,当我的产品仅面向中文用户,我会毫不犹豫地使用中文,甚至可能不会写英文文档

    这个帖子想和大家讨论的是,我们抛开其他的一切,不管你的英文好或不好,不管你有没有项目,你的产品受众也是两开花,难分伯仲,此时,你会如何选择?

    把英文放在首页,主要更新,附一个中文文档链接;还是中文放首页,附一个英文文档链接?为什么

    101 条回复    2023-09-16 19:03:23 +08:00
    1  2  
    EatMi
        1
    EatMi  
    OP
       182 天前   ❤️ 3
    中文
    EatMi
        2
    EatMi  
    OP
       182 天前   ❤️ 9
    英文
    xipuxiaoyehua
        3
    xipuxiaoyehua  
       182 天前   ❤️ 3
    技术类的我会更偏向于使用英文
    jstony
        4
    jstony  
       182 天前   ❤️ 4
    看情况,面向的主要是中文受众就中文,面向的主要是英文受众就英文。
    artnowben
        5
    artnowben  
       182 天前   ❤️ 1
    我在做 dperf 的时候,也考虑过这个问题,最终是中英文都有,英文方便国际化,中文方便国内用户,有中文、英文切换的链接。
    https://github.com/baidu/dperf/
    EatMi
        6
    EatMi  
    OP
       182 天前
    @jstony 确实这样简单粗暴,但是如果两方面都有受众呢,你会更倾向于哪种
    jstony
        7
    jstony  
       182 天前   ❤️ 1
    @EatMi “主要”
    EatMi
        8
    EatMi  
    OP
       182 天前
    @artnowben 嗯,我看你的首页也是采用了英文,然后加上中文链接
    artnowben
        9
    artnowben  
       182 天前   ❤️ 1
    dperf 最终只会用英文,维护中英文太费精力了
    zhangxh1023
        10
    zhangxh1023  
       182 天前   ❤️ 1
    英文写的够好,自信,就优先英文 😂
    kdwnil
        11
    kdwnil  
       182 天前 via Android   ❤️ 1
    自娱自乐的项目懒得翻译/仅面向中文用户(比如外语翻译成中文)用中文,其余用英文然后随缘附加中文 readme
    EatMi
        12
    EatMi  
    OP
       182 天前
    @jstony 了解你的意思,谢谢。有时候我确实会难以判断出,项目的“主要”受众是哪边。但是看大多数这种情况下,会采用英文作为首选,然后附上中文链接
    EatMi
        13
    EatMi  
    OP
       182 天前
    @xipuxiaoyehua 好像确实大多数也是这样,就比如国内一些大厂的开源项目,除非是很“鲜明”地面向国内用户,一般的技术项目都会采用英文首选
    EatMi
        14
    EatMi  
    OP
       182 天前
    @zhangxh1023 以前可能确实有英文水平这个问题在,但是现在有了 ChatGPT 的加持,自己再稍微改改,写出一份质量不错的英文文档不算特别困难
    EatMi
        15
    EatMi  
    OP
       182 天前
    @artnowben #9 确实,我现在文档体量还很小,但是每次改动都要改两份,也觉得挺费劲的
    EatMi
        16
    EatMi  
    OP
       182 天前
    @kdwnil #11 了解,谢谢!其实就还是在**乐观**情况下,更倾向于英文首选 + 中文链接
    EatMi
        17
    EatMi  
    OP
       182 天前
    @artnowben #5 哇,刚注意到,是百度的大佬呢。公司内部在做这种项目的时候,关于英文首页还是中文首页,会有相关规定吗?还是说全凭开发者习惯
    artnowben
        18
    artnowben  
       182 天前   ❤️ 1
    @EatMi 倾向英文
    kongkx
        19
    kongkx  
       182 天前 via iPhone   ❤️ 1
    中英写在一个文件里面如何
    cnbatch
        20
    cnbatch  
       182 天前   ❤️ 1
    目标用户是中文用户的话,就用中文 + 英文链接;否则就英文 + 中文链接。

    到目前为止,我个人的项目都明确考虑过用户群,所以不会在中文还是英文浪费过份的时间

    至于我工作时公司的项目……都是内部使用的,不对外开放,说出来没意义。
    janus77
        21
    janus77  
       182 天前   ❤️ 1
    我同意按主要受众为标准的办法
    如果你不确定谁是主要的,看看你的宣传阵地,你如果在中文社区宣传多,引流来的中文用户就多,issue 里面提中文的也多。
    lifesimple
        22
    lifesimple  
       182 天前   ❤️ 2
    README_CN.md
    README_EN.md
    README.md 里放上面两链接 中文文档 | English
    不就完美了 不偏不倚
    EatMi
        23
    EatMi  
    OP
       182 天前
    @lifesimple #22 鬼才
    villivateur
        24
    villivateur  
       182 天前   ❤️ 1
    @lifesimple 这还是有偏有倚的,凭什么中文文档在左,英文在右[/狗头]
    EatMi
        25
    EatMi  
    OP
       182 天前
    @villivateur #24 鬼中鬼才
    cwcc
        26
    cwcc  
       182 天前   ❤️ 1
    我的有些项目完全面向中国人的就是直接中文 README.md ,但也有部分项目因为一开始面向中国人,后来也可以面向国际化,我就随缘了,但一份 1:1 的英文 README 我肯定是会写的,但也不保证首页 README.md 一定要英文。如果有人提意见,我就改,不提就这样了,哈哈。
    skiy
        27
    skiy  
       182 天前   ❤️ 2
    我见过小程序的 README 用英文的。
    笑不活了。老外的软件有小程序的吗?或者说有外包开发小程序开发给老外的吗?
    duzhuo
        28
    duzhuo  
       182 天前 via Android   ❤️ 1
    见人说人话 见鬼说鬼话
    WillBeethoven
        29
    WillBeethoven  
       182 天前   ❤️ 1
    默认英文,只面向中文网站/内容的项目才用中文。
    EatMi
        30
    EatMi  
    OP
       182 天前
    @skiy #27 其实也可以理解,一方面可能作者是出于练习目的,尝试使用英文 README ,另一方面,我们不得不承认,有时候英文就会显得更“专业”😂
    callmesmc
        31
    callmesmc  
       182 天前 via iPhone   ❤️ 1
    我也见过喷别人 readme 不用中文的,感觉好奇葩,为什么默认作者和其他用户都是中国人
    kwanzaa
        32
    kwanzaa  
       182 天前   ❤️ 1
    见人说人话,见鬼说鬼话。
    要不就默认 En ,给个 Zh 的超链。
    Pencillll
        33
    Pencillll  
       182 天前   ❤️ 1
    用英文一劳永逸,老外和大部分国人都能看懂
    以前还会额外提供中文版,现在不打算提供了,本来写文档就又费劲又无聊,维护两份文档直接超级加倍,还要考虑是否同步的问题,不如把精力省下来多写点代码
    Lockeysama
        34
    Lockeysama  
       182 天前   ❤️ 1
    本来想房中文的,后来放了英文,因为之前写了 Python 的 SDK ,因为 setup.py 里面引用了中文 readme ,导致在 Windows 下安装 SDK 一直编码报错。后来就索性直接用英文了。
    qquantt
        35
    qquantt  
       182 天前   ❤️ 1
    不用局限在 README
    我和我妈只说村里话,和中小学同学基本说县里话,会中文的朋友我就说中文,以上都不会就英文,英文还不行就找个翻译机器。
    tool2d
        36
    tool2d  
       182 天前   ❤️ 1
    这就和软件是否需要出多语言版本一个道理,有人看还是需要的,毕竟有需求在。

    有 gpt 帮助,翻译一般来说不是太大的问题,比以前没有的时候,要省力多了。
    flyqie
        37
    flyqie  
       182 天前 via Android   ❤️ 1
    default eng
    jadelike
        38
    jadelike  
       182 天前   ❤️ 1
    中文,因为我看不懂英文
    fredweili
        39
    fredweili  
       182 天前   ❤️ 1
    github 上不写英文,就是想内卷
    TianHeiLeKuaiPao
        40
    TianHeiLeKuaiPao  
       182 天前
    预测又是一个撕逼贴
    LitterGopher
        41
    LitterGopher  
       182 天前   ❤️ 1
    中文开发者能看懂英文文档是基本需求,反过来却不是。直白的说就是,写英文版传播范围可能会更广(也只是可能)。
    EatMi
        42
    EatMi  
    OP
       182 天前
    @TianHeiLeKuaiPao #40 也不能这么说,目前为止大家的讨论还是很友善的。不去说谁对谁错,谁优谁劣,这个前提下其实也不太容易撕起来,这样挺好
    FeatureProbe
        43
    FeatureProbe  
       182 天前   ❤️ 1
    Github 是英文,提供了中文链接,如果不想看英文可以直接跳转到 Gitee 查看。
    jlmzzz
        44
    jlmzzz  
       182 天前   ❤️ 1
    在大多数情况下,请使用英语。如果您想表示尊重,请加上中文。
    dabaibai
        45
    dabaibai  
       182 天前   ❤️ 1
    英文极其差 就用中文吧
    LykorisR
        46
    LykorisR  
       182 天前   ❤️ 1
    英文
    EatMi
        47
    EatMi  
    OP
       182 天前
    @Pencillll #33 你说的有道理,主要还是看作者本人的精力和意愿了。同时英文能够兼顾,但是中文却只能面国内用户
    EatMi
        48
    EatMi  
    OP
       182 天前
    @Lockeysama #34 确实,中文的这种兼容性比较棘手
    EatMi
        49
    EatMi  
    OP
       182 天前
    @qquantt #35 对,理解你的意思,就是看目标用户嘛,但有时候就是没有一个“主要”的用户群,想两开花,在这种情况下的倾向性,是我想来讨论的
    EatMi
        50
    EatMi  
    OP
       182 天前
    @tool2d #36 确实省力多了,但是每次更新都得去同步一下,久而久之应该还会感觉到疲累 😂
    EatMi
        51
    EatMi  
    OP
       182 天前
    @flyqie #37 get
    EatMi
        52
    EatMi  
    OP
       182 天前
    @jlmzzz #44 您指的尊重是向哪一方的尊重?
    EatMi
        53
    EatMi  
    OP
       182 天前
    @FeatureProbe #43 嗯嗯,我看到你的项目是这样做的,但是我实在不喜欢 Gitee ,哈哈。我的看法是技术是中立的,GitHub 也不存在一个官方语言,只能说大家默认使用英文来,而且上面也有很多其他国家语言的仓库
    EatMi
        54
    EatMi  
    OP
       182 天前
    @LitterGopher #41 对,这是一方面,英文能够做到兼顾,但是中文却不能
    EatMi
        55
    EatMi  
    OP
       182 天前
    @fredweili #39 其实还好啦,都已经上 GitHub 了,无论带不带功利性的目的,做的东西起码都是免费分享给大家的
    EatMi
        56
    EatMi  
    OP
       182 天前
    @callmesmc #31 是的,虽然知道不用理会这种人,但还是会被影响到心情,令人难过且生气
    dann73580
        57
    dann73580  
       182 天前
    其实没什么对错,更多还是看产品市场吧。这是纯实用主义的角度。

    当然,中文优先,对自己民族文化有认同,愿意使用并且推广,十分理解而且尊重。

    不管怎么选,都是对的。看你价值观更侧重什么方面。
    dann73580
        58
    dann73580  
       182 天前
    @dann73580 补一句:如果你认为作品是自己的代表的话,我建议中文优先。开源本身就是一种政治倾向。立场鲜明的,自信的表达我是中国开发者,是非常有个性,也是非常酷的一件事。
    EatMi
        59
    EatMi  
    OP
       182 天前
    @dann73580 #57 对的,没有孰对孰错,就只是个人倾向,对于你“开源是一种政治倾向”我不太认同,我认为技术就应该仅仅是技术,纯粹的技术,如果让技术染上政治,会有很多不必要的麻烦,比如美国如果严重制裁,就应该舍弃所有美国的开源相关技术吗,那肯定是做不到的。而且我们就只是想做做技术嘛,不想管那么多的有的没的,生活已经很不容易了。但是我尊重你的看法哈,现在也有很多开源仓库会有“支持乌克兰”等政治立场在。对于宣扬民族文化,我也认同,我也觉得很酷,这也是我会认真考虑使用中文有限的重要原因,否则我可能就直接使用英文了。
    joesonw
        60
    joesonw  
       182 天前 via iPhone   ❤️ 1
    一般只用英文,要上 v 站宣传的时候会再 jiage 中文的。
    tyzandhr
        61
    tyzandhr  
       182 天前 via Android   ❤️ 1
    拉丁语。
    qquantt
        62
    qquantt  
       182 天前
    @EatMi 实在觉得有必要,就弄个中英文对照。
    maokabc
        63
    maokabc  
       182 天前 via Android   ❤️ 1
    英文差,机翻英文还不如直接中文,毕竟还有大把喜欢替别人尴尬的人。外国人要用,他们自己机翻一下可能更准确。
    EatMi
        64
    EatMi  
    OP
       182 天前
    @tyzandhr #61 好家伙
    EatMi
        65
    EatMi  
    OP
       182 天前
    @maokabc #63 搭配 ChatGPT 类似的工具会好很多
    EatMi
        66
    EatMi  
    OP
       182 天前
    @kongkx #19 对,文档较小的话确实可以,还方便,我的一个项目就是这样做的。那么问题又来了,是英文在上面还是中文在上面🤣
    Dipous
        67
    Dipous  
       182 天前
    拿中文写的就中文,拿英文写的就英文呗
    hsfzxjy
        68
    hsfzxjy  
       182 天前 via Android   ❤️ 1
    一般只用英文,平时写英文多于中文
    dann73580
        69
    dann73580  
       182 天前
    @EatMi 这个是我没说清。我是说开源这个行为本身,就是一种理念。可能用政治理念这个词模糊了重点。所以优先中文,在不增加额外工作量的情况下,表达自己的理念,是非常酷且值得尊重的。
    voidmnwzp
        70
    voidmnwzp  
       182 天前 via iPhone   ❤️ 1
    给中国人用的就写中文,全球通用的 比如轮子之类的就用英文 我就是这样的
    iintothewind
        71
    iintothewind  
       182 天前   ❤️ 1
    默认肯定得是英文文档,然后在考虑中文文档,毕竟技术文档,英文更方便传播。
    baobao1270
        72
    baobao1270  
       182 天前   ❤️ 1
    我会提供中英双语,但是优先英文( README.md 是英文,README_ZH.md 是中文)
    begeneral
        73
    begeneral  
       182 天前
    有啥区别,甲骨文都行
    kongkx
        74
    kongkx  
       182 天前 via iPhone
    klo424
        75
    klo424  
       181 天前   ❤️ 1
    现在都 gpt 翻译了,英文中文全写上也不费劲,个人比较喜欢中英文双语的写法。

    例如:

    # 我的世界 Minecraft

    > 《我的世界》是一款沙盒类电子游戏,开创者为马库斯·阿列克谢·泊松。游戏由 Mojang Studios 维护,现隶属于微软 Xbox 游戏工作室。游戏最初于 2009 年 5 月 17 日作为 Classic 版本发布,并于 2011 年 11 月 18 日发布 Java 正式版。我的世界的游戏平台囊括桌面设备、移动设备和游戏主机。 中国版现由网易游戏代理,于 2016 年 5 月 20 日在中国大陆运营。
    >
    > Minecraft is an open-world survival and multiplayer game, originally designed and created by Notch of Mojang.
    > Minecraft is available for PC, mobile and various gaming consoles, the game allows players to place and destroy a variety of blocks in a 3D environment. Within this 3D environment, players can roam around, free to do and build anything they want.
    tairan2006
        76
    tairan2006  
       181 天前   ❤️ 1
    如果是给国人用的项目,当然还是中文优先

    如果跟国别无关,一般优先英文
    themelody0
        77
    themelody0  
       181 天前   ❤️ 1
    我曾经见过多次有用中文 README 被喷的
    EatMi
        78
    EatMi  
    OP
       181 天前
    @begeneral #73 硬要说确实也没啥区别,影响不大。但不可否认这些东西还有会有一些意识形态的因素在里面的,只是想和大家理性讨论讨论哈,可以理解为纯粹是我的好奇,看看大家的想法
    chinaguaiu
        79
    chinaguaiu  
       181 天前   ❤️ 1
    很多中文项目自己刷星然后卖课,整个中文用户群体给人的印象瞬间不好了...写英文吧
    EatMi
        80
    EatMi  
    OP
       181 天前
    @themelody0 #77 这种情况挺多的,令人不悦😑
    wyl986
        81
    wyl986  
       181 天前   ❤️ 1
    在 GitHub 只使用英文可以过滤掉很大一部分垃圾用户和垃圾仓库
    wudicgi
        82
    wudicgi  
       181 天前   ❤️ 1
    我是把中英文写在一个 readme 里
    如果分开的话,首页放英文的比较好
    EatMi
        83
    EatMi  
    OP
       181 天前
    @chinaguaiu #79 这种情况确实,把脸丢到国外去了。
    EatMi
        84
    EatMi  
    OP
       181 天前
    @wyl986 #81 我比较同意你的观点,能够起到过滤作用。但是我认为用户倒是没有垃圾、不垃圾之分,只要用我的产品,就是好用户哈哈。不过提问、建群之类的,使用英文或者 TG ,来过滤一下,会有很好的作用
    dog82
        85
    dog82  
       181 天前   ❤️ 1
    没人看,不写
    agagega
        86
    agagega  
       181 天前   ❤️ 1
    现在有了 ChatGPT ,不如再加上日文、德文、法文、西班牙文、俄文的 README 。

    https://github.com/github/markup/issues/899 GitHub 用户希望能有多语言 README 支持已经很久了,只是迟迟没一个官方方案。起码法文的俄文的西班牙文的我都见过,人用母语不可耻
    RainCats
        87
    RainCats  
       181 天前   ❤️ 1
    中文,如果其他语言群体有需要,他们会自行翻译,翻译工具这么多,甚至还有 AI 工具
    ZeroDu
        88
    ZeroDu  
       181 天前   ❤️ 1
    两个都 提供,默认英文,毕竟 github 也是全英文的,英文也算是国际比较广泛的语种;
    但是非常反感装老外,好像写中文掉价一样。同时国内程序员群体还是很大的,中文还是很有必要的。
    ryan4yin
        89
    ryan4yin  
       181 天前   ❤️ 1
    维护两个版本太麻烦了,我 README 只有英文的,因为感觉想看我这项目的人,这点英文读下去应该没难度。
    andytao
        90
    andytao  
       181 天前   ❤️ 1
    中国人维护的项目强烈建议一定要有中文,有没有英文自己看着办,但一定要有中文,因为中文是我们的母语和根,不能丢了自己的根呀。

    Github 是英语社区,它就没有提供多语言的规范和支持,说明啥?

    说明它期望甚至强迫我们写英文文档,丰富英文社区,可我们是华夏儿女,用的是中文汉字呀。咱们不能用自己水电和生命,单纯去丰富他人的社区,进而导致了我们的儿孙看不懂、学不会我们创造的东西。
    ZeroDu
        91
    ZeroDu  
       181 天前
    @ZeroDu #88
    补充:
    对于一些随便写写,不准备推广,搞社区的项目我的观点是:“写不写管你屁事”,甚至 README 都没有
    andytao
        92
    andytao  
       181 天前
    中国人维护的项目强烈建议一定要有中文,有没有英文自己看着办,但一定要有中文,因为中文是我们的母语和根,不能丢了自己的根呀。

    Github 是英语社区,它就没有提供多语言的规范和支持,说明啥?
    https://github.com/github/markup/issues/899
    说明它期望甚至强迫我们写英文文档,丰富英文社区,可我们是华夏儿女,用的是中文汉字呀。咱们不能用自己水、电和生命,单纯去丰富他人的社区,进而导致了我们的儿孙看不懂、学不会我们创造的东西。
    andytao
        93
    andytao  
       181 天前
    Github 是一个国际社区,它没有提供 README 的多语言规范指引和支持,说明它有一定的文化殖民倾向。

    只要我你他的儿孙还是用中文,就应该优先用中文写 README ,这样他们就可以循着足迹找到我们的作品,了解我们曾经的过往,老外看不懂可以用翻译嘛,不用太考虑他们。
    wangmou
        94
    wangmou  
       181 天前
    看受众。其实最烦的就是那些受众是国人,然后非要装逼写英文,外国人又用不到你那东西,英文写的也别别扭扭何必呢。。。
    dif
        95
    dif  
       181 天前   ❤️ 1
    如果你主要针对国人,那就中文优先。
    如果你野心大,要面向国际,那就英文优先。
    andytao
        96
    andytao  
       181 天前   ❤️ 1
    如果软件或库很优秀,就算 README 用的是中文,老外会用翻译工具来学习使用它;
    如果软件或库很低劣,就算 README 用的是英文,国内国外用户都不会有人来鸟它;

    README 用中文还是英文很关键吗?不是,那么用最省力的语言写 README 就好了。
    EatMi
        97
    EatMi  
    OP
       181 天前
    @wangmou #94 兄弟,感觉你稍微有点偏激了,人家本来就是开源免费的东西,为爱发电,而且作为作者本人的东西,写什么也都无可厚非,没有必要这么说,平和一点嘛,可能也不是要装逼,可能就是想锻炼一下,或者往功利处讲,可能写英文更有利于他本人呢,比如找工作加分项等
    EatMi
        98
    EatMi  
    OP
       181 天前
    @andytao #96 对,你说的在理,但是项目初期的话,个人项目,可能还是稍微会有点影响的。但这也不是重点,更想和大家讨论的是主观层面的意愿和倾向
    wangmou
        99
    wangmou  
       179 天前
    @EatMi 有些人写的东西一看就是机翻出来的,话都不通顺还加分项。
    EatMi
        100
    EatMi  
    OP
       179 天前
    @wangmou #99 对,你说得对,每个人一开始不都是从菜起步的吗。可能的确有些人纯为了装逼,随便机翻就放上去,观感也不好,但是和我说的有冲突吗?你不自己也说了有些人,那还是有些人,英文的 README 也是用心好好写的吧,这种不应该算加分项吗?
    1  2  
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   2581 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 38ms · UTC 00:29 · PVG 08:29 · LAX 16:29 · JFK 19:29
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.