如何向微軟 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 也是提升英語水平的一個方法。天天努力看一點，時間久了就會發現英語閱讀能力會有很大提升，順便爲社區作點貢獻，何樂而不爲呢？但願能有更多同窗加入到貢獻者的隊伍中來，幫助他人的同時也提升本身。

重要的幾個連接，可點擊直達上面所述的幾個網站：

• [微軟Docs]
• [Cloud + AI Localization Community]
• [微軟全新學習平臺：Learning]