iT邦幫忙

6

六個語言的 README,要一比一翻完整,還是只寫到「裝得起來」就好?

  • 分享至 

  • xImage

第一次在這裡發文。先說一下我的身分,免得被當成來打廣告的:我是 LibreDB Studio 的維護者之一,MIT 授權的開源工具。今天要問的事跟工具本身沒什麼關係,是我們內部吵很久、到現在還沒定案的一件事:多語系的 README 到底要做到什麼程度。

我們的 README 有六份。英文那份最完整,一千多行;其他五份(簡體中文、日文、西班牙文、烏爾都語、印地語)都是精簡版,三百行上下,只寫「這東西是幹嘛的」跟「怎麼裝起來」,再深入的就直接連回英文版。

先自首一件事:沒有繁體中文版。這也是我想順便問的。

前陣子有個第一次發 PR 的人,把簡中那份整個重寫,從 315 行補到 1014 行,照著英文版一節一節翻下來。老實說翻得不錯,我也不太想退。但收下去之後,簡中就跟其他四種語言不同調了,接下來要不要比照辦理,我們就卡住了。

兩邊的理由我們自己都講得出來。

全翻的好處很明顯,讀者不管用哪個語言,看到的東西都一樣。問題是英文那邊改一次,一千多行要誰去跟上?我們沒有專門做在地化的人,真的跟不上的話,最後就是一份看起來很齊、其實停在半年前的文件,那還不如一開始就請人直接看英文。

維持精簡的好處是不容易過時,壞處是讀者一路看下去,看到一半被丟去英文版,體驗其實滿差的。

所以想問一下平常也會看中文 README 的人:

你點開一個專案的中文 README,比較希望它內容齊全,還是寧可它短一點、但至少是對的?如果你發現它比英文版舊了半年,你會自己翻回英文看,還是心裡就先對這個專案打個折?

還有繁中這塊:你們會希望有獨立一份,還是簡轉繁就夠用了?

我們在 issue 那邊也在討論這題,想看實際情況的話在這裡:
https://github.com/libredb/libredb-studio/issues/1055

看更多先前的討論...收起先前的討論...
假如寫得真的是純英文,正規的,你用任何的翻譯引擎,翻譯成其他語言就會怪怪的
真的專業英文用的文字,只有專業的翻譯者才會能正確翻譯成其他語言
如果你用的是付費引擎,也許能夠翻得比較正確,
但很多的專業專用字詞還是需要專業的翻譯者才能夠翻譯正確,
當然如果樓主用的是特定專業翻譯引擎,
那種費用負擔的起,那麼就不需要請專業翻譯了,
直接用專業翻譯引擎來同步翻譯就行了
所以真的問題還是在於樓主的公司打算在翻譯這一塊做多少預算
libredb iT邦新手 5 級 ‧ 2026-09-23 06:32:44 檢舉
@窮嘶發發發 預算這點說得很實在:我們沒有專職做在地化的人,所以才選擇讓翻譯少一點、但錯了會被擋下來。
libredb iT邦新手 5 級 ‧ 2026-09-23 06:34:50 檢舉
謝謝各位的回覆,這裡整理一下我們最後怎麼做,也順便回應幾個建議。


