RAG-Flex 語言系統說明

English | 日本語

🌍 雙層語言機制

RAG-Flex 採用雙層語言機制，提供真正的多語系體驗：

1️⃣ 配置介面語言（系統自動）

由系統語言決定

🔍 自動檢測：插件啟動時自動檢測系統語言
🎨 介面顯示：所有配置項標籤使用檢測到的語言
🔄 如何切換：改變作業系統的語言設置，然後重啟插件

範例：

系統語言是繁體中文 → 配置介面顯示中文
系統語言是英文 → 配置介面顯示英文

2️⃣ 訊息語言（用戶可選）

由用戶在設置中選擇

⚙️ 可配置：在插件設置中選擇「訊息語言 / Message Language」
💬 影響範圍：運行時的所有狀態訊息、錯誤提示、LLM 系統提示
🔄 即時生效：切換後立即影響新的操作

範例：

系統是英文，但選擇「繁體中文 (zh-TW)」
- 配置介面：英文 ✅
- 運行訊息：繁體中文 ✅

📊 語言影響範圍對照表

部分	使用的語言	如何切換	何時生效
配置介面標籤	系統語言	改變系統語言 + 重啟插件	插件啟動時
訊息語言選擇器	系統語言	改變系統語言 + 重啟插件	插件啟動時
其他配置項標籤	系統語言	改變系統語言 + 重啟插件	插件啟動時
狀態訊息	訊息語言	在設置中選擇	立即
錯誤提示	訊息語言	在設置中選擇	立即
LLM 系統提示	訊息語言	在設置中選擇	立即

🎯 使用場景

場景 1：完全單語環境

情況： 系統是繁體中文，想要全中文體驗

設置：

✅ 系統語言：繁體中文
✅ 訊息語言：選擇「繁體中文 (zh-TW)」

結果：

配置介面：繁體中文
運行訊息：繁體中文

場景 2：混合語言環境

情況： 系統是英文，但想看中文訊息

設置：

✅ 系統語言：English
✅ 訊息語言：選擇「繁體中文 (zh-TW)」

結果：

配置介面：English
運行訊息：繁體中文

場景 3：學習模式

情況： 想同時看到中英文對照學習技術術語

設置：

✅ 系統語言：任意
✅ 訊息語言：切換觀察不同語言的表達方式

結果：

可以隨時切換訊息語言來對照學習

🔧 技術原理

為什麼配置介面不能動態切換？

這是 LM Studio SDK 的限制，不是設計缺陷：

// 插件生命週期
export async function main(context: PluginContext) {
    // 1. 檢測系統語言
    const systemLang = detectSystemLanguage();

    // 2. 生成配置介面（使用系統語言）
    const config = createDynamicConfig(models, systemLang);

    // 3. 註冊到 LM Studio（此時配置介面就固定了）
    context.withConfigSchematics(config);
    //                          ↑
    //                    從此無法更改
}

SDK 限制：

withConfigSchematics() 只能調用一次
註冊後無法動態更新配置介面
沒有提供「配置介面重新渲染」的 API

我們的解決方案：

✅ 配置介面：跟隨系統語言（真正的本地化）
✅ 運行時訊息：用戶可選（靈活性）
✅ 兩者結合：達到最佳用戶體驗

🌐 系統語言檢測機制

檢測順序

環境變量 LANG （最常見）
環境變量 LANGUAGE （備選）
環境變量 LC_ALL （locale 覆蓋）

檢測邏輯

export function detectSystemLanguage(): SupportedLanguage {
    const envLang = process.env.LANG ||
                    process.env.LANGUAGE ||
                    process.env.LC_ALL || "";

    // 繁體中文（台灣、香港、澳門）
    if (envLang.includes("zh_TW") ||
        envLang.includes("zh-TW") ||
        envLang.includes("zh_HK")) {
        return "zh-TW";
    }

    // 簡體中文（暫時映射到繁體，未來支援）
    if (envLang.includes("zh_CN") ||
        envLang.includes("zh-CN")) {
        return "zh-TW";  // TODO: 添加 zh-CN 支援
    }

    // 預設英文
    return "en";
}

🔄 如何切換系統語言

Windows

設定 → 時間與語言 → 語言
新增語言或設為預設
重新啟動應用程式

環境變量設置（進階）：

set LANG=zh_TW.UTF-8
set LANG=en_US.UTF-8

macOS

系統偏好設定 → 語言與地區
新增或重新排序偏好語言
重新啟動應用程式

終端機設置：

export LANG=zh_TW.UTF-8
export LANG=en_US.UTF-8

