一起來協作 MDN 翻譯吧!


Posted by SimonAllen on 2021-08-31

前言

這陣子還在佛系找新工作中,聽不少朋友分享與查看網路上求職心得:有不少公司喜歡對 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 是我們實際上看到的 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 資料夾 javascripteventloopindex.html

找到了!點開 eventloopindex.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 做為參考的存在非常重要,有缺漏的段落你可以搬運並翻譯,有翻譯不妥的內容你也可以修正。只要有時間,大家也可以從前端臭泥變成搬運小匠呦。

參考


#MDN









Related Posts

24. Visitor

24. Visitor

JavaScript 核心 - 物件導向與原型鍊

JavaScript 核心 - 物件導向與原型鍊

[進階 js 08] Closure

[進階 js 08] Closure


Comments