一句日文錯誤訊息是怎麼被組出來的：ValidX 語言包的介面觀察

（本文事件日期為 2026 年 8 月 28 日，掘金平臺上的一篇技術長文，以回顧角度撰寫。）

先從一個副檔名看起。在 ValidX 專案的資源目錄裡，躺著九個 properties 檔案：ValidationMessages.properties、ValidationMessages_zh.properties、_en、_ja、_ko、_fr、_de、_es、_ru。八種語言，九個檔案，多出來的那一個是無後綴的預設檔。這個看似冗餘的配置，其實是整套國際化設計裡最有味道的細節：無後綴檔名上寫著「預設」，內容卻是中文；英文反而是獨立的 _en 包。換句話說，任何一個沒被覆蓋的語言環境，最終會先落到中文，再一路回退到英文。

一個驗證庫的錯誤訊息，通常被當成功能文件的一小節匆匆帶過。但對一個準備出海的系統來說，它就是使用者真正會讀到的唯一文案。日本使用者送出格式錯誤的電話號碼，畫面上跳出中文「手機號碼格式不正確」；德國使用者的生日欄位出現中英混雜的亂碼；或者更常見的，開發者在 Controller 裡寫滿 if (lang == EN) 的分支，改一句文案要動三處程式碼。這些都是錯誤訊息沒有被當成介面來設計的後果。

兩條路徑，一套文案

ValidX 的做法可以拆成三層來看。

第一層是檔案層。九個 properties 檔案承載八種語言，用 ResourceBundle 的標準命名慣例切分。這個選擇本身就很節制：沒有發明新的檔案格式，沒有引入資料庫或 JSON 設定，而是回到 Java 生態裡最古老、最多工具支援的資源檔機制。UTF8Control 強制以 UTF-8 讀檔，解決了 properties 歷史上 ISO-8859-1 的編碼宿疾，這是那種使用者永遠不會察覺、但少它就會在日文環境炸出問號的細節。

第二層是取用層。注解式驗證（@Email 之類）走 Hibernate Validator 的 MessageInterpolator，訊息寫成 {key} 佔位符，按執行緒的 Locale 解析；鏈式 API 則走自研的 MessageManager，直接以 getMessage(key, locale) 取文。兩條路徑最終都從同一套語言包拿文案。這個「單一來源」的約束比看上去重要：許多庫的常見病是注解走一套預設文案、程式化呼叫走另一套，結果同一個欄位錯誤在不同入口顯示兩種說法，口徑分裂在使用者眼裡就是「這個系統不可靠」。

第三層是回退層。指定語言、英文、key 本身，三級依序嘗試。回退機制是國際化設計裡最考驗品味的地方：太慷慨，使用者會看到語言混雜；太嚴格，會直接裸奔出內部代碼。ValidX 選了「寧可英文也不要亂碼」的中間路線，並用 ConcurrentHashMap 快取已載入的語言包，把這條回退鏈的代價壓在第一次查詢。

key 的命名，是給未來的維護者看的

訊息 key 採完全限定名，把驗證器的命名空間直接編進字串裡。這在當下看不出好處，但它的讀者是三年後接手的人：當錯誤訊息在日誌裡、在翻譯表格裡、在客服的截圖裡流轉時，一個能自我說明來源的 key，本身就是文件。

把這套機制放回更大的脈絡。我們先前在觀察日本企業的審批介面時提過，工具能不能被用下去，往往取決於它在地化做得夠不夠徹底，印章與簽核欄位如此，錯誤訊息的語言也如此。而對照谷歌把法律 AI 做成一種專業介面的思路，會發現同一個方向：專業工具的介面語言，是產品能不能跨過專業門檻的條件，附屬功能。

兜底兜到中文，是一個立場

回到開頭那個多出來的檔案。無後綴預設檔放中文、英文另立 _en 包，這個配置可以被讀成專案對自身出發點的坦白：它是中文社羣的產物，中文是它的第一語言，英文是面向世界的第二層保險。大多數國際化框架的慣例恰好相反，英文當預設，其他語言各自掛後綴。ValidX 沒有遵循這個慣例，後果是任何冷門語言環境的使用者會先看到中文。

這裡沒有標準答案，但有一個明確的設計判斷可以給：回退鏈的終點應該放在「最多數使用者讀得懂」的語言上，而這個判斷應該跟專案的實際使用者結構一致，跟開發者的舒適區不一致。對一個以中文開發者為主要受眾的開源庫，中文當預設檔完全合理；但如果它的野心包含被海外專案直接依賴，那個無後綴檔案遲早要換成英文，或者至少在文件裡把這條回退鏈講清楚，讓接入者知道自己在簽什麼約。

錯誤訊息是系統裡被閱讀次數最多的文字，卻往往是維護優先序的最後一格。ValidX 這套九檔案的配置告訴我們，把這一格做好不需要發明任何新東西，需要的是把「誰會在什麼語言下讀到這句話」當成設計問題認真回答一次。答案放在哪個檔案裡，就是那個系統對世界的態度。