V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
• 请不要在回答技术问题时复制粘贴 AI 生成的内容
EatMi
V2EX  ›  程序员

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

  •  2
     
  •   EatMi ·
    wy-luke · 2023-08-31 13:29:56 +08:00 · 6036 次点击
    这是一个创建于 474 天前的主题,其中的信息可能已经有所发展或是发生改变。

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

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

    会考虑很多因素

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

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

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

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

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

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

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

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

    第 1 条附言  ·  2023-08-31 19:29:05 +08:00

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

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

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

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

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

    101 条回复    2023-09-16 19:03:23 +08:00
    1  2  
    eyelly
        101
    eyelly  
       2023-09-16 19:03:23 +08:00
    个人看法也是看当前库的受众,如果仅限国内用户,只需中文文档即可;否则的话,默认语言应该还是以国际通用语言英语为主,然后可以加上中文文档链接。



    哈哈哈,打个广告,后续皆为广告😊

    之前我也为如何同时维护多个语言的 README 文档而发愁,因为文档的内容或者结构发生变化,然后又需要调整多个语言的文档还是挺繁琐的。然后采用了一个策略,将 Markdown 文件当做是产出的资源,通过 js 代码来动态生成,这样不同语言就可以抽取出独立的语言包,整个文档结构是在代码中固定的,后续调整只改 js 代码的结构而不用每个语言都改,这样就看似很像日常前端开发中给前端页面添加多语言功能。

    然后,上述的这套逻辑,已装了一个工具 https://github.com/eyelly-wu/jsx-to-md ,它可以像平常写 React 一样来编写 Markdown ,举个例子

    // 这里文案的内容通过 t 函数标记了,是需要多语言处理的内容
    export function Temp(){
    return (
    <>
    t('这是一段中文描述,这是后续的描述内容')
    </>
    )
    }

    然后再配上另一个国际化的工具 https://github.com/i18n-pro/core ,它可以识别出需要翻译的内容(例如上述代码示例中的“这是一段中文描述,这是后续的描述内容”),并调用第三方翻译平台的接口(例如 谷歌和 OpenAI 等,还不止这些)对内容进行翻译并生成生成各自语言的语言包(当然翻译的内容效果不保证一定很理想,但是调整语言包也很方便)

    有了语言包,以及固定的文档结构,就能生成不同语言但结构相同的 Markdown 文档了。后续无论是文档内容的变化或者是新增语言的支持,都将变更轻松很多。


    最后,上面提到的两个工具的中英文文档都是这样生成的,热烈欢迎各位开发者朋友的尝试😊
    1  2  
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   5508 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 22ms · UTC 08:57 · PVG 16:57 · LAX 00:57 · JFK 03:57
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.