i18n-manager-mcp

LLM-MCP-Servers/i18n-manager-mcp

3.2

If you are the rightful owner of i18n-manager-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A Model Context Protocol (MCP) server designed for managing i18n translation files, enabling LLM to easily read, edit, and manage internationalization translation data.

Tools
6
Resources
0
Prompts
0

i18n Manager MCP

一個專為管理 i18n 翻譯檔案設計的 MCP (Model Context Protocol) 服務器，讓 LLM 能夠輕鬆地讀取、編輯和管理國際化翻譯資料。

功能特色

🎯 核心功能

  • 路徑式存取：使用點號分隔的路徑存取翻譯內容 (如 HOME.NAV.LIST.0.TITLE)
  • 多語系支援：同時處理多個語系的翻譯檔案
  • 靈活的資料操作：支援字串、物件、陣列等各種資料類型
  • 批量處理：一次操作多個翻譯條目

🛠️ 提供的 MCP 工具

  1. i18n-get - 讀取翻譯內容
  2. i18n-set - 設定翻譯內容
  3. i18n-delete - 刪除翻譯條目
  4. i18n-list-paths - 列舉指定路徑下的所有子路徑
  5. i18n-batch - 批量處理多個操作
  6. i18n-search - 透過內容搜尋路徑（支援模糊搜尋）

快速開始

安裝依賴

npm install

建置專案

npm run build

執行測試

npm test

開發模式

npm run dev

配置設定

環境變數

  • I18N_LOCALES_PATH: i18n 檔案資料夾路徑 (預設: "./locales")

支援的檔案結構

locales/
├── zh-tw.json
├── en.json
└── ja.json

每個檔案代表一個語系，檔案名稱即為語系代碼。

使用範例

1. 讀取翻譯內容

// 讀取單一語系
{
  "tool": "i18n-get",
  "args": {
    "path": "HOME.TITLE",
    "locale": "zh-tw"
  }
}
// 回傳: "首頁"

// 讀取多語系
{
  "tool": "i18n-get",
  "args": {
    "path": "HOME.TITLE",
    "locale": "zh-tw",
    "locales": ["zh-tw", "en"]
  }
}
// 回傳: { "zh-tw": "首頁", "en": "Home" }

2. 設定翻譯內容

// 設定單一翻譯
{
  "tool": "i18n-set",
  "args": {
    "path": "HOME.NEW_TITLE",
    "value": "新首頁",
    "locale": "zh-tw"
  }
}

// 設定物件
{
  "tool": "i18n-set",
  "args": {
    "path": "HOME.META",
    "value": {
      "title": "首頁",
      "description": "網站首頁"
    },
    "locale": "zh-tw"
  }
}

3. 列舉路徑

{
  "tool": "i18n-list-paths",
  "args": {
    "basePath": "HOME",
    "locale": "zh-tw"
  }
}
// 回傳: ["HOME.TITLE", "HOME.NAV.LIST.0.TITLE", "HOME.NAV.LIST.0.DESC", ...]

4. 搜尋翻譯內容

// 完全匹配搜尋
{
  "tool": "i18n-search",
  "args": {
    "query": "首頁標題",
    "locale": "zh-tw",
    "options": {
      "threshold": 0
    }
  }
}
// 回傳: { path: "HOME.TITLE", value: "首頁標題", score: 0 }

// 模糊搜尋
{
  "tool": "i18n-search",
  "args": {
    "query": "首頁",
    "locale": "zh-tw",
    "options": {
      "threshold": 0.3,
      "limit": 5
    }
  }
}
// 回傳: [
//   { path: "HOME.TITLE", value: "首頁標題", score: 0.12 },
//   { path: "HOME.SUBTITLE", value: "首頁副標題", score: 0.25 },
//   ...
// ]

// 多個查詢字串（OR 邏輯）
{
  "tool": "i18n-search",
  "args": {
    "query": ["首頁", "導航"],
    "locale": "zh-tw",
    "options": {
      "threshold": 0.3
    }
  }
}

5. 批量操作

{
  "tool": "i18n-batch",
  "args": {
    "operations": [
      {
        "type": "get",
        "path": "HOME.TITLE"
      },
      {
        "type": "set",
        "path": "HOME.NEW_SECTION",
        "value": "新區塊"
      },
      {
        "type": "delete",
        "path": "HOME.OLD_SECTION"
      }
    ],
    "locale": "zh-tw"
  }
}

專案架構

