摘要：內容包括翻譯環境搭建項目管理與自動化構建三部分。博客首頁聲明官方文檔翻譯稿發布托管在七牛上的翻譯文檔倉庫環境搭建翻譯與寫作一樣，首要之事均為專注于翻譯寫作本身，而不考慮樣式等方面。安裝完成后，運行即可在啟動一個本地的。

感興趣的同學可以關注這個翻譯項目 、 我的博客原文 和 我的Github

前段時間翻譯的Spring MVC官方文檔完成了第一稿，相關的文章和倉庫可以點擊以下鏈接。這篇文章，主要是總結一下這個翻譯項目自開始到上線發布，完整的一個生命流程。內容包括 翻譯環境搭建 、項目管理 與 自動化構建 三部分。

博客首頁聲明：Spring MVC官方文檔翻譯稿發布

托管在七牛上的翻譯文檔

Github倉庫

翻譯與寫作一樣，首要之事均為專注于翻譯/寫作本身，而不考慮樣式等方面。而章節之間的聯系，自然也不想過多操心，這部分與樣式一起，都可交由工具去處理。然后版本管理，不用說一定要上，后面也會看到github的生態圈使得它與其他工具做到了無縫集成。那么總結起來，我們需要的工具大體是：

markdown

markdown編輯器 Atom

版本管理 Git

代碼托管平臺 Github

寫書專用工具 Gitbook

HTML轉markdown工具

Markdown是一種近乎完美的寫作標記語言，其最大的功勞便是將寫作從內容中分離出來，這個分離使你只專注于寫作內容本身，極大地提高了效率及工作愉悅度。沒有markdown的話，會是怎樣一種情況？想想HTML和寫論文經常使用的word。你在HTML中為內容混入各種各樣的樣式，寫論文時最痛苦的莫過于調樣式（不過筆者當年寫論文時通過Office Word的樣式窗也是完美地解決了內容和格式的問題）。

比如說，上面這段文字在markdown中寫出來是這樣的：

## 環境搭建

翻譯與寫作一樣，首要之事均為專注于翻譯/寫作本身，而不考慮樣式等方面。而章節之間的聯系，自然也不想過多操心，這部分與樣式一起，都可交由工具去處理。然后版本管理，不用說一定要上，后面也會看到github的生態圈使得它與其他工具做到了無縫集成。那么總結起來，我們需要的工具大體是：

* markdown
* markdown編輯器 Atom
* 版本管理 Git
* 代碼托管平臺 Github
* 寫書專用工具 Gitbook
* HTML轉markdown工具

說起來markdown這個名字也有點意思，一般的標記語言叫markup language。這里將up改成down，寓意著將標記語言中與內容本身無關的標記全部剔除，形成一個精簡子集。本篇不是markdown用法記，所以更多的語法請自行百度Google。我這里可以提供幾個鏈接：

Wikipedia: Markdown

Markdown overview

Github上最有名的Markdown Cheat Sheet倉庫

編輯器的選擇并無定式，打造一個完全符合自己操作習慣的編輯器也是每個程序員應做的一個工作，這里我不贅述。在Mac上，不錯的markdown編輯器有Sublime 3、Atom、MacDown、Mark Editor、Gitbook Editor、Mou等，可挑選適合自己的，我選擇的是Atom，是因為有一個剛性的需求它能夠滿足：

與終端（terminal）的集成。由于使用了版本管理，同時有時有拷貝文件、查看目錄等需求，命令行肯定是必須隨時在手的。終端方面我的選擇是iTerm2+zsh，關于它們的配置和特性，可以查看博客的這兩篇文章 Mac優雅的工具集——iTerm2篇 和 Mac優雅的工具集——oh-my-zsh篇。對如何在Mac上構建一個優雅的工具集有興趣的同學，也可以前往Gitbook看看我正在寫的這個系列：關于優雅地使用Mac OS的理念、想法、工具與實踐集，不過還沒寫完就是了。

