OdfKit i18n 與在地化
本文件說明 OdfKit 目前的 i18n 與在地化機制，包含訊息來源、語系選擇、 遞補規則與已支援語言。API 文件站台（GitHub Pages）的 17 語系入口屬另一套 機制，見 api-docs-site.md。
1. 機制概觀
OdfKit 透過 OdfKit.Compliance.OdfLocalizer 統一管理錯誤訊息、警告訊息與
部分合規建議文字。程式庫內拋出的可在地化訊息，會以訊息鍵值搭配語系字典
解析，而不是在程式碼中直接寫死文字。
2. 語系選擇與遞補
OdfLocalizer 解析訊息時的順序如下：
- 呼叫時明確傳入的
CultureInfo OdfLocalizer.DefaultCultureCultureInfo.CurrentUICulture- 英文預設字典
en - 若仍找不到，回傳原始訊息鍵值
3. 已支援語言
目前已註冊的語言如下：
| 語系代碼 | 說明 |
|---|---|
en |
英文 |
zh-TW |
正體中文（臺灣） |
de |
德文 |
fr |
法文 |
nl |
荷蘭文 |
nb |
挪威文 Bokmål |
pt |
葡萄牙文 |
it |
義大利文 |
sk |
斯洛伐克文 |
da |
丹麥文 |
ms |
馬來文 |
ko |
韓文 |
ja |
日文 |
es |
西班牙文 |
cs |
捷克文 |
pl |
波蘭文 |
pt-BR |
巴西葡萄牙文 |
目前全部 17 種語言的訊息鍵值數量一致（2026-07-11 查證），皆有對應翻譯。pt-BR 會優先使用巴西譯文；
pt-PT 與其他葡萄牙語地區則透過父文化特性遞補至 pt。歷史上曾出現新增
訊息鍵值時僅同步補上 en／zh-TW、其餘語言暫時依第 2 節遞補規則退回英文的情形；若日後
再發生類似落差，應在合併前一併補齊全部語言，而非僅補兩種語言後留待後續處理。
4. 使用方式
直接取得訊息
using OdfKit.Compliance;
string message = OdfLocalizer.GetMessage("ODF0001");
指定語系
using System.Globalization;
using OdfKit.Compliance;
string message = OdfLocalizer.GetMessage(
"ODF0001",
new CultureInfo("zh-TW"));
設定全域預設語系
using System.Globalization;
using OdfKit.Compliance;
OdfLocalizer.DefaultCulture = new CultureInfo("zh-TW");
5. 適用範圍
- 合規檢查與驗證相關訊息
- 可在地化的例外訊息與警告訊息
- 部分建議修復文字
公開與受保護 API 的 XML 文件已採英文＋正體中文雙語格式；英文摘要提供 .NET IntelliSense 的主要說明，正體中文摘要保留臺灣地區用語。
6. 相關原始碼
| 檔案 | 用途 |
|---|---|
OdfKit/Compliance/OdfLocalizer.cs |
訊息解析、格式化與文化遞補 |
OdfKit/Compliance/OdfLocalizer.Languages.cs |
語言字典註冊與各語系內容 |
OdfKit/Compliance/i18n/exceptions.<culture>.json |
例外／診斷訊息來源真相（17 語系） |
OdfKit/Compliance/OdfLocalizer.Exceptions.<culture>.cs |
由 JSON 產生的字典 partial（勿手改） |
OdfKit/Compliance/OdfLocalizer.Exceptions.cs |
例外字典入口（註冊 17 語系） |
eng/Generate-LocalizerExceptionsFromJson.ps1 |
JSON → C# 產生／-VerifyOnly |
eng/Add-LocalizerKey.ps1 |
新增鍵腳手架（寫 JSON 並重產） |