如何向微軟 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
)。
直接在頁面上修改
第一種方式是直接在頁面上修改,適合修改單個詞語、句子或文章。以該頁面為例: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 和本地化社區提交翻譯貢獻