Git作為版本管理的意義也不贅言。你肯定不想自己的工作區最后變成這樣：

同樣本小節也不是Git入門的命令集，這部分請自行查閱學習。當然我還是可以給出一些鏈接，雖然沒有太多的意義我真的不知道為什么我還要給。基本的幾個命令能熟悉就可以滿足日常的需要了。另外，zsh下的Git可以配一下 快捷鍵(alias) 和 自動補全，具體配置非常簡單，可以來這篇文章Mac優雅的工具集——oh-my-zsh篇看一下最終的效果。

Git - 簡易指南

A Visual Git Reference

廖雪峰的官方網站：史上最淺顯易懂的Git教程這浮夸的標題收視率果然好

Github是世界上最大的同性交友平臺目前最大我并無依據的代碼托管平臺，其生態圈之繁榮與力量令人震驚，幾乎你需要的所有工具和資源都可以在上面找到。它與Git不是一個層級的概念git=github.substring(0, 3)，這部分請自行搜索。在這個平臺上，我可以給翻譯項目一個README.md文件，為閱讀的人做簡單的介紹以及引流，同時它可與CI（持續集成）、Gitbook等工具完美集成，其內置的issue、pull-request功能還能與Zenhub結合，直接當成trello來進行項目管理之用。相關的工具下一節會介紹。

上文提到了翻譯內容與樣式的分離。實際上在這里樣式這部分就是由Gitbook自帶的渲染引擎來負責的。此外，Gitbook還能幫助你管理整個書的目錄結構、章節生成、搜索、詞匯表、站點構建與生成等，同時它也有豐富的插件生態。這一切只需要你進行少量的配置（其實，就只是在書的根目錄下運行gitbook init命令，它會生成下圖所示的一個目錄結構），其低學習成本與高效益，使它成為了寫書最易入門的趁手工具。

.
├── README.md
└── SUMMARY.md

項目管理方面的需求，主要是有時會有想法出現，希望增加什么特性，或者想到什么問題不想馬上修，那么最好是有一個TODOLIST可以隨時記錄下來，并且能被方便地檢索到。這方面的需求，怎么解決呢？

Github內置的issue功能已經好用到爆，再加上專為Github issue功能定制的Zenhub簡直就是活生生把issue當成trello來用。一些內置特性如下，稍加體驗即可滿足所有小型項目管理上的需求：

issue可以通過commit sha直接與相關的單次提交關聯，還可以 通過提交信息來引用、關閉issue

issue中支持GFM(Github Flavored Markdown)，可以直接使用todolist的語法

通過Command/Ctrl+V可以直接在留言中上傳截圖

可以為issue添加標簽（tag）、類別（pipeline, 如正在做、還沒做、已完成等）

可以為issue估點、指定負責人、燃盡圖，簡直就是為敏捷實踐而生，不過在這個翻譯項目中用不到這些，畢竟自己給自己估點沒什么意思

自動化什么的構建？這還要從本翻譯稿的托管平臺——Gitbook——說起。gitbook是一個絕好的寫作平臺，官方也通過Webhooks提供了與Github的集成，只要你把代碼git push到遠端倉庫，Gitbook就會自動拉取倉庫中的內容，依照特定的格式為書本構建站點。過大概2到3分鐘，你就可以在Gitbook上看到自己最新的更新已經到書上了。一切看起來都十分美好，一鍵提交與部署。但是有一個最大的問題：Gitbook在國內的速度不行，輕則卡頓，重則整站被墻刷不出頁面。

這種情況下，我決定將整個翻譯同時遷移到七牛上。七牛的CDN在國內速度名聲在外，用來托管靜態站點再好不過只需要拍兩張身份證正反雙面的照片上傳等待審核即可。遷移也很簡單，因為gitbook生成的靜態站點其實就是_book文件夾，只需要把這個文件夾下的全部東西放到七牛空間上去，在使用index.html作為入口就可以了。但是，問題又來了：

