Hi everyone 大家好我们今天演讲的主题是KBS的文档我先做一个自我介绍我目前是能够就这一Docloud在KBS社区里面应该贡献了两年多目前是中文文档的Owner然后英文文档的Reviewer当然KBS的生态里面也做了一些贡献像East Show里面我是Docus的Ventainer还有Kamada的Reviewer像还有一些Sandbox的也有三四个是Maintainer反正我觉得主要就是做文档的Technical Writer主要是Support的开发工程师写一些基础文档对好我们今天主要回来主题讲主要KBS文档KBS有一个对外的对用户的文档叫KBS.io它是面向用户的还有另外一个文档是面向开发者的就是面向你贡献者的叫KBS.io对这两个网址大家可以记一下然后就可以直接点进去看然后所有的技术问题都可以在KBS.io上面找到基本上像KBS.io去年的它有Google的缝隙上面有一个数据2022年的访能量在1个亿对 1.1亿的已经达到在2B领域来说这种网站已经进入了1,100了我们可以看一下它访问最高的页面是哪些比如说第一个叫KBS.io的一个缺德系的就是有很多命令就采讯来采讯命令的下面就是像Service英格尔斯的一些网页对好然后我们在有一些统计数据在OSS Insider上面也能看到看到我们过去一年或者10年内的应该都可以看到我们的贡献数据目前的STAR数了COMMENTS都可以看得很清楚另外KBS它有一个专业的就是CNCF提供了一个Devastated上面提供了哪些公司做的贡献你可以看到国内也经常能看到我们Docl的名字对SigDocl是排名的贡献在前面的除了KK主库我们的K-Website就是第二个货业的网站了第二个货业的藏库了总共KBS现在有76个藏库了吧对我们的Website是排名第二的对那现在讲一下我们KBS的文档它所有的文档经常都是用Mac当的写的Mac当就是一种充分本的那种格式就用一些简单的标记就可以实现了这可以Headings标题了Link了还有可以加一些列表像表哥包括你的代码端各种各样的代码端可以用不同的颜色来显示然后图片的话就可以直接很方便就可以引用了对KBS它编印的一个静态编印的那个编印器是用的HugoHugo是一个免费开源的目前来说将KBS的E-S修了包括Continuity应该用的都是Hugo它都是原码都是用的Mac当我们的就原的就是DocumentDocument as a code就是code文档也是一种代码把一切当成代码来运行然后你要编一这个文档的时候就把它放到一个容器里面运行像常用的一些短代码怎么用Note的两边就像那个勾引那个标记一样两个大过号那个小过号一样是的接下来就是用一个那个文档的结构这是一个Hugo的标准结构像第一个LKTypes里面就放一些模板文件把我讲出了一些什么是content什么是concept什么是task什么是reference像task就是要有123456步骤concept就是要有一个三段式八股文三段式要说清楚这个概念是什么样子的OK那第二个像Hugo的Note这是Hugo在编译文件的时候它有一个种的配字文件就读取这个配字文件来把整个往在编译成Html文件那第三个content里面就放了我们所有的文档文件如果你要提文档皮牙的话就可以在content里面找到了找到你可以修改的这些文件它里面就包括了像kabs现在有16个语言英文English是sauce你在英语文件里面我们是传议的嘛传议的中文文档比较多你可以在zh.cn里面找到很多中文文档如果发现中文文档有时候它可能有错别字了或者是404.link或者是跟英文不一致你都可以去tpr对然后接下来data文件家里面就是Yama文件了像你在release的时候有一些配置的东西OK接下来我们不要一个一个讲了反正hugo我们用的就是dokshi的一个主题最后有一个scripps文件家里面它自备了一些脚本文件你在做公信的时候可以用这些我们开发着以前定义的一些脚本来检查一些link只要运行那个脚本就可以发现哪些link是断开的那些中文文档跟英文不一致哪些法语文档跟英文不一致都可以很方便地看到对 右边这是一个编译的过程你看根据我们有比如说我们有三个concept五个task然后全部从container里面找出来经过我们的hugo的编译级编译编译出来就会形成呈现上百个html文件那就是构建这个网站的一个基础文件但是编译这个hugo的时候它有几个要点就是说像刚刚一样我们把所有的文档当成代码来运行然后把所有的marcann文件三三html文件然后总配置的文件就是hugo.tomo主题是用的doxy对那右侧这个hugo.tom就是基本上就是我们总文的配置文件一般是不怎么改的除非是新增了一些语言现在我们有16个语言如果有新增第17个这个可能就会修改一下然后就是有一个netify我们的原文件叫markdown然后编译的时候用的是hugo那编译出来的文件图管在哪呢就图管在netify上面去它是跟hugo完美接口的对它可以把所有kbs编译出来的文件放到netify上然后它也实行CICD跟kit opus是完美契合的当然它也有一个总的配置文件叫netify.tomo你看右侧的就是netify.tomo的总的配置文件这个配置文件从那个我们kwebsite的readme里面都可以找到都可以找到这些链接的对好那现在我们就是用了三种一个是kitkit opus一个是hugo一个叫netify三个加起来就有了魔法了像第一个你kit上面就图管了原文件像markdownhugo的一些配置文件netify的配置文件然后中间经过一些hugo的编译新称了那种html最后全部图管到netify这样整个网就bube出来了目前我们官方的kwebs支持的是四个版本社区目前只维护最新的四个版本文档是多了一个是五个版本然后我们目前的本地花园有16个之多所以我们需要很多的贡献者像一贡献量最大的应该是英国的一区然后本地花方面像亚洲语言还是比较多的我们韩语是本地花里面排名第一的那接下来就是像日语韩语还有印度语印度语现在也不能小小印度语的贡献量每天都可以看到pia目前我们localization的那个leader是一个韩国人他负责前头我们本地花的一个方向对OK接下来就是说我们要怎么去长运贡献那为什么要长运贡献里面看来是这个网站已经经过了千吹百烈里面那些很多技术都是在网站方面都是经过教验的经过验证的如果你了解了整个流程的话在你自己不管是公司也好个人也好都可以把它用起来而且你还可以再学习一些网站的编写技巧style guide还有gith的工作流程熟悉一些基本的命令当然社区里面有很多那种文大大大佬他在编写整篇文章甚至是某些段落都会有非常有想法你贴了pia之后他会给你非常详细的commentsOK其他就这样对基本上就是你要做贡献的时候首先你要熟悉一些基本的magnon的语法像如果你在百度上面收受magnon的语法一般来说十分钟左右就可以了解一些magnon的语法是什么样子的它就是一种文明的命令gith的命令也比较简单你就常用的就那么十来条命令熟悉了以后也没什么当然还有github是做work flow你签那个做贡献之前需要签署一个CLA叫做贡献者那个认可的协议如果你不签这个协议的话一般来是没人帮你review的对然后我们就看一下怎么tpr最简单的tpr的方式就是你随便打开一个开发的网站的页面在上面就有一个按钮叫做编辑词页或者编辑本页added this page按点击那个按钮它就可以弹出来一个编辑的编辑的那个窗口你就可以编辑你的mark比如说找到错别字了直接编辑编辑完之后就可以去网应上面点击提交提交完之后你可以选择写一些comments每一个pr它有一个description叫描述的地方你要说清楚你为什么要提这个pr然后你提了这个pr对社区有什么作用这样在方面变成来review你的pr很快就可以合进去如果你要什么都不写的话就好像陌生人见面一样很冷漠的样子最好是写一个你的描述文件最后就得提出来一个pr那提了pr之后就等着去review当然另外一个正常的tpr的方式这是一种这个是pony的fork从forktpr的时候就是你要去找到get that Kubernetes的那个窗户然后点一个forkfork它你的自己的空间里面去然后你把它用get clon命令把它clon到你的本地clon到你的本地之后你可以通过一些刚刚那个脚本文件里面的脚本来找到一些哪个地方可以tpr或者从getpr的列表里面可以发现一些tpr的地方对就可以在本地修改本地修改完之后你就可以运行get命令把它push到website上面去然后就可以tpr对可惜今天我们不能demo就大概讲一讲tpr之后也不是结束了tpr它只是一个开始tpr之后肯定会有人给你comments首先那个是一个机器人叫propro它会说它会通知对应的reviewer说有一个pr上来了比如说你提了一个中文难得pr它就会给一个这个中文有一个team中文有一个专门的本地化team把team的相关会优先选两个最近活跃的给两个最近活跃的发邮件告诉这两个reviewer说有一个中文的pr提上来了然后让他们来review一下然后同时那个pro这个机器人他也会通知那个netify去把这个网站里面进行一个预览版本review一下同时那个pro这个机器人也会检查贡献者是不是签署了cra然后如果reviewer到时候给了你觉得你这个tpr没有问题他会给你一些label比如说look at good to me或者pro那个reviewer刚刚收到你的邮件了说有个人tpr上来了他就会进入首先要做一些technical review比如说signal的一些他会很technical的一些内容首先要technical看你对不对如果他觉得没有问题了他会给你打一个look at good to me然后接下来就是要我们technical review要上场了就是我要看你的style是不是对的跟我们的你提了一个评我们其实里面还有很多有几千三百个文档在里面的你要跟我们的style一致不能因为你的个人的风格就把整个网站的风格全部都改掉了对 首先像每一个仓库他都有自己的风格然后如果你的没有问题那他就会给你uploadupload的这个label两个label起了之后那pro接下来就收到了就告诉我说这个pr可以莫及了等这个cr跑完之后pr就可以合进去然后netlify就把整个网站重新build一遍把原来的覆盖掉对ok像我们kwebsite的主要负责的团队叫做sigdogsig是一个兴趣小组的意思就是专门对文档有感趣的小组那是一个到时的主要组的架构就是最下面的是manber最下面的是各种各样的contributor是贡献者不管你是不是manber还是不管是你来自哪儿都可以来做贡献这个极数是最大的可能有成千三万可能成千三万的不止现在kwebsite的manber就应该有成千三万个像上面这个框框里面这些蓝色的它就属于那种管理性子的就reviewer了approver owners现在加起来有100多位吧它会分开的首先左边是英语英语是属于所有文档的上游英语它有reviewer owner上面还有一个例子例子上面还有一个委员会委员会就是一回定期选举像我们中国人这边的话传议的主要是做localizationlocalization目前加起来有二三十个人reviewer和owner加起来二三十个人然后localization它种子上面有一个例子这个例子它不光是汉语它包括法语德语 意大利葡萄牙语 汉语它有个种的管理人目前是一个韩国人它在社区应该很活跃了SEO开头的一个ID以前是前两年是我们腾起鸣是我们中国的这两年变成一个韩国的了接下来就是讲一些文档的style和guide首先是content的guide就是内心内容可以放到kbs网站上像kbs的网站粘坊容量已经过一亿了去年是一点一亿那今年可能会更高可能会达到1.3 1.4亿这么高的访问量就会增加你的曝光度不管是你的私有项目你的公开捐献出来的项目也好还是你的想法也好只要你能发一篇blog我们的kbs.io网站上就会增加你的曝光度像我们Docloud有一个项目叫cork就是因为在kbs网站上面发了一篇稿我们的star数就增加了一千多star而且是自然增长的一千多star对第一个就是什么内容可以放到kbs网站上然后第二个中间这个就是style guide说了一下你的段落应该是什么样式的比如说某一段落如果你超过一两百个字应该在第一百个制服的时候走个行这样就方便我们review而review然后那个每个code block的时候可以前面加一些压马或者go了这些代码标志让他们把不同的辨量显示出来然后就是其他一些style guide的说法当然还有一些图片的概的图片的概的我们建议用momei的momei的是一种用markdown的歌词来写做图片的做流程图的工作一些flow chart之类的是的它这个momei的做的图片很方便做多语言翻译因为你如果用png,jpg或者甚至是bmp之类的你做了英文版的图片就做好了但是这个很不方便做多语言因为你我已经找不到当初你是用photoshop做的在elastic reader做的那个圆稿了而且那个圆稿的图片会很大有时候一个photoshop的那个图片可能就会有几百兆那如果是momei的话它就几k或者更小里边的每个文字还都是可以编辑的这样子做图片就比较方便对然后就是我们欢迎每个月我们这个sigdox都会有一个例会你可以在kbs.dev网站上面可以看到对对 下面这个网站就是kbs.dev网站上面就列出了我们的日历然后每个月它都会有个定期的会议有时候是sigdox是美国人主持的那localization就是我们中国人主持有很多中国人参加的最近是韩国人主持的韩国人主持的虽然是韩国人主持但是也有很多中国人参加的对然后左边就是一个slag的频道还有一些邮件的列表欢迎大家去参加好 这都是open的谁都可以来参加OK 我这边就结束了接下来就请我们360的李欣讲一下本地话方面的一些东西大家好 我先做个自我介绍吧我是李欣然后来自360目前的工作是专注于调度和分布式训练加速这块然后我们前是我KNOEL项目的Approver如果有这方面想跟我交流的然后会后也可以跟我交流然后我给他把ID是HWDEF今天我就不讲调度跟分布式训练相关了我就接着那个海峰的讲我讲一下本地话的也非常感谢海峰刚才的演讲就是我四年前第一次接触KBS的时候KBS丰富的文档给我了特别大的震撼然后我感觉文档就是对一个使用者的低印象然后我讲一下当跨过这个低印象之后进入到KBS之后我当我使用的过程中的可以说是第二印象或者第三印象这么一个东西它是本地话我会介绍两方面一个是大概介绍一下本地话相关的东西然后第二就是讲两个真实的样利也是我在社区中的一些贡献首先我们聊一下这三个概念就是国际化本地化和全球化这三个概念其实它比较模糊在网上搜集资料的时候有的说国际化包含本地化有的说国际化和本地化是有交集的就像我这样图一样然后这个就是我在中文危机百科上找的然后我觉得这个概念其实它不是很重要吧就是其实我们都知道它是一个什么东西然后我的理解是本地话就是站在特定国家地区和文化的角度去适配软件让用户使用的更方便然后我今天其实它包括很多东西比如翻译比如一些法律宗教文化都有但是我今天就主要讲一下本地化的翻译方面首先就是一个问题它本地话是否重要因为有很多软件它也不做本地话或者本地话做得不好因为这个就跟代码无关所以承轩可能觉得当然我也承轩并没有冒犯承轩就很多承轩觉得这个是后面的工作先把代码信号但是我在了解了之后我觉得本地话还是非常重要的我从三个方面说明比如这个第一个方面就是我觉得本地话是被无关之使用被无关之设置的就比如当我们拿到一个电脑的时候我们给它安装操作系统然后我们第一次启动的时候会让我们选择语言地区等等设置然后我们进入系统之后比如中端还有浏览器就会读取这个系统的设置然后把自己的语言也设置成这些比如这个Chrome它会根据操作系统的设置把自己的语言也设置成中文然后中端的话就是会这几个环境辨量它会设置一下也设置成比如我选的系统语言是中文的话它这块也会设置成中文然后有一些软件比如Cube CTL比如Dashbar的等等这些它运行在中端或者浏览器当中的时候它会读取这些配置比如这个代码就是我解的Cube CTL的图它会读取这三个环境辨量的配置然后设置自己的语言然后Dashbar的它会读取这个配置然后设置自己的语言所以说对于用户来说它会奇怪我没有设置成中文但是我默认就使用中文了所以这个也是我觉得是督促开发者去适配的一个因素吧然后第二个就是我觉得本地话也会是在我使用软件过程中的第一印象右上角这个图是我刚结不久的一个Cube CTL目前的本地话的一个状态就可以看到它上面有一些已经翻译过了然后有一些没有翻译过这样就会给某些比较注意的人就是他会觉得这个软件不是那么的精致然后如果我给它全翻译过后就是显得比较正规了这么一个软件我觉得对于比如KBIS这么庞大的这么一个软件或者专业的这个软件下面这种应该是必须的然后第三个就是我觉得是比较重要的因为前两个提到的只是光感不好第三个就是我觉得会有一些错误的引导比如我一面上有个按钮它显示的是更新一个POD但实际上因为在本地话过程中一些错误它被翻译成删除一个POD了那么这个问题就会比较严重了所以我觉得在本地话过程中也需要非常严谨然后经过前面的三个点我觉得我已经说明了本地话它比较重要了然后下面我想进一步说明对于一个新手来说为什么应该从本地话着手既然了解整个社区和项目我觉得本地话是一个新手村吧就是开源世界的一个新手村第一就是它非常简单就是你只需要专注一些翻译和一些少量的代码然后第二个就是它比较广泛所有语用户有沟通 有交流的软件你都需要本地话然后第三个就是它又不止是翻译它会涉及一些脚本一些工具级的使用这个会帮助你去了解整个项目然后第四个就是它有些社区的支持就是比如Select里如果你遇到任何问题你在Select这个频道去问的话应该都会有人去解达的然后第五个就是它有些官方的指导比如我下面给这个链接就是KBIS的官方对于本地话的一些指导然后刚才那个海峰讲了文档相关的那我想对比一下本地话和文档它的这个在翻译过程中有什么不同首先他们设计的范围都是比较广泛的因为什么都会翻译基本然后在他们及时性上也都是非常高的然后你代码或者是软件有个新的版本你必须也要翻译也要跟进然后在历史留存方面我觉得是有一些差异的就在本地话的过程中它永远只保持最新的这个翻译然后文档的话你翻译过后就会一直留存在那儿了然后长短的话本地话它就比较短就像我刚才解那个图基本就是一句话就完事了但是文档的话就比较长一般都是一篇博文或者是一个使用指南之类的然后写不写代码呢本地话它可能会写一些代码比如一些晒药脚本一些自动工具之类的文档几乎就不怎么写代码了然后下面我介绍两个项目这两个项目都是我亲自参与的一个是Dashboard一个是Kubectl这两个项目其实对于KBS老用户来说都是已经非常熟悉的了我就简单讲一下我们前来是Dashboard的中文本地话的这个Opso World首先说一下Dashboard的Dashboard是什么呢那对于我就给初学者者讲一下这块就是官方的说法是Dashboard是一个通用的基于Web的UI适用于Kubectl的集群它允许用户管理集群中的应用并且对其进行故障排除并且它可以管理集群本身它的使用其实就像图中一样就是用户通过Dashboard的这个网页然后它可以去查看集群管理集群然后上面这个是Dashboard的官方的一个架构图Dashboard的它的本地话流程是什么呢因为Dashboard它用的是Angler这个前端所以它的翻译过程中也要参考Angler的这个指南就是下面这个链接然后它的流程其实相对来说比较简单了首先就是我需要一个原语言的文件就是一般都是英文语言了然后我copy一份就是把这个语言复制一份出来这个语言文件然后给它重明名一下重明名的时候我把中间加上这个语言的这个代码比如这个就是简体中文然后我就可以翻译这个语言了翻译这个语言文件了翻译的过程中是怎样的就是把这个点插LIF这个文件打开的话下面就是像这样它有很多这样的然后它用一个TransUnit这么一个单元包裹起来然后里面有两个一个Source一个TargetSource就是你要翻译的原语言的内容Target就是你要翻译的语言就是当你执行完这部之后它其实Target这块也是英文的然后你需要做的就是把这个英文翻译成你需要翻译的语言对于我来说就是中文然后翻译过后呢你就可以保存这个文件然后创建一个PR然后去审核然后审核过后你的这个代码就会被合并了你这个翻译就会不合并了那么审核的流程我大概说一下就是刚才这个海峰也提到了其实跟文档审核的是一样的首先你需要提交你的代码然后创建一个PR然后机器人会给你这个PR它去分配一个审核者这块一般就是一个翻译的审核者如果你是在dashboard的话很有可能这块就会分配给我了然后如果审核通过的话那这个就会被合并了如果没通过的话你就需要修改然后再提交代码然后我再次审核然后这套流程走下来直到这个东西被合并然后下面就是一个PR被合并之后它的样子然后我们再讲一下QB-CTL这个工具这个工具相信就是用过KBiS的都会接触到它就是一个命令行然后可以去跟KBiS进行交流它通过QBiS API它可以增山改啥也就是这些那么它的本地化流程就比较复杂了跟刚才讲的dashboard相比它比较复杂了首先它用了Gatex这个东西这个是GNU组织下它开发的一个工具级它包含这些二斤制然后这些二斤制怎么使用呢我们就跟着这个流程图来讲吧首先你需要原码那这块我们就是QB-CTL的原码然后从原码当中提取出这个需要翻译的字幕创用XGatex这个二斤制然后你会得到一个POT fail这个POT是一个翻译要用的文件那这个T是什么意思呢就是template就是样历的那个单词所以这是个样历文件然后你拿到样历文件之后你可以做什么呢这块就出现了一个分叉如果你是个新的语言的话那你需要创建一个新的POT文件用MSG init这个二斤制如果你是更新一个已有的语言比如中文啊那么用MSG merge它会把比如你POT文件中有10句话然后有5句是被翻译的然后你POT文件中有5句话这5句话其实已经翻译的那会把POT文件中这个为翻译这5句话摘到这个POT文件中然后无论这两条你选择哪个其实你最后都会得到一个POT文件然后你就可以去翻译这个POT文件了这块QB-CTL的官方推荐的是用Pro-edit这个软件这个软件后面我们会讲一下然后你就可以来翻译过后的得到翻译过后的POT文件然后你得到翻译过后的POT文件就可以用它去生成一个IMO文件其实我们最重要的产物是IMO这个文件是用MSG FMT这个二斤制然后你得到IMO文件之后就可以直接去编译QB-CTL的二斤制了你就得到已经带着翻译的二斤制你就可以直接用了那么下面我来介绍一下Pro-edit这个工具吧这个工具它是QB-CTL官方推荐的工具然后它这个功能非常强大而且比较直管而且比较直管因为可以看到左边就是英文然后右边就是中文然后黄色的就是提醒你这块应该翻译了如果是黑色的就证明它已经被翻译过了然后我们直接用它打开POT文件可以开始翻译翻译过后你点保存它自动给你生成IMO文件然后其实你很多事情都不用管了然后它也完全支持POT格式也完全支持GateTest这些工具级然后就说一下QB-CTL的审核流程其实它的审核流程跟Dashbar的完全一致但是只有粉色这块不一致它不一致的地方在哪了就是Dashbar你只需要一些翻译的审核员审核就可以了但是QB-CTL它还需要代码的审核员就审核这个一方面是因为你的改动可能涉及代码因为QB-CTL这块翻译它有一个自动化脚本你可能会改织脚本等等第二就是因为它这块的全线切割不是那么的清晰它这块全线切割就是你必须要QB-CTL代码那块的审核员去批准才行然后最后我想说就是大家都参与进来就是无论你从哪开始无论是QB-CTL、K&HALM这种二斤制或者是Dashbar的这种网页的应用无论从哪开始都可以其实无论你做了多少其实你翻译一句话或者是修改一个单词其实都是比较在社区里都是比较欢迎的然后无论你从哪方面开始都行你可以从翻译然后比如适配一些你的地区的国家的文化或者你甚至从一些梗来翻译都可以然后如果你想保持沟通的话其实KB-CTL社区它用slag用的比较多你可以从这些slag频道中获取一些帮助当然你可以去把这个后阵改成自己的语言比如这个是韩国嘛这是法国然后如果你是中文的话这块应该就是CH了我相信在这些频道中的这些开发者都会很愿意去回答新手的一些问题然后我要讲的就是这些谢谢大家