rag-flex

Public
Plugin
Revisions
Back

docs / I18N.zh-TW.md

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