如何向微软 Docs 和本地化社区提交翻译贡献

Docs (docs.microsoft.com)是微软新版的文档网站,重新规划了各项技术栈的文档结构,看起来比 MSDN 可读性更好。虽然 Docs 提供了各种语言的版本,但大多是机器翻译,某些中文文档基本读不下去。因此微软鼓励社区参与者提交本地化内容。对于微软 MVP 来说,参与 Docs 的本地化也是一种重要的贡献方式。除了 Docs 的本地化,微软还有一个本地化社区,可以对微软的多个软件程序进行本地化:Microsoft Localization Community。接下来给大家介绍一下如何向这两个项目提交贡献。如果你已经很熟悉Git操作,可略过本文。

排行榜及积分规则

微软发布了一个排行榜,可以看到全球贡献者的分数排名:Microsoft Cloud + AI International Community Leaderboard(https://microsoftl10n.github.io/)

如何向微软 Docs 和本地化社区提交翻译贡献_第1张图片

计分规则是这样的:

  • 对于 Docs 来说,每项建议得15分,如果微软审核后接受建议,则可以得到60分。也就是说一项建议最多得75分。

    1. Docs 本地化得分 = 建议数 * 15 + 接受建议数 * 60

    2. 一个建议 = 15分

    3. 一个通过审核的建议 = 60分

  • 对于软件程序来说,如果审核并修改一个包含10个单词的的句子,可以得20分。如果该翻译被微软批准,则可以得到80分。也就是说翻译10个单词的句子最多得100分。同时如果审核其他人的翻译并投票,可以得2分。

    1. 软件本地化得分 = 建议单词数 * 2 + 投票数 * 2 + 接受翻译单词数 * 8

    2. 一个建议的单词 = 2分

    3. 一个通过审核的单词 = 8分

    4. 对其他人的翻译投票 = 每个投票2分

     

当然我想强调的是,我们并不是为了得分才去做贡献,提交 PR 是一件很有成就感的事情,你的贡献能够帮助到他人,同时对自己也是一个提高,这才是 Contribution 的意义所在。

向 Docs 提交 PR

下面详细介绍如何对 Docs 提交 PR(Pull Request)。

直接在页面上修改

第一种方式是直接在页面上修改,适合修改单个词语、句子或文章。点击链接:微软Docs 进入Docs网站,可以选一个类别的文档进行修改。但注意有些文档还没有提供本地化内容,也就是还没有提供可供修改的GitHub repo。以该页面为例:https://docs.microsoft.com/zh-cn/dotnet/standard/design-guidelines/choosing-between-class-and-struct

如何向微软 Docs 和本地化社区提交翻译贡献_第2张图片

“每个框架设计器的人脸的基本设计决策之一……” 这什么乱七八糟的。Bing 翻译的质量还需提高啊。

首先点页面右上角的 登陆按钮,这里需要使用 GitHub 账户,没有的话先注册一个。然后可以看到页面上方有几个链接:

可以点击 反馈 按钮来提交你的反馈意见,相当于发布评论,会显示在页面下方。如果想编辑翻译的话,就点击 编辑 按钮,这样会直接链接到该页面在 GitHub 上的地址:

要编辑的话,就点击那个笔形的编辑按钮:

然后就可以直接编辑了,注意页面上方的说明:

如何向微软 Docs 和本地化社区提交翻译贡献_第3张图片

使用这种方式会自动在你的仓库中创建一个分支。点击下面的 Propose file change按钮:

如何向微软 Docs 和本地化社区提交翻译贡献_第4张图片

这样会自动生成一个页面,对比所做的修改,点击绿色的 Create pull requet 按钮就可以创建一个 PR 了:

如何向微软 Docs 和本地化社区提交翻译贡献_第5张图片

创建 PR:

 

可以看到,这种方式实际上是创建了一个名为patch-1的分支:

如何向微软 Docs 和本地化社区提交翻译贡献_第6张图片

等 PR 被批准并合并之后,会提示你将该分支删除,因为该分支已经没用了。按提示操作就可以了。

Fork 项目到自己的仓库

直接在页面上修改的方式虽然简单,但只能在线操作,如果遇到断网或系统崩溃,可能会丢数据。此外,只改几个单词就提交一个 PR,显得比较零散。因此建议 fork 项目到自己的仓库,在本地修改后,再提交 PR 。本地编辑使用 VS Code 或其他编辑器,也不会丢失数据,VS Code 会自动暂存修改。

Fork 相当于一个仓库的副本。将源项目 fork 到自己的仓库可以让你随意修改代码而不会影响到源项目。并且你还可以将你的修改提交到源项目。一般流程是这样的:

  • Fork源项目到自己的仓库

  • 修改

  • 向源项目提交 Pull Request

 

如果原项目作者同意了你的修改,会将其合并到源项目中。

Fork 项目

首先,打开官方项目的主页面,将其 fork 到自己的仓库:

如何向微软 Docs 和本地化社区提交翻译贡献_第7张图片

这样会在自己的账户内生成一个新的项目,并显示是从源项目 fork 过来的:

如何向微软 Docs 和本地化社区提交翻译贡献_第8张图片

使用 VS Code,将项目 Clone 到本地。没有 VS Code 的话就装一个吧,前端神器,集成 Git,用来写 markdown 也是极好的。Docs 的文档都是markdown 格式,所以 VS Code 很适合干这个。

点击 Clone or download 的按钮,再点击路径旁边的按钮,将项目路径复制下来:

因为 VS Code 已经集成了 Git,所以 VS Code 中也有两种不同的使用 Git 的方式:

  • 按 F1,调出命令输入框,输入 Git,即可看到支持的各种 Git 命令:

     

  • 按 Ctrl+`,也可以在 Terminal 窗口中直接输入 Git 命令:

     

    如何向微软 Docs 和本地化社区提交翻译贡献_第9张图片

选择自己喜欢的方式即可。如果使用第一种方式,就选择 Git: Clone 命令,然后输入项目路径,回车,会弹出一个选择文件夹位置的对话框,选择后确定即可将项目 Clone 到该文件夹中。

如果使用第二种方式,首先要定位到你要存放该仓库的文件夹,然后输入:

git clone https://github.com/YOUR-USERNAME/dotnet.docs.zh-cn.git

如何向微软 Docs 和本地化社区提交翻译贡献_第10张图片

设置与源项目同步

Clone项目后,还需要设置一下,将本地的项目与源项目(upstream)关联起来,这样就可以进行同步了。

使用Terminal导航到项目所在目录,输入以下命令:

git remote -v

输出如下:

c:\Source\dotnet.docs.zh-cn>git remote -v
origin  https://github.com/YOUR-USERNAME/dotnet.docs.zh-cn.git (fetch)
origin  https://github.com/YOUR-USERNAME/dotnet.docs.zh-cn.git (push)

接下来,输入以下命令设置本地目录的 upstream:

git remote add upstream https://github.com/dotnet/docs.zh-cn.git

再输入之前的命令查看,显示已设置成功:

c:\Source\dotnet.docs.zh-cn>git remote add upstream https://github.com/dotnet/docs.zh-cn.git

c:\Source\dotnet.docs.zh-cn>git remote -v
origin  https://github.com/YOUR-USERNAME/dotnet.docs.zh-cn.git (fetch)
origin  https://github.com/YOUR-USERNAME/dotnet.docs.zh-cn.git (push)
upstream        https://github.com/dotnet/docs.zh-cn.git (fetch)
upstream        https://github.com/dotnet/docs.zh-cn.git (push)

创建分支

回到自己的项目页面(不是官方源项目的页面),点击 Branch 那个下拉列表框,输入一个新的 branch 名称:

注意,选择的时候要注意是以哪个分支为基础,默认是 live 分支,你也可以选择以其他的分支为基础创建自己的分支。

创建分支后,就可以在本地切换到该分支进行修改了。我还是更倾向使用 VS Code 集成的命令,不易出错。

使用 VS Code 打开刚才 Clone 的项目目录,按 F1 调出命令输入框,输入Git,即可看到支持的 Git 命令:

如何向微软 Docs 和本地化社区提交翻译贡献_第11张图片

选择 Git: Checkout to...,选择刚才创建的分支:

如何向微软 Docs 和本地化社区提交翻译贡献_第12张图片

这样本地的分支就切换为刚创建的分支了,在 VS Code 左下角可以看出来当前分支是哪个:

如何向微软 Docs 和本地化社区提交翻译贡献_第13张图片

 

点击左下角这个地方也可以方便的切换分支。

如果使用命令行的方式,可以输入以下命令:

git checkout xy-test

输出如下:

C:\Source\dotnet.docs.zh-cn>git checkout xy-test
Switched to branch 'xy-test'Your branch is up to date with 'origin/xy-test'.

现在可以大胆修改了。

修改

这次我们来修改另一篇文档。打开 member.md,即https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/member页面的源文件。

对照英文原文进行翻译。为了查看 markdown 的效果,可以安装一个插件。点击 VS Code 侧栏的第五个按钮,打开插件管理器,输入 markdown 搜索,安装前面两个即可:

这两个插件能够有效提升你写 markdown 文档的效率,还可以在右侧预览效果。具体的功能可查看插件的说明。

修改完后保存。点击 VS Code 侧栏的第三个图标,可以看到已经有一个修改,输入 comment,然后点击对号提交。

如何向微软 Docs 和本地化社区提交翻译贡献_第14张图片

这样修改只是提交到本地仓库,还需要 Push 到远程仓库。点击右侧的三个点的按钮,选择 Push

如何向微软 Docs 和本地化社区提交翻译贡献_第15张图片

如果选择 Push to... 的话,还可以选择直接 Push 到上游分支,也就是官方的项目,但这样是没有权限的,所以只能先提交到自己的项目,再向官方项目提PR。

返回到自己的仓库页面,可以看到 GitHub 已经检测出来已经提交了一个更新,这时候就可以点击右侧按钮创建 Pull Request了:

如何向微软 Docs 和本地化社区提交翻译贡献_第16张图片

也可以点击 tab 栏的 Pull Request,也会有一个 New pull request 的按钮。这样会出现一个页面对修改后的文件和源文件进行比较:

如何向微软 Docs 和本地化社区提交翻译贡献_第17张图片

一定要注意上面的分支选择,是从我们自己的分支提交到源项目的分支,不要选错了。建议输入详细的 comment 便于官方人员检查。

最后点击 Crete Pull Request 的按钮,就成功创建 PR 了:

如何向微软 Docs 和本地化社区提交翻译贡献_第18张图片

等微软工作人员审核后,即可以被合并到主项目分支了。期间微软可能会做出一些修改。

删除本地分支

往往本地创建的分支都是针对一个 issue 做的修改,或者修复某个bug,或增加一个新 feature。当修改并成功被合并后,该分支就没用了。可以点击分支后面的删除按钮删除:

注意,一旦删除就无法恢复了,因此一定要确认分支的内容都已成功被合并后再删除。

与源项目进行同步

时间一长,我们本地的项目可能已经大大落后源项目的更新了。因此如果本地分支不是做出很大的破坏性变更的话,建议保持与源项目的同步。

首先点击自己仓库项目的 Pull Request 栏,点击 New pull request 按钮。

此时要注意,默认是将自己项目的更改提交到源项目,我们要反过来,将源项目的更改提交到自己的项目。

所以先选择左侧的下拉列表框,选择自己的仓库:

如何向微软 Docs 和本地化社区提交翻译贡献_第19张图片

这样两边都是自己的项目了,再点击 compare across forks 链接:

如何向微软 Docs 和本地化社区提交翻译贡献_第20张图片

右侧的下拉列表框选择源项目:

如何向微软 Docs 和本地化社区提交翻译贡献_第21张图片

可以看到源项目已经更新很多了,点击 Create pull request 按钮即可创建一个 PR。

如何向微软 Docs 和本地化社区提交翻译贡献_第22张图片

因为是自己的项目,所以可以直接将 PR 合并:

如何向微软 Docs 和本地化社区提交翻译贡献_第23张图片

合并后,自己的项目就更新到源项目的进度了。然后要把更新的内容 Pull 到本地。

在 VS Code 中按 F1,打开命令行窗口,输入 git pull

如何向微软 Docs 和本地化社区提交翻译贡献_第24张图片

或者点侧栏第三个按钮,右上角的三个点按钮,选择 Pull

如何向微软 Docs 和本地化社区提交翻译贡献_第25张图片

这样本地的项目也是最新的了。

现在大家应该对如何向 Docs 贡献翻译有一个大概了解了。我并没有全部使用 Git 命令,使用 VS Code 可以很方便的代替命令行做一些操作,还是比较方便的。

向应用程序提交贡献

这个就比较简单了,将这个网址加入收藏夹:

https://envelope-community.azurewebsites.net/

首先选择语言,然后可以点击右侧的按钮对当前已存在的翻译进行投票,或在下面的输入框中输入自己的翻译:

如何向微软 Docs 和本地化社区提交翻译贡献_第26张图片

这个页面支持手机浏览,所以没事等车的时候也可以刷几个翻译。

结语

Docs 是很好的学习资料,文章质量也都比较高。参与翻译 Docs 也是提高英语水平的一个方法。每天努力看一点,时间久了就会发现英语阅读能力会有很大提高,顺便为社区做点贡献,何乐而不为呢?希望能有更多同学加入到贡献者的队伍中来,帮助他人的同时也提高自己。

重要的几个链接,可点击直达上面所述的几个网站:

  • [微软Docs]
  • [Cloud + AI Localization Community]
  • [微软全新学习平台:Learning]

你可能感兴趣的:(如何向微软 Docs 和本地化社区提交翻译贡献)