如何向微软 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 来说，每项建议得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

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

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

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

要编辑的话，就点击那个笔形的编辑按钮：

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

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

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

创建 PR：

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

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

`Fork` 项目到自己的仓库

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

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

Fork源项目到自己的仓库
修改
向源项目提交 Pull Request

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

Fork 项目

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

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

使用 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 命令：

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

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

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

设置与源项目同步

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 命令：

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

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

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

如果使用命令行的方式，可以输入以下命令：

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，然后点击对号提交。

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

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

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

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

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

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

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

删除本地分支

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

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

与源项目进行同步

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

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

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

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

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

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

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

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

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

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

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

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

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

向应用程序提交贡献

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

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

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

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

结语

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

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