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)。

直接在頁面上修改

第一種方式是直接在頁面上修改，適合修改單個詞語、句子或文章。以該頁面為例：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 也是提高英語水平的一個方法。每天努力看一點，時間久了就會發現英語閱讀能力會有很大提高，順便為社區做點貢獻，何樂而不為呢？希望能有更多同學加入到貢獻者的隊伍中來，幫助他人的同時也提高自己。

如何向微軟 Docs 和本地化社區提交翻譯貢獻