結論是:英文 README 是唯一的準。簡中那份完整翻譯收下了(#1052),其他四個語言維持精簡版。每份翻譯最上方都加了一行提示,說明譯文可能落後 英文版,兩邊不一致時以英文版為準(#1064)。另外 CI 會檢查每份翻譯裡的資料庫清單、安裝指令(必須跟英文版逐字相同)和一段登入設定的警告,這幾塊是讀者照著做最容易出事的地方,寫錯就過不了 PR。其他內容(功能介紹、數字、日期)沒有被檢查到,所以才需要那行提示。
個人建議的做法,將整篇分段,把會更新跟幾乎不會變化的分開來
例如每次的版更就可以分段,每分一段,如果需要翻譯,就依序把不同語言加進來
透過本地化標籤,不同的語系國家載入本地語言的說明,假如沒有本地語言,就顯示原文
這樣就算沒有翻譯,你的說明在不同語系也會顯示最完整的說明
這樣就沒有所謂的簡易版本的問題,至於翻譯,有時間一段一段敲
libredb iT邦新手 5 級 ‧ 2026-09-24 02:16:06 檢舉
@窮嘶發發發 這個思路我們認真想過,也想說明一下為什麼最後沒走這條路:問題不在想法,在 GitHub。

你說的「按段落做本地化、沒有譯文就回退原文」,本質上就是 docs 站的 i18n 做法。我們官網(libredb.org)走的就是這套。但 **README 是 GitHub 直接渲染的單一檔案**,GitHub 不會依讀者語系去挑內容,也沒有段落級 fallback 的機制:它只會找 README.md,剩下的靠人工放連結。

不過你這個想法有一個「可以做」的版本,我們把它記下來了:**把 README 拆成帶 key 的段落來源,用一個產生步驟去組出每一份 README.zh-CN.md / ja.md 等等,沒翻的段落直接填英文原文。** 這樣確實就沒有「精簡版」這個概念了,每份都是完整的,只是部分段落是英文。

代價是 README 變成產生物,不能直接手改,外部貢獻者發 PR 時會踩到:這是我們現在還在猶豫的點。上次那個把簡中從 315 行補到 1014 行的 PR,就是一個第一次貢獻的人直接改檔案,如果檔案是產生的,那個 PR 會直接失效。

所以目前的折衷是:英文為準 + CI 只檢查「照著做會出事」的那幾塊(資料庫清單、安裝指令、登入設定警告),其餘靠檔頭那行提示。你的做法更完整,我們留著當下一步。
libredb iT邦新手 5 級 ‧ 2026-09-24 02:31:44 檢舉
@helenanova 這個補充很實用,`git rev-list --count` 那個數字我們沒想到可以直接拿來當門檻用。

我們現在的檔頭提示是靜態的一句話(「譯文可能落後英文版,不一致時以英文版為準」),讀者看不出來到底落後多少,可能是三天,也可能是半年,對他們來說沒差別,就只能整份打折。你說的做法等於把「落後」從一句免責聲明變成一個可以看見的數字,這差很多。

門檻那段特別有道理。我們之前沒做自動開 issue,一部分原因就是怕吵:英文 README 改個錯字也要開一張,很快就沒人理了。用累積次數當門檻可以避開這件事。

有一個我們還要想的點:README.md 的修改次數不完全等於「需要重譯的次數」。像我們 CI 現在盯的那幾塊(資料庫清單、安裝指令、登入設定警告),改到就一定要跟;但功能介紹那種段落改了,其實可以晚一點。所以可能要分兩個計數,或者乾脆只算「受檢查區塊」的變動次數。

總之這條我們會做,謝謝。
martin20 iT邦新手 5 級 ‧ 2026-09-30 21:48:17 檢舉
<p>我覺得可以先不用做兩套計數,而是把「提醒讀者」和「通知維護者」分開:檔頭顯示英文版累積更新了幾次,但註明不代表每次都需要重譯;開 issue 則只看你們列出的關鍵區塊。安裝指令或登入警告有變動就立即提醒,其他內容累積到門檻再處理。同一份譯文如果已經有未關閉的 issue,就更新原本那張,應該也能減少通知干擾。</p>
圖片
  熱門推薦
圖片
{{ item.channelVendor }} | {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中
1
cevheri
iT邦新手 5 級 ‧ 2026-09-21 21:38:42

请查看这个翻译相关的 PR。 https://github.com/libredb/libredb-studio/pull/1052

4
DanSnow
iT邦好手 1 級 ‧ 2026-09-21 22:27:02

我單純說自己的偏好,沒有說一定正確:其實我不喜歡多語言 readme

我覺得 readme 應該以英文,或是主要使用者會用的語言為主 (比如你預期你的專案是中文圈的人會用,那就用中文) ,理由其實就是寫 code 的人不一定會翻譯,如果要維護多份其實沒有能力審查 ,叫 AI 翻也行啦,只是你也只能相信 AI 翻的正確了

我覺得 readme 應該是給來看 code 的人看的,不是給來使用的人看的,你完全可以在 readme 上加上多語言的連結,把這些使用者全部導到網頁版的文件去,然後做多語言版的文件,你可能會想這有什麼不同,但我覺得不一樣,網頁簡單的你可以另外開一個 repo 放網頁版的文件,然後讓使用者來貢獻翻譯,或是用像 Crowdin 那樣的社群翻譯的工具,用工具翻譯有好處,你的原文改了 Crowdin 上就會被標記成過時的內容,必要時可以逐頁 fallback 回英文版

libredb iT邦新手 5 級 ‧ 2026-09-23 06:31:43 檢舉

@DanSnow 把 README 定位成給看 code 的人、使用者導去文件網站,這個方向很有道理。我們現在的文件都還在 repo 裡,短期內先用上面的方式撐住,Crowdin 那種「原文改了就標記過時」的機制,是以後搬出去時的參考。

2
mathewkl
iT邦高手 1 級 ‧ 2026-09-22 09:26:20

我個人只會看完整版確保不會漏東西

簡轉繁有繁化姬可以連帶將常用用語轉成台灣的用法

libredb iT邦新手 5 級 ‧ 2026-09-23 06:31:58 檢舉

@mathewkl 謝謝推薦繁化姬。繁中的部分,目前還沒有決定,如果有台灣的朋友願意長期幫忙看,再考慮獨立維護。

3
helenanova
iT邦新手 5 級 ‧ 2026-09-22 19:10:26

我會把「齊全但過時」排在「精簡但正確」後面。文件錯比文件少更傷:讀者不知道哪一段已經不準,整份的可信度就垮了。所以英文當 single source of truth、其他語言維持精簡並明確導回英文,是合理的預設。

如果想收下那份完整簡中翻譯,又不想養出六份全職翻譯,可以用低成本的方式盯住新鮮度:每份翻譯在檔頭記下它翻譯時對應的英文版 commit hash,CI 比對英文 README 在該 hash 之後是否有變動,有就自動開 issue 或在頁首標「本翻譯對應英文版<日期>,原文已有更新」。翻譯不用即時跟上,但落後是可見的、可以認領的,而不是悄悄爛掉。DanSnow 提到的 Crowdin 本質上也是把「哪段過時」變成系統狀態;純 markdown 流程用 commit hash 可以做到同一件事。

繁中的部分:簡轉繁加一份用語對照表(内存→記憶體、程序→程式、默认→預設、信息→資訊)大致夠用,工具鏈成熟,可以先從這裡開始;如果台灣使用者夠多、有人願意長期認領,再考慮獨立的繁中版,語感還是有差。

DanSnow iT邦好手 1 級 ‧ 2026-09-22 20:37:02 檢舉

用 commit hash 的方法我覺得很不錯耶

libredb iT邦新手 5 級 ‧ 2026-09-23 06:32:20 檢舉

@helenanova
「齊全但過時」排在「精簡但正確」後面,這點我們完全同意。目前那行提示是固定的文字,還不會知道自己落後了多少。記下翻譯當時對應的 commit hash、由 CI 比對,是很自然的下一步,我們會評估要不要做。

@libredb 補一個順手的好處:有了 hash,「落後多少」就不用猜——git rev-list --count ..HEAD -- README.md 會直接告訴你英文版後來改了幾次。這個數字可以印進頁首提示(「本翻譯落後英文版 N 次更新」),也可以反過來設門檻:累積超過 N 次才自動開 issue 催人,零星小改就不打擾。

1

原則上是這樣,一律只將英文版先處理好,也只有英文版才是人工修正的。

其它語言的走向,得先決定好方向。「直譯」或是「轉譯」

直譯來說,會比較容易也比較單純。也就是不管文法通順,直接翻譯就對了。
但相對的,就有可能會發生文法或語意不通順或誤解的問題。

轉譯來說,則是需要由懂該語言及英文的人才來處理。
先讀懂英文的本意,再將其依意思重新解釋翻譯。
但這就得對應相關的人才。雖然現在也可以靠AI來處理。
不過現今的AI還只能做到直譯後重新解釋,並不一定很完整。

再加上技術性的文案中,有可能會有些專有名詞。有些名詞並不太適合轉譯。最好還是維持原英文。

libredb iT邦新手 5 級 ‧ 2026-09-24 02:32:41 檢舉

專有名詞維持英文這點,我們踩過,而且是踩在「不是 README」的地方。

前陣子我們在中國的幾個技術社群發過幾篇文章,一開始有些詞是照著英文直翻的,結果被指出來讀起來很怪:wire protocol 翻成「線協議」(當地習慣講「通信協議」)、event log 翻成「台賬」(那是會計用語)、full marks 翻成「鎖」。這些字面上都對得上,但當地工程師不這樣講,一看就知道不是本地人寫的,整篇的可信度就先掉一截。

後來我們做的事跟你說的「轉譯」比較接近,但範圍縮小了:維護一份詞彙對照表,只管那些翻了會變怪的詞,其餘該留英文就留英文(像 InnoDB、prepared protocol、wire protocol 這種,我們現在乾脆不翻)。這比整篇轉譯便宜很多,而且不需要一個全職懂雙語的人。

AI 那段您說得也準。我們試過讓它直接產出譯文,問題不是文法,是它會很有自信地把專有名詞也一起「翻順」,反而更難發現。所以現在的用法是:AI 產草稿,但對照表裡的詞由 CI 硬性檢查,不合就擋下來。錯的地方至少是可見的。

martin20
iT邦新手 5 級 ‧ 2026-09-30 22:01:29
【**此則訊息已被站方移除**】

我要發表回答

立即登入回答