七牛網站上無法上傳文件夾。就算可以，我也無法忍受每次都要手動將文件夾拖上去

每次倉庫有更新，都需要將最新的內容同步到七牛空間上，并覆蓋舊版本的同名文件

第二步的操作還不能通過githook+shell的方式來做，因為整個過程的耗時會使git push的反饋周期變長，從而使得我更不傾向于頻繁提交，影響翻譯體驗

解決方案也很簡單：

第一條，尋找七牛的SDK，通過命令行進行上傳

第二條，既然不能，[細想]也沒必要在本地做，那么就在遠端做好了。遠端在哪里呢？CI/Pipeline啊，這樣構建站點、同步文件等工作都可以并行進行了，既不會阻礙本地開發速度，也不是翻譯時需要考慮的問題，我還是只需要像以前一樣git push提交代碼即可，站點從構建到最終上線，都有CI在負責

想法出來了，在實施的時候還是走了一些彎路的。這些折騰過程在此無法深表，只有可能帶過程序員們都懂的。在CI的選擇上，我選擇了Jenkins 2.0，原因比較純粹，最近項目上在使用Jenkins 2.0，我剛好當是練手。至此文章成筆之時，我仍在考察其他選擇，比如travis-ci，看起來UI和配置都簡單許多，這部分可能是后文了。下面會簡單介紹折騰搭建Jenkins 2.0作為本翻譯項目CI的步驟和關鍵節點。

話說Jenkins不愧為CI/CD領域的先鋒，這個產品每周都會發一個小版本（目前最新是2.11）。Jenkins 2.0的安裝，可以通過直接下載安裝包的方式下載，在Mac上也可以通過brew install jenkins來下載安裝。安裝完成后，運行jenkins即可在localhost:8080啟動一個本地的jenkins。

流程十分簡單，免費用戶可以有一個空間，有一定的流量限制，不過通常來說對于只有一個空間需求的用戶來說，這樣的流量應該不會超吧。由于我已經超過了一個空間的需求，同時我又有配置獨立域名的需求，所以需要更多的權限。流程也很簡單，進行實名認證、填寫身份證、上傳本人及身份證正反面照片各一張本人不需拍反面，最后保證賬戶里有最少10元即可。

pipeline搭建起來了，接下來我們需要捋一捋前面說到的兩個步驟：構建站點、上傳站點文件到七牛空間。細分下來，主要是有以下的task要做：

引入必要的依賴

構建站點

同步到七牛

我們想要構建站點，必然使用gitbook的命令行工具；要使用七牛的命令行，也必然引入相應的工具。這里我走過一些彎路，比如嘗試將七牛工具以插件形式引入到Jenkins job中來，但是2.0以后，我們更傾向于使用腳本來描述構建工作，而非將Jenkins單純當作一個轉存/轉儲的工作區間并為該workspace零散地寫一些適配腳本。因此，在pipeline類型的項目就不存在每個job特定的配置空間，若想使用插件，配置起來有些麻煩。于是，最后我決定使用七牛的npm包（肯定是有的），并通過NPM來管理所有依賴。以下是一個package.json文件需引入的依賴：

{
   ...
   "devDependencies": {
        "gitbook": "^3.1.1",
        "gitbook-cli": "^2.3.0",
        "qiniu": "^6.1.11"
    },
    ...
}

另外，需要注意的是，Gitbook的渲染引擎已經升級到v3.1.1版本，與Legacy v2.6.7版引擎相比，主要的區別是v3支持多個部分(part)的文章、默認關閉了目錄中章節前的數字等。其中multipart的部分有些小bug但還可以忍受，但是默認關閉的目錄數字則需要通過以下的配置給設置回來。在book.json文件中：

{
   "gitbook": ">=3.1.0",
   "pluginsConfig": {
      "theme-default": {
         "showLevel": true
      }
   }
}

