localizationAdd

Adds a complete translation entry with Chinese and English versions to localization files for multilingual application support.

Instructions

新增一個完整的翻譯項目

Input Schema

TableJSON Schema

Name	Required	Description	Default
`filePath`	Yes
`entry`	Yes

Implementation Reference

tools/localizationTool.ts:346-371 (handler)

Core handler function that implements the localizationAdd tool logic: reads CSV, checks for duplicate Key, adds the new entry, writes back to file, and handles caching.

static async addEntry(filePath: string, entry: LocalizationEntry): Promise<string> {
  try {
    // 檢查輸入是否有效
    if (!entry.Key) {
      return '錯誤: Key 不能為空';
    }
    
    const records = await this.getCSVData(filePath);

    // 檢查Key是否已存在
    if (records.some(e => e.Key === entry.Key)) {
      return `錯誤: Key "${entry.Key}" 已存在`;
    }

    // 新增項目
    records.push({...entry});

    // 寫回檔案並更新緩存
    await this.writeCSVData(filePath, records);

    return `成功新增Key "${entry.Key}"`;
  } catch (error) {
    console.error(`新增翻譯項失敗: ${error instanceof Error ? error.message : '未知錯誤'}`);
    throw error;
  }
}

main.ts:346-369 (registration)

MCP server registration of the 'localizationAdd' tool, including inline input schema and handler wrapper that calls LocalizationTool.addEntry.

server.tool("localizationAdd",
    "新增一個完整的翻譯項目",
    {
        filePath: z.string(),
        entry: z.object({
            Key: z.string(),
            "zh-TW": z.string(),
            "zh-CN": z.string(),
            en: z.string()
        }).passthrough()
    },
    async ({ filePath, entry }) => {
        try {
            const result = await LocalizationTool.addEntry(filePath, entry as LocalizationEntry);
            return {
                content: [{ type: "text", text: result }]
            };
        } catch (error) {
            return {
                content: [{ type: "text", text: `新增失敗: ${error instanceof Error ? error.message : "未知錯誤"}` }]
            };
        }
    }
);

main.ts:348-356 (schema)

Zod input schema validation for the localizationAdd tool defining filePath and entry structure (Key, zh-TW, zh-CN, en).

{
    filePath: z.string(),
    entry: z.object({
        Key: z.string(),
        "zh-TW": z.string(),
        "zh-CN": z.string(),
        en: z.string()
    }).passthrough()
},

tools/localizationTool.ts:8-14 (schema)

TypeScript interface defining the structure of a LocalizationEntry used in the tool.

export interface LocalizationEntry {
  Key: string;
  'zh-TW': string;
  'zh-CN': string;
  en: string;
  [key: string]: string; // 其他可能的語言欄位
}

tools/localizationTool.ts:212-258 (helper)

Helper method to write updated CSV data back to file with proper column ordering, CSV stringification, and cache update, used by addEntry.

private static async writeCSVData(filePath: string, data: LocalizationEntry[]): Promise<void> {
  try {
    // 檢查是否有數據
    if (data.length === 0) {
      throw new Error('沒有要寫入的數據');
    }
    
    // 獲取所有列名
    const columnSet = new Set<string>();
    columnSet.add('Key'); // 確保Key始終是第一列
    
    // 收集所有可能的列
    data.forEach(entry => {
      Object.keys(entry).forEach(key => columnSet.add(key));
    });
    
    // 轉換為陣列並將Key移到第一位
    const columns = Array.from(columnSet);
    if (columns[0] !== 'Key') {
      const keyIndex = columns.indexOf('Key');
      if (keyIndex > 0) {
        columns.splice(keyIndex, 1);
        columns.unshift('Key');
      }
    }
    
    // 使用csv-stringify生成CSV內容
    const output = stringify(data, {
      header: true,
      columns,
      quoted_string: true,
      quoted_empty: true
    });
    
    // 寫入檔案
    await fs.writeFile(filePath, output, 'utf-8');
    
    // 更新緩存
    this.cache.set(filePath, {
      data: [...data], // 深拷貝防止引用問題
      timestamp: Date.now()
    });
  } catch (error) {
    console.error(`寫入CSV檔案失敗: ${error instanceof Error ? error.message : '未知錯誤'}`);
    throw error;
  }
}

GonMCPtool