Linux

臨時設置（當前會話）：

export LANG=zh_TW.UTF-8
lms dev

永久設置：

# 編輯 ~/.bashrc 或 ~/.zshrc
echo 'export LANG=zh_TW.UTF-8' >> ~/.bashrc
source ~/.bashrc

📝 訊息語言設置

在 LM Studio 中設置

打開 LM Studio
進入 插件設置
找到 RAG-Flex 插件
第一個設置項：
- 英文系統：「Message Language」
- 中文系統：「訊息語言」
選擇想要的語言：
- English (en)
- 繁體中文 (zh-TW)

✅ 測試語言切換

測試配置介面語言

切換系統語言（Windows/macOS/Linux）
重啟插件：
```
lms dev
```
檢查配置介面：所有標籤應該使用系統語言

測試訊息語言

在 LM Studio 中：選擇不同的「訊息語言」
上傳測試文件
觀察狀態訊息：

選擇 English (en):

Loading embedding model: bge-m3...
Retrieving relevant citations...
Retrieved 5 citations (threshold: 0.4)

選擇繁體中文 (zh-TW):

載入 Embedding 模型: bge-m3...
正在檢索相關片段...
成功檢索到 5 個相關片段 (門檻: 0.4)

🎓 最佳實踐建議

給一般用戶

建議配置：

系統語言 = 訊息語言
兩者保持一致，獲得最統一的體驗

給雙語用戶

建議配置：

系統語言 = 工作主要語言
訊息語言 = 根據當前任務靈活切換

優勢：

配置介面穩定不變
運行訊息可以根據需要切換
學習技術術語的中英對照

給開發者

測試建議：

測試兩種系統語言環境
測試所有訊息語言選項
驗證配置介面正確顯示
驗證運行訊息正確切換

🆘 常見問題

Q: 為什麼切換「訊息語言」後配置介面沒變？

A: 這是設計行為，不是錯誤。

✅ 配置介面：由系統語言決定（插件啟動時固定）
✅ 運行訊息：由訊息語言決定（可隨時切換）

如果想改變配置介面語言，請改變系統語言後重啟插件。

Q: 如何獲得完全的中文體驗？

A: 兩步設置：

系統語言：設為繁體中文
訊息語言：選擇「繁體中文 (zh-TW)」

重啟插件後，所有內容都是中文。

Q: 支援簡體中文嗎？

A: 目前還不支援，但已規劃中。

當前支援：English、繁體中文
計劃支援：簡體中文、日文、韓文

如需簡體中文支援，請參考 src/locales/README.md 了解如何貢獻翻譯。

Q: 可以添加其他語言嗎？

A: 可以！請參考：

詳細指南：src/locales/README.md
繁體中文版：src/locales/README.zh-TW.md

添加新語言只需 5 個步驟，歡迎貢獻！

📚 相關文檔

完整實現文檔：I18N_IMPLEMENTATION.md
快速摘要：SUMMARY.md
變更日誌：CHANGELOG_I18N.md
語言文件維護：src/locales/README.md
繁體中文版維護指南：src/locales/README.zh-TW.md

💡 設計理念

這個雙層語言機制的設計基於以下原則：

尊重系統設定：配置介面跟隨系統語言
提供靈活性：運行訊息可由用戶選擇
真正的本地化：避免雙語混雜的界面
用戶友好：清楚說明每個設置的作用

🙏 致謝

感謝 LM Studio 團隊提供優秀的插件 SDK，讓我們能夠構建這個多語系系統。

最後更新：2026-01-02 版本：v1.2.0

rag-flex

RAG-Flex 語言系統說明

🌍 雙層語言機制

1️⃣ 配置介面語言（系統自動）

2️⃣ 訊息語言（用戶可選）

📊 語言影響範圍對照表

🎯 使用場景

場景 1：完全單語環境

場景 2：混合語言環境

場景 3：學習模式

🔧 技術原理

為什麼配置介面不能動態切換？

🌐 系統語言檢測機制

檢測順序

檢測邏輯

🔄 如何切換系統語言

Windows

macOS

Linux

📝 訊息語言設置

在 LM Studio 中設置

✅ 測試語言切換

測試配置介面語言

測試訊息語言

🎓 最佳實踐建議

給一般用戶

給雙語用戶

給開發者

🆘 常見問題

Q: 為什麼切換「訊息語言」後配置介面沒變？

Q: 如何獲得完全的中文體驗？

Q: 支援簡體中文嗎？

Q: 可以添加其他語言嗎？

📚 相關文檔

💡 設計理念

🙏 致謝