簡單地運行命令gitbook build即可生成站點目錄。最后的構建腳本Jenkinsfile.groovy如下所示：

node ("main") {
    stage "Pull latest changes from SCM"
    git([
        url: "git@github.com:linesh-simplicity/translation-spring-mvc-4-documentation.git",
        branch: "master"
    ])

    stage "Download dependencies: Gitbook/Gitbook-cli/Qiniu"
    sh "npm install"

    stage "Build book serving directory through Gitbook"
    sh "gitbook build --gitbook=3.1.1"

    stage "Upload production _book to Qiniu through their API"
    sh "./jenkins/sync-book-to-qiniu.sh"
}

使用七牛的命令行工具進行文件上傳，需要配置一些東西，主要是要同步的本地目錄、七牛的Access key和Secret Key等，示例代碼則可以從七牛SDK的官網上參考。我最后完成的這份同步腳本sync-book-to-qiniu.js如下所示，其中完成了 準備本地同步目錄 、 排除不同步文件 、 指定覆蓋上傳策略等工作：

const qiniu  = require("qiniu");
const glob   = require("glob");
const crypto = require("crypto-js")

const ignoredFiles = [
    "Jenkinsfile.groovy",
    "sync-book-to-qiniu.js",
    "sync-book-to-qiniu.sh",
    "mvc-origin.md",
    "package.json"
];

// node ./jenkins/sync-book-to-qiniu.js $ACCESS_KEY $SECRET_KEY
let qiniuAccessKey = process.argv.slice(2, 3);
let qiniuSecretKey = process.argv.slice(3);

// Prepare Qiniu configuration options
qiniu.conf.ACCESS_KEY = qiniuAccessKey.toString(crypto.enc.Utf8);
qiniu.conf.SECRET_KEY = qiniuSecretKey.toString(crypto.enc.Utf8);
bucket = "mvc-linesh-tw";

glob.sync("_book/**/*.*", {}).filter(filename => {
    for (let ignored of ignoredFiles) {
        if (filename.endsWith(ignored)) return false;
    }
    return true;
}).forEach(filepath => {
    const resource_key_in_qiniu_api = filepath.substring("_book/".length, filepath.length);
    // ":" means allow override upload. For further details refer to offical API docs
    const policyToken = new qiniu.rs.PutPolicy(bucket + ":" + resource_key_in_qiniu_api).token();
    uploadFile(policyToken, resource_key_in_qiniu_api, filepath)
})

function uploadFile(uptoken, key, localFile) {
    let extra = new qiniu.io.PutExtra();
    qiniu.io.putFile(uptoken, key, localFile, extra, function(error, response) {
        if(!error) {
            console.log("[Success] File uploaded: " + response.key);
        } else {
            console.log(error);
        }
    });
}

同行們求review代碼啊～

AK(Access Key)和SK(Secret Key)是七牛分配給注冊開發者的一對密鑰，不能泄露，否則其他人得到了就可以對你的七牛空間進行任意操作。但是，你要把構建工作自動化，就必須這段腳本提交到github上，同時CI還要能從你的代碼中讀出正確的AK和SK，這要如何做到呢？回答是，通過CI提供的接口，由pipeline將參數注入到你的代碼中。這樣，AK和SK就被保存在了pipeline上，別人無權對其進行訪問。在Jenkins CI上，這是通過一個EnvInject插件來做到的，在travis-ci中則更加簡單，直接設置。

呼呼，最后看到這個圖的時候還是很激動的，所有的部署工作都成功了。那么也是時候結束了，本篇文章總結起來，先是提到如何準備和搭建讓翻譯工作更加專注和高效的環境和工具，如markdown/atom/gitbook/git/github等，然后講到如何使用github的issue和zenhub來輔助管理翻譯項目中的待辦事項和協作，最后一節講述了如何使用CI工具將整個站點的構建和發布自動化，提高翻譯和部署效率。任何有疑問或說錯的地方，也請各位給我指出。

—— 2016-07-01