一起來協作 MDN 翻譯吧！

前言

這陣子還在佛系找新工作中，聽不少朋友分享與查看網路上求職心得：有不少公司喜歡對 mid-senior level 求職者穿插一些基本題目例如：

「什麼是 eventloop ?」

有鑑於前端技能樹實在太廣，(Senior 需要準備的)問題很多，可能面試期待公司問這幾年做了什麼或框架特色，結果對方還在考 JS 語言特性，然後再回馬槍考核心基本題，mid-senior level 若沒準備，回答卡還算是好的，有時怕的是沒準備到，接著等著被公司電到像寶可夢臭泥一樣癱軟掉。

強者我朋友真的不是我，聽了別人誠心(血淚)建議，趕緊查看以前鐵人賽文章複習一下，期間也上 MDN 看看怎麼解釋的，結果：

恩？「視覺化呈現」下方的圖片是掛掉了嗎？
MDN 作為一個前端工程師常查閱的網站，JavaScript 核心中的 eventloop 圖片是掛掉多久了？

想到了前陣子 FB 社群上討論，有人想合併 MDN 簡體中文與正體中文議題

Github issues 傳送門

好吧，自己的 zh-tw 自己修，十萬青年十萬肝，前端臭泥救台灣！

第一步：Fork 與 Clone

首先到 Github 上的 MDN 去 Fork 這兩份 repo 到自己帳戶：

• content
• translated-content

content 是我們實際上看到的 MDN 原版英文內容，translated-content 則是 content 版的多語系（翻譯）版，我們看的中文內容就是來自 translated-content。

而實際上修改 MDN 文件翻譯，我們也是修改 translated-content，至於 Fork content 原因有兩點：

1. 可以在本機修改 translated-content 時對照目前 content 版原文。
2. 某些內容 translated-content 沒有創建頁面資料夾、檔案甚至是文章段落只搬一半，這時需要協作者自己參考 content 原本內容並手動複製遷移。

是的，除了翻譯，遷移檔案或文章段落也是很重要的。

第二步：修改

Fork 好後就可以 git clone 至本機上了，我們接著在本機電腦用編輯器(如 VSCode)打開 translated-content 看看。

translated-content 目錄結構

• docs 資料夾內放的是修改說明文件，這裡我們不動它。
• files 資料夾內放的是 mdn 各語系頁面的檔案(也就是我們要修改的檔案)。

例如我現在要修改 eventloop 這頁，以網址為例：
https://developer.mozilla.org/zh-TW/docs/Web/JavaScript/EventLoop

從 developer.mozilla.org/zh-TW/docs/ 後面開始看，也就是 Web/JavaScript/EventLoop，檔案位置比照網址後方的 path 路徑，我要修改的檔案就位於 file 資料夾內 zh-tw 語系下 web 資料夾 javascript 裡 eventloop 的 index.html。

找到了！點開 eventloop 下 index.html 檔案查看

原來如此，有問題的是第20行圖片這邊，<img> element 的 src='/files/4617/default.svg'，這段相對路徑根本取不到圖片呀，我們要做的便是修正它。

除了這個問題，比對此頁正體中文與英文版網站其他內容，看看還有沒有哪邊怪怪的。

再比對英文原文版看看：

挖咧，Adding messages 這段中文沒有翻完，並且還有程式碼範例沒有遷移過來，那麼接下來就來修正這兩處，我們要怎麼取得「正確」的段落呢？這時就是 content 專案派上用場的時候了！

content 目錄結構

這裡另外再起一個 VSCode 打開 content，由於 content 就是 MDN 的原文(英文版)，所以目錄結構只有 en-us 不會有其他語系，裏頭一樣能順著網址的 path 資料夾階層找到對應檔案。

我們對照剛剛在 translated-content 的資料夾結構找到 web 資料夾 javascript 裡的 eventloop。

然而 eventloop 資料夾沒有 index.html 只有 index.md 和一張 the_javascript_runtime_environment_example.svg圖片。

注意 content 與 translated-content 檔案的不一致

有時可能會發生類似的狀況，即 content 的檔案不是 HTML 檔，但 translated-content 檔案卻是 HTML，這時要怎麼修改呢？

要記住基本原則就是不要動 content 的檔案，因為 content 是原文檔案，我們要修改的是 translated-content，故僅需對照 index.md 內 markdown 原文段落，複製 content 的段落並按照原意轉換成 HTML 貼回 translated-content 對應的檔案。也就是說：

1. 不在 content 內修改任何東西
2. 複製 content 內容或檔案到 translated-content
3. 在 translated-content 修改段落或檔案以符合原意

開始修改

既然是圖片掛了，那我們就檢查原本 content 的eventloop 資料夾the_javascript_runtime_environment_example.svg 這張圖，發現它就是正體中文缺少的原圖，那就簡單了，複製一份到 translated-content 的 eventloop 資料夾下，並把 index.html內<img> element 的 src 做對應修正即可。

