前言
去年，我在實(shí)習(xí)過程中加入了國(guó)內(nèi)大型前端文檔翻譯組織—印記中文。參與了 ionic 和 vuepress 的翻譯。
我深深感受到，翻譯過程中，最吸引人的，令我收獲最大的，不是說那些零零碎碎的 API，而是開源精神對(duì)我的鼓舞。
開源社區(qū)，是程序員這個(gè)人群最寶貴的財(cái)富。
我從翻譯文檔中學(xué)到了什么？這是我的答案：
- 翻譯流程與 git 操作
- 翻譯與開源理解
- 翻譯素養(yǎng)
翻譯流程與 git 操作
印記中文的翻譯流程幾經(jīng)更迭，到如今已經(jīng)形成了一個(gè)比較可靠、高效的流程。以 ionic 翻譯流程為例：
我們將翻譯涉及到的倉(cāng)庫(kù)分為三級(jí)：
項(xiàng)目原倉(cāng)庫(kù)（一級(jí)）、印記中文倉(cāng)庫(kù)（二級(jí)）、譯者倉(cāng)庫(kù)（三級(jí)）。
三者職責(zé)分明，一級(jí)倉(cāng)庫(kù)負(fù)責(zé)原始信息的生產(chǎn)，二級(jí)倉(cāng)庫(kù)用來管理，不提供翻譯，只負(fù)責(zé)同步上游信息和審閱下游翻譯。真正的貢獻(xiàn)者，在第三級(jí)倉(cāng)庫(kù)。
從圖中可以看出，我們使用了大量 git 和 github 操作：
- fork(github) 復(fù)制倉(cāng)庫(kù)
- clone(git) 從 github 簽入代碼到本地倉(cāng)庫(kù)
- remote add(git) 關(guān)聯(lián)上游倉(cāng)庫(kù)
- remote update(git) 同步上游倉(cāng)庫(kù)
- add/commit(git) 將工作區(qū)更改保存到本地倉(cāng)庫(kù)
- push(git) 將本地倉(cāng)庫(kù)代碼推送到遠(yuǎn)程倉(cāng)庫(kù)中
- pull request(github) 將下游倉(cāng)庫(kù)的更改同步到上游倉(cāng)庫(kù)
除了圖中明顯的操作，還有一些實(shí)際中也常用到的操作：
- branch(git) 列出或新增、刪除分支
- checkout(git) 切換分支
一般開源項(xiàng)目都有若干個(gè)分支，每個(gè)分支都可以說是幾乎對(duì)應(yīng)著一個(gè)版本。在印記的翻譯流程中，中文文檔統(tǒng)一在 cn 分支下。
- fetch(git) 將遠(yuǎn)程倉(cāng)庫(kù)內(nèi)容拉取到本地倉(cāng)庫(kù)
- merge(git) 將本地倉(cāng)庫(kù)內(nèi)容合并到工作區(qū)
為什么要提這兩個(gè)命令呢？因?yàn)閷?shí)際上 pull = fetch + merge，而 pull 是不具備拉取所有分支的功能的，所以我們需要把這個(gè)步驟拆開：先把遠(yuǎn)程倉(cāng)庫(kù)所有分支內(nèi)容同步到本地倉(cāng)庫(kù)，再選擇某一個(gè)分支和當(dāng)前工作區(qū)內(nèi)容合并。
當(dāng)然，還有一些不常用的操作和騷操作，這塊內(nèi)容會(huì)在本文靠后的成長(zhǎng)與挫折部分介紹。
對(duì)于基本的 git 概念和操作還有疑惑的讀者可以參考下面資源：
理解開源
在這里，我真正學(xué)會(huì)了真正的閱讀源碼的技巧。
以前，我以為讀源碼和上學(xué)時(shí)讀教科書一樣，順著章節(jié)從頭讀到尾就能達(dá)到目標(biāo)，通過考試。
但開源項(xiàng)目不同，它沒有考試，也不會(huì)終結(jié)，只要世上還有人在運(yùn)行著它的代碼。
要理解一個(gè)開源項(xiàng)目，必須要沿著它的 git log 一路尋找才能真正感受到它的真正魅力。最初的起點(diǎn)，可以是項(xiàng)目剛剛好正常運(yùn)行的那個(gè)節(jié)點(diǎn)，也可以是被打上第一個(gè) v1.0.0 tag 的節(jié)點(diǎn)。
開源項(xiàng)目是動(dòng)態(tài)的。
如果像過 PPT 一樣過源碼簡(jiǎn)直就是對(duì)它價(jià)值的浪費(fèi)！我們應(yīng)該將這個(gè)項(xiàng)目先運(yùn)行起來，這是對(duì)它的基本尊重。然后打斷點(diǎn)，跟調(diào)試。
開源項(xiàng)目是有生命的。
就拿 Vuepress 來說，我們從它發(fā)布的 v0.1.0 跟到這篇文章發(fā)布時(shí)的 v0.8.4，期間可以看到作者對(duì)這個(gè)產(chǎn)品的奇思妙想，也能看到來源于大眾的各個(gè) issue 和 pr，沿著時(shí)間一點(diǎn)一滴地澆筑這個(gè)項(xiàng)目。
比如說這個(gè)關(guān)于下拉導(dǎo)航鏈接的討論：從基本的功能需求到詳細(xì)的數(shù)據(jù)結(jié)構(gòu)，再到之后對(duì)基于此功能開發(fā)多語(yǔ)言特性的展望。
開源項(xiàng)目是集體財(cái)產(chǎn)。
開源是一個(gè)自下而上的體系，如果從譯者的角度來看。但這同時(shí)也是一個(gè)自上而下的體系，如果從項(xiàng)目本身來看。一個(gè)優(yōu)秀的開源項(xiàng)目，會(huì)源源不斷地產(chǎn)生新的靈感和想法，下游的譯者們孜孜不倦地受著來自上游的給養(yǎng)，從而又轉(zhuǎn)化成更適合當(dāng)?shù)匚障恼Z(yǔ)言版本反哺給上游。
把譯者替換成萬千默默無聞給開源項(xiàng)目貢獻(xiàn)代碼的普通工程師也是一個(gè)道理。正是因?yàn)橛辛诉@些人，前端乃至IT界的技術(shù)生態(tài)才會(huì)如此繁榮。
它是分權(quán)、公開、同僚復(fù)審的。
我們都是其中的一員，沒有人是一座孤島。
翻譯素養(yǎng)
“翻譯技術(shù)文檔不是隨便翻譯就完了，你需要重新審視它，讓它容易被讀者理解，但又不能出現(xiàn)原意的偏差?！?/p>
在我第一次提交翻譯 ionic 文檔的 pr 時(shí)，印記的前輩這樣教導(dǎo)我。
“排版和格式也需要注意，記住我們是專業(yè)的?！?/p>
說完他給了我一個(gè)鏈接：中文文案排版指北。它詳細(xì)地規(guī)定了哪些元素需要用空格隔開，遇到完整的英文整句、特殊名詞該怎么辦等不容易引起注意卻很重要的細(xì)節(jié)？
翻譯文檔和翻譯文章不同，它應(yīng)以通順重視原文為準(zhǔn)。
我的英文水平自認(rèn)為不是非常好，雖然過了所謂的六級(jí)，但閱讀英文資料時(shí)常常還是需要借助翻譯工具來輔助閱讀。這就更加提醒我了，翻譯是個(gè)耐心活，看似沒有多少技術(shù)含量，實(shí)則非常能反映譯者的水平。我的水平，顯然還是不太夠的，還是需要多向各位前輩們學(xué)習(xí)的。
成長(zhǎng)與挫折
-
三級(jí)倉(cāng)庫(kù)同步流程
原始項(xiàng)目往往更新地非常迅速，我們需要跟上更新還是挺費(fèi)力氣的。不過李同學(xué)提出了一個(gè)方法：二級(jí)倉(cāng)庫(kù)只拓展，不修改。拓展來源可以是一級(jí)的更新，也可以是三級(jí)的翻譯。
然后在三級(jí)倉(cāng)庫(kù)同步二級(jí)倉(cāng)庫(kù)，遵循行數(shù)不變的原則，利用 git diff + 可視化編輯工具完成同步。具體步驟為：-
1.1 fetch(從一級(jí)遠(yuǎn)程倉(cāng)庫(kù)到二級(jí)本地倉(cāng)庫(kù))
fetch vuepress
可以看到圖中有三個(gè)箭頭，最上面的箭頭指向最新版本，中間箭頭指向我們需要拓展到的 0.9.0 版本，第三個(gè)箭頭指向 fetch 成功提示。
-
1.2 push master（從二級(jí)本地倉(cāng)庫(kù)到二級(jí)遠(yuǎn)程倉(cāng)庫(kù)）
push master
經(jīng)過這一步操作，我們就可以將一級(jí)遠(yuǎn)程倉(cāng)庫(kù)的更新拓展到二級(jí)遠(yuǎn)程倉(cāng)庫(kù)。
注意：push 的分支是 master 不是 cn。
- 1.3 fetch + merge 發(fā)現(xiàn)沖突(從二級(jí)遠(yuǎn)程倉(cāng)庫(kù)到三級(jí)本地倉(cāng)庫(kù))
這個(gè)時(shí)候我們工作區(qū)已經(jīng)切換成翻譯者擁有的，而不是管理者擁有的。
注意：由于我既是管理者也是翻譯者所以才需要切換。
翻譯工作區(qū)的 fetch + merge：
fetch
merge
沖突-
1.4 diff 解決沖突（翻譯的過程）
diff
webstrom 為我們提供了三塊編輯區(qū)：你的版本、合并版本、服務(wù)端版本。紅色的自然就是沖突部分了，我們可以選擇全部要我們的版本，也可以全部要服務(wù)端的版本，當(dāng)然，一般是部分來自于我們的版本部分來自于服務(wù)端的版本。
行數(shù)對(duì)應(yīng) -
1.5 push cn（從三級(jí)本地倉(cāng)庫(kù)到三級(jí)遠(yuǎn)程倉(cāng)庫(kù)）
push cn
翻譯者此時(shí)提交自己的翻譯成果。
-
1.6 pull request（從三級(jí)遠(yuǎn)程倉(cāng)庫(kù)到二級(jí)遠(yuǎn)程倉(cāng)庫(kù)）
新建 pr
創(chuàng)建 pr
管理員視角下的 pr
到這時(shí)，如果管理員覺得 pr ok 的話，就會(huì)接受，否則會(huì)不接收然后注明不接收的原因。有時(shí)管理員還要處理產(chǎn)生沖突的 pr。
-
webstrom 還有很多操作 git 的功能：Smart merge、Stash Change、Rebase 等，更多用法可以參考在 WebStorm 中熟練地使用 git
- 翻譯錯(cuò)誤或有瑕疵
限于本人水平有限，翻譯成果自然有不如人意的地方，比如 vuepress 的 yaml front matter，我不知道這是一個(gè)庫(kù)，就直譯成“yaml 前端” ，鬧了笑話，幸好之后有人指出來錯(cuò)誤。我們印記中文是樂于接受批評(píng)和指正的，因?yàn)槲覀円彩情_源社區(qū)的一份子。 - 遭遇無恥抄襲
抄總比自己做簡(jiǎn)單的多。再加上我們又是開源，自然有不少站點(diǎn)如 xx碼頭等直接搬運(yùn)過去用的，不打招呼就算了，還在網(wǎng)頁(yè)上加一句：經(jīng)自己整理翻譯。這就令人很痛心了。
結(jié)語(yǔ)
這，就是我從翻譯文檔中收獲到的。