src/
├── server.ts                     # MCP 服務器入口
├── tools/                        # MCP 工具層
│   ├── __tests__/
│   ├── i18n-get-tool.ts          # 讀取工具
│   ├── i18n-set-tool.ts          # 編輯工具
│   ├── i18n-delete-tool.ts       # 刪除工具
│   ├── i18n-list-paths-tool.ts   # 路徑列舉工具
│   ├── i18n-batch-tool.ts        # 批量操作工具
│   └── i18n-search-tool.ts       # 搜尋工具 ⭐ NEW
├── core/                         # 核心業務邏輯層
│   ├── __tests__/
│   ├── i18n-reader.ts            # 讀取核心邏輯
│   ├── i18n-writer.ts            # 寫入核心邏輯
│   ├── i18n-deleter.ts           # 刪除核心邏輯
│   ├── i18n-path-lister.ts       # 路徑列舉核心邏輯
│   ├── i18n-batch-processor.ts   # 批量處理核心邏輯
│   └── i18n-searcher.ts          # 搜尋核心邏輯 ⭐ NEW
├── services/                     # 基礎服務層
│   ├── __tests__/
│   ├── i18n-manager.ts           # i18n 檔案管理
│   ├── file-handler.ts           # 檔案操作處理
│   └── path-utils.ts             # 路徑解析工具
└── types/
    └── i18n-types.ts             # TypeScript 類型定義

路徑格式

基本路徑

HOME.TITLE           → 物件屬性存取
HOME.NAV.LIST        → 巢狀物件存取
HOME.NAV.LIST.0      → 陣列索引存取

支援的資料類型

  • 字串: "Hello World"
  • 數字: 42
  • 布林值: true/false
  • 物件: { "key": "value" }
  • 陣列: ["item1", "item2"]

開發指南

TDD 開發流程

本專案遵循 TDD (Test-Driven Development) 開發模式：

  1. 寫測試 - 先撰寫測試案例
  2. 紅燈 - 執行測試，確認失敗
  3. 寫程式 - 撰寫最少程式碼讓測試通過
  4. 綠燈 - 執行測試，確認通過
  5. 重構 - 改善程式碼品質

測試命令

# 執行所有測試
npm test

# 監控模式
npm run test:watch

# 測試覆蓋率
npm run test:coverage

程式碼品質

# 執行 ESLint 檢查
npm run lint

# 自動修正 ESLint 問題
npm run lint:fix

技術規格

系統需求

  • Node.js: >= 18.0.0
  • TypeScript: ^5.0.0

主要依賴

  • @modelcontextprotocol/sdk: MCP 協議支援
  • lodash: 工具函數庫
  • fuse.js: 模糊搜尋引擎
  • vitest: 測試框架

測試統計

  • 總測試數: 151 個測試案例
  • 通過率: 100%
  • 測試檔案: 14 個

授權條款

MIT License

貢獻指南

  1. Fork 此專案
  2. 建立功能分支 (git checkout -b feature/amazing-feature)
  3. 提交變更 (git commit -m 'Add some amazing feature')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 開啟 Pull Request

未來計劃

  • 內容搜尋功能 - 透過翻譯文字反向查找路徑（已完成 ✅）
  • 支援 Vue SFC 中的 <i18n> 區塊
  • 支援 Next.js 模組化 i18n 結構
  • 新增翻譯內容驗證功能
  • 提供 CLI 工具
  • 支援更多檔案格式 (YAML, TOML)
  • 多語系搜尋（跨語系搜尋相同內容）

常見問題

Q: 如何更改 i18n 檔案的預設路徑？

A: 設定環境變數 I18N_LOCALES_PATH 即可，例如：I18N_LOCALES_PATH=./src/locales

Q: 支援巢狀物件的深層存取嗎？

A: 是的，支援任意深度的路徑存取，如 HOME.SECTION.SUBSECTION.ITEM.PROPERTY

Q: 可以同時操作多個語系嗎？

A: 可以，使用 locales 參數可以同時對多個語系進行操作

Q: 如何處理陣列類型的翻譯資料？

A: 使用數字索引存取，如 HOME.NAV.LIST.0.TITLE 存取陣列第一個元素的 TITLE 屬性

Q: 搜尋功能支援哪些選項？

A: 支援完全匹配（threshold: 0）和模糊搜尋（threshold: 0-1），以及 fuse.js 的各種進階選項，如 minMatchCharLength、distance、ignoreLocation 等

Q: 如何優化搜尋效能？

A: 使用較小的 threshold 值（接近 0）可以提高搜尋精確度並減少結果；設定 limit 參數限制結果數量