個人經驗，<img> 圖片最好是複製到 translated-content 對應資料夾並用相對路徑讀取，不要用外連絕對路徑方式從 translated-content 讀 MDN content 原始圖片，不然 pull request 時 MDN 有時會檢查不過報錯進 Flaws

除了圖片外，還有 Adding messages 這段中文與範例程式碼的缺漏，我們對照 content 英文原版index.md，其是用 markdown 語法撰寫的：

對照 translated-content index.html，可以發現程式碼段落是用<pre class="brush: js">來處理，那麼簡單，從 content 對應段落複製貼上到 translated-content 內的 /Web/JavaScript/EventLoop/index.html 並修改成 HTML 格式：

第三步：commit & pull request

目前我們是在 Fork 來的 Project translated-content 上修改，接下來要把本機的修改推到自己 Github 帳戶上的 translated-content。

這裡建議開一個新 branch 分支自己比較好管理，branch 名稱我就取 event-loop，commit 我就以我流習慣寫上修改內容並推上去。

接著打開我們 Github 對應的 translated-content，切換到對應的 branch，剛剛已經把本機上修改的內容推上來了，現在我們可以點選 Contribute 來 Open pull request 打開一個 pull request。

這裡創建 pull request 時也可以加上一些對應的留言或註解，這裡我會比照 git commit 的註解再寫一次。

接著就點選 Create pull request 按鈕就可以囉！
看到出現 Review requested 已請求審核就代表這一階段結束了，可以稍微休息與等候。

等

就是等，MDN 基本上會把 pull request 派給 zh-tw 文件負責的大大審核，只需要等待(幾小時到幾天)即可。

第四步：再次修改

隔一段時間再回來看，會發現 github-actions bot 的提示：

哇..沒有錯誤？
開玩笑的，若沒有錯誤那運氣真的很好，實際上這個例子我修改了好幾次

github-actions bot 報的提示會類似下圖

• Preview URLs 是 MDN 產給你的暫時性網址
  裏頭會清楚標明 Flaws 給的錯誤提示，告訴你「第幾行程式有問題」
• Flaw count：4 表示目前有四個錯誤
  提示什麼 setTimeout 和 img style width 還有一個連結要 fallback 到 en-us 等等。

通常 github-actions bot 報的 Flaws，你會發現

啊和我這次修改有什麼關係？

沒有關係

反正 Preview URLs 裡會很清楚告訴第幾行錯誤，既然報錯了，就順手修正吧。

只需要到本機電腦對應的 translated-content 檔案修正，修完 commit 與 push 推到自己 Github 同 branch 的 translated-content。Github 會自動合併你的 translated-content 同 branch 提交到 MDN 的 pull request 內。

修改的過程並不會痛苦，有看不懂的 Flaws 也可以留言(通常都是既有連結 http 要改 https 這種等級的錯誤)，審核者也會一起檢查並給予修改說明，其實不用太在意這個過程，有錯誤就修正就好。

再等

基本流程就是：等 -> 修改 -> 等 -> 修改，持續到審核結束。

有時除了 github-actions bot，審核者也會給建議提示，例如：

某個段落預設為0，0的前後應該要用 <code> 包著，但這其實是正體中文版本來就少加的緣故，不過既然提出了這裡就一起修改，將其修改成 預設為<code>0</code> 即可。

如果有不清楚的 Flaws 錯誤，也可以在 pull request 處留言，審核者或社群大大們也會告訴你怎麼修改比較好。

第五步：完成

這樣來回修改後，Github Bot 與審核者審核沒問題，就會將修改合併回 main branch。

隔一陣子(幾天)再上 MDN 該頁面 就能看到自己的修改囉！

• 圖片——有
  

• 範例程式——有
  

這麼一來就結束啦，不僅修正了圖片錯誤、補上漏掉的段落，也算是對社群做了一點貢獻回饋。

總結

關於風格

關於修改翻譯的風格可以參考 translated-content 這篇說明，內文非常清楚地說明了翻譯 zh-tw 需要注意的事項，例如：

• 中英數之間不要留空白(不要「盤古之白」)
• id 用英文
• 註解留英文
• 簡中與正體中文技術數語差異等

另外我自己的心得是：

• 如果文章已經有預留「盤古之白」就不要去更動了，不然整篇文章你會改很久。
• 比照 content，可以的話圖片放 translated-content 專案內，不要連至外部。
• 連結皆須改 https，不然 bot 會報錯
• 若 MDN zh-tw 內部連結檔案不存在，改成 en-us(其實沒差但不改 bot 可能會報錯)

我們是翻譯還是搬運？

都是，雖然改的是 translated-content，但 content 做為參考的存在非常重要，有缺漏的段落你可以搬運並翻譯，有翻譯不妥的內容你也可以修正。只要有時間，大家也可以從前端臭泥變成搬運小匠呦。

參考

• 此次pull request issue
• 最早修改 MDN 的契機是保哥在 FB 的直播認識 MDN 中文文件翻譯的貢獻方式
  這支影片清楚明瞭的介紹如何修改，推薦給大家。