@agentscope-ai/i18n 0.1.9 → 1.0.0

package/lib/cli.js

@@ -1,7 +1,17 @@
 #!/usr/bin/env node
 
 const { program } = require('commander');
-const { init, initMT, patch, patchMT, check, reverse, medusaRun } = require('./index');
+const {
+  init,
+  initMT,
+  patch,
+  patchMT,
+  check,
+  reverse,
+  translate,
+  replaceOnly,
+  medusaRun,
+} = require('./index');
 const path = require('path');
 const fs = require('fs-extra');
 
@@ -191,6 +201,54 @@ withCommonOptions(
   }
 });
 
+withCommonOptions(
+  program
+    .command('translate')
+    .description(
+      'Extract Chinese text, translate, and generate locale files + mds-payload.json (Step 1/3, no code modification)',
+    )
+    .option(
+      '-f, --file <path>',
+      'Process a single file instead of the entire targetPath directory',
+    ),
+).action(async (options) => {
+  try {
+    const config = getConfig(options);
+    const targetPath = resolveCommonOptions(options, config);
+    if (options.file) {
+      config.file = options.file;
+    }
+    await translate(targetPath, config);
+  } catch (error) {
+    console.error('translate 失败:', error.message);
+    process.exit(1);
+  }
+});
+
+withCommonOptions(
+  program
+    .command('replace')
+    .description(
+      'Replace Chinese text in code with $i18n.get calls using saved translation state (Step 3/3)',
+    )
+    .option(
+      '-f, --file <path>',
+      'Process a single file instead of the entire targetPath directory',
+    ),
+).action(async (options) => {
+  try {
+    const config = getConfig(options);
+    const targetPath = resolveCommonOptions(options, config);
+    if (options.file) {
+      config.file = options.file;
+    }
+    await replaceOnly(targetPath, config);
+  } catch (error) {
+    console.error('replace 失败:', error.message);
+    process.exit(1);
+  }
+});
+
 program
   .command('init-config')
   .description('Create i18n.config.js configuration file from template')

package/lib/core/file-processor.js

@@ -14,6 +14,7 @@ const {
 const { extractStringValue } = require('../utils/ast-utils');
 const { askQuestion } = require('../utils/cli-utils');
 const { generateMedusaExcel } = require('../utils/excel-utils');
+const { generateMdsPayload } = require('../utils/mds-payload');
 const parseJSX = require('../parse-jsx');
 
 // 提取共用的文案处理函数
@@ -285,6 +286,16 @@ const singleTranslateAndUpdateFiles = async (
     console.log('    [取消] 已取消代码替换操作');
   }
 
+  // 生成 mds-payload.json（供 sync-to-mds 脚本使用）
+  if (medusa && medusa.appName) {
+    const newKeys = Object.keys(zhCN);
+    generateMdsPayload({
+      localesFilePath,
+      appName: medusa.appName,
+      filterKeys: newKeys,
+    });
+  }
+
   // 询问是否生成medusa excel文件
   if (medusa && medusa.appName && medusa.group && medusa.keyMap) {
     let shouldGenExcel = skipConfirm;

package/lib/core/translator.js

@@ -4,12 +4,15 @@ const find = require('find');
 const { parse } = require('@babel/parser');
 const traverse = require('@babel/traverse').default;
 const generate = require('@babel/generator').default;
-const { scanFiles } = require('../utils/file-utils');
+const { scanFiles, resolveFiles, injectImportStatement } = require('../utils/file-utils');
 const {
   processFiles,
   translateAndUpdateFiles,
   singleTranslateAndUpdateFiles,
+  replaceKeysInFiles,
 } = require('./file-processor');
+const { generateMdsPayload } = require('../utils/mds-payload');
+const { singleKeyTranslate, singleTranslate } = require('../utils/translation-utils');
 const {
   extractI18nKey,
   chnRegExp,
@@ -1129,6 +1132,181 @@ const reverse = async function (sourcePath, params) {
   };
 };
 
+/**
+ * translate: 提取中文 → AI翻译 → 写locale文件 → 生成mds-payload.json
+ * 不会修改源代码，是三步工作流的第一步。
+ */
+const translate = async function (sourcePath, params) {
+  try {
+    const {
+      fileType = '.tsx,.js,.ts,.jsx',
+      localesFilePath,
+      keyPrefix,
+      doNotTranslateFiles,
+      dashScope,
+      medusa,
+      file: singleFile,
+    } = params;
+
+    if (!keyPrefix) {
+      throw new Error('keyPrefix is required in params');
+    }
+    if (!dashScope || !dashScope.apiKey) {
+      throw new Error('dashScope.apiKey is required for translation');
+    }
+
+    console.log('');
+    console.log('=== [Step 1/3] translate ===');
+    console.log('    提取中文 → AI翻译 → 生成locale文件和mds-payload');
+    console.log('');
+
+    const files = resolveFiles(sourcePath, fileType, doNotTranslateFiles, singleFile);
+    console.log(`    # 扫描到 ${files.length} 个文件`);
+
+    const { i18n } = await processFiles(files, params);
+
+    if (Object.keys(i18n).length === 0) {
+      console.log('    [完成] 没有找到需要提取的文案');
+      return { newKeysCount: 0, newKeys: [], keyMap: {} };
+    }
+
+    console.log(`    [进度] AI正在翻译key...共${Object.keys(i18n).length}条`);
+    const { keyMap, zhCN } = await singleKeyTranslate(i18n, dashScope);
+
+    const zhCNPath = `${localesFilePath}/zh-cn.json`;
+    let existingZhCN = {};
+    try {
+      existingZhCN = fs.readJsonSync(zhCNPath);
+    } catch {
+      // first run
+    }
+    const finalZhCN = { ...existingZhCN, ...zhCN };
+    fs.ensureDirSync(localesFilePath);
+    fs.writeJsonSync(zhCNPath, finalZhCN, { spaces: 2 });
+    console.log(`    [完成] 更新 zh-cn.json (新增${Object.keys(zhCN).length}条)`);
+
+    console.log(`    [进度] AI正在翻译多语言...`);
+    const translatedResults = await singleTranslate(zhCN, dashScope);
+
+    for (const [language, translatedI18n] of Object.entries(translatedResults)) {
+      const languagePath = `${localesFilePath}/${language}.json`;
+      let existing = {};
+      try {
+        existing = fs.readJsonSync(languagePath);
+      } catch {
+        // first run
+      }
+      fs.writeJsonSync(languagePath, { ...existing, ...translatedI18n }, { spaces: 2 });
+      console.log(`    [完成] 更新 ${language}.json`);
+    }
+
+    const newKeys = Object.keys(zhCN);
+
+    generateMdsPayload({
+      localesFilePath,
+      appName: medusa?.appName,
+      filterKeys: newKeys,
+    });
+
+    const statePath = path.resolve(localesFilePath, '.i18n-state.json');
+    fs.writeJsonSync(
+      statePath,
+      { keyMap, newKeys, sourcePath, timestamp: new Date().toISOString() },
+      { spaces: 2 },
+    );
+    console.log(`    [完成] 翻译状态已保存到 ${statePath}`);
+
+    if (medusa && medusa.appName && medusa.group && medusa.keyMap) {
+      try {
+        await generateMedusaExcel({ localesFilePath, medusa, newKeys });
+      } catch (error) {
+        console.error('    [警告] 生成medusa excel文件失败:', error.message);
+      }
+    }
+
+    console.log('');
+    console.log(`    ✅ translate 完成！新增 ${newKeys.length} 条翻译文案`);
+    console.log('    下一步: 运行 sync-to-mds 同步到美杜莎，然后运行 replace 替换代码');
+    console.log('');
+
+    return { newKeysCount: newKeys.length, newKeys, keyMap };
+  } catch (error) {
+    console.error('    [错误] translate 失败:', error);
+    throw error;
+  }
+};
+
+/**
+ * replaceOnly: 将代码中的中文替换为 $i18n.get 调用。
+ * 依赖 translate 步骤保存的 .i18n-state.json，是三步工作流的第三步。
+ */
+const replaceOnly = async function (sourcePath, params) {
+  try {
+    const {
+      fileType = '.tsx,.js,.ts,.jsx',
+      localesFilePath,
+      keyPrefix,
+      doNotTranslateFiles,
+      functionImportPath,
+      i18nFilePath,
+      file: singleFile,
+    } = params;
+
+    if (!keyPrefix) {
+      throw new Error('keyPrefix is required in params');
+    }
+
+    console.log('');
+    console.log('=== [Step 3/3] replace ===');
+    console.log('    将代码中的中文替换为 $i18n.get 调用');
+    console.log('');
+
+    const statePath = path.resolve(localesFilePath, '.i18n-state.json');
+    if (!fs.existsSync(statePath)) {
+      throw new Error(`.i18n-state.json 不存在于 ${localesFilePath}，请先运行 translate 命令`);
+    }
+    const state = fs.readJsonSync(statePath);
+    const { keyMap } = state;
+    console.log(`    [进度] 已加载翻译状态 (${Object.keys(keyMap).length} 条keyMap)`);
+
+    const files = resolveFiles(sourcePath, fileType, doNotTranslateFiles, singleFile);
+    console.log(`    # 扫描到 ${files.length} 个文件`);
+
+    const { fileCodeMap, needImportFiles } = await processFiles(files, params);
+
+    console.log(`    [进度] 开始替换文件中的key...`);
+    await replaceKeysInFiles(sourcePath, keyMap, fileType, fileCodeMap);
+
+    if (needImportFiles.size > 0 && functionImportPath) {
+      console.log(`    [进度] 开始添加导入语句...`);
+      needImportFiles.forEach((file) => {
+        injectImportStatement(file, functionImportPath);
+      });
+      console.log(`    [完成] 已为${needImportFiles.size}个文件添加导入语句`);
+    }
+
+    if (i18nFilePath) {
+      const sourceI18nPath = path.join(__dirname, '../i18n.ts');
+      const targetI18nPath = path.join(i18nFilePath, 'index.ts');
+      if (!fs.existsSync(targetI18nPath)) {
+        fs.ensureDirSync(i18nFilePath);
+        fs.copyFileSync(sourceI18nPath, targetI18nPath);
+        console.log(`    [完成] i18n.ts 已复制到 ${targetI18nPath}`);
+      }
+    }
+
+    fs.removeSync(statePath);
+    console.log(`    [完成] 已清理临时状态文件`);
+
+    console.log('');
+    console.log('    ✅ replace 完成！代码中的中文已替换为 $i18n.get 调用');
+    console.log('');
+  } catch (error) {
+    console.error('    [错误] replace 失败:', error);
+    throw error;
+  }
+};
+
 module.exports = {
   init,
   initMT,
@@ -1136,4 +1314,6 @@ module.exports = {
   patchMT,
   check,
   reverse,
+  translate,
+  replaceOnly,
 };

package/lib/index.js

@@ -1,4 +1,13 @@
-const { init, initMT, patch, patchMT, check, reverse } = require('./core/translator');
+const {
+  init,
+  initMT,
+  patch,
+  patchMT,
+  check,
+  reverse,
+  translate,
+  replaceOnly,
+} = require('./core/translator');
 const { run: medusaRun } = require('./utils/medusa');
 
 module.exports = {
@@ -8,5 +17,7 @@ module.exports = {
   patchMT,
   check,
   reverse,
+  translate,
+  replaceOnly,
   medusaRun,
 };

package/lib/utils/file-utils.js

@@ -271,11 +271,32 @@ const scanFiles = (path, fileType, doNotTranslateFiles = []) => {
   }
 };
 
+const resolveFiles = (sourcePath, fileType, doNotTranslateFiles, singleFile) => {
+  if (singleFile) {
+    const nodePath = require('path');
+    const absFile = nodePath.isAbsolute(singleFile)
+      ? singleFile
+      : nodePath.resolve(process.cwd(), singleFile);
+
+    if (!fs.existsSync(absFile)) {
+      throw new Error(`文件不存在: ${absFile}`);
+    }
+    if (shouldIgnoreByComment(absFile)) {
+      console.log(`    # 文件 ${absFile} 包含 @i18n-ignore，已跳过`);
+      return [];
+    }
+    console.log(`    # 单文件模式: ${absFile}`);
+    return [absFile];
+  }
+  return scanFiles(sourcePath, fileType, doNotTranslateFiles);
+};
+
 module.exports = {
   shouldIgnoreFile,
   shouldIgnoreByComment,
   injectImportStatement,
   scanFiles,
+  resolveFiles,
   shouldIgnoreLineByComment,
   shouldIgnoreBlockByComment,
 };

package/lib/utils/mds-payload.js

@@ -0,0 +1,86 @@
+const fs = require('fs-extra');
+const path = require('path');
+
+const LANG_CODE_TO_MCMS = {
+  'en-us': 'en_US',
+  'zh-cn': 'zh_CN',
+  'ja-jp': 'ja_JP',
+  'ko-kr': 'ko_KR',
+  'zh-tw': 'zh_TW',
+  'fr-fr': 'fr_FR',
+  'de-de': 'de_DE',
+  'es-es': 'es_ES',
+  'pt-br': 'pt_BR',
+  'ru-ru': 'ru_RU',
+  'ar-sa': 'ar_SA',
+  'th-th': 'th_TH',
+  'vi-vn': 'vi_VN',
+  'id-id': 'id_ID',
+  'ms-my': 'ms_MY',
+};
+
+/**
+ * 从 locale JSON 文件生成 MDS payload（McmsWriteDTO 数组）。
+ * 只包含 filterKeys 中的 key（即本次新增/变更的 key）。
+ *
+ * @param {object} options
+ * @param {string} options.localesFilePath - locale 文件目录
+ * @param {string} options.appName        - 美杜莎应用名
+ * @param {string[]} options.filterKeys   - 要包含的 key 列表
+ * @param {object} [options.langCodeMap]  - 自定义语言 code 映射 { 'en-us': 'en_US' }
+ * @returns {object[]} McmsWriteDTO 数组
+ */
+const generateMdsPayload = ({ localesFilePath, appName, filterKeys, langCodeMap }) => {
+  if (!appName) {
+    console.log('    [跳过] 未配置 medusa.appName，跳过 mds-payload 生成');
+    return [];
+  }
+  if (!filterKeys || filterKeys.length === 0) {
+    return [];
+  }
+
+  const codeMap = { ...LANG_CODE_TO_MCMS, ...langCodeMap };
+
+  const localeDir = path.resolve(localesFilePath);
+  if (!fs.existsSync(localeDir)) {
+    console.log(`    [跳过] locale 目录不存在: ${localeDir}`);
+    return [];
+  }
+
+  const localeFiles = fs
+    .readdirSync(localeDir)
+    .filter((f) => f.endsWith('.json') && f !== 'key.json');
+  const locales = {};
+  for (const file of localeFiles) {
+    const langCode = file.replace('.json', '');
+    const mcmsLang = codeMap[langCode] || langCode;
+    try {
+      locales[mcmsLang] = fs.readJsonSync(path.join(localeDir, file));
+    } catch {
+      // skip unreadable files
+    }
+  }
+
+  const keysSet = new Set(filterKeys);
+  const payload = [];
+
+  for (const key of keysSet) {
+    const i18n = {};
+    for (const [mcmsLang, data] of Object.entries(locales)) {
+      if (data[key] !== undefined) {
+        i18n[mcmsLang] = data[key];
+      }
+    }
+    if (Object.keys(i18n).length > 0) {
+      payload.push({ key, appName, i18n });
+    }
+  }
+
+  const outputPath = path.resolve(process.cwd(), 'mds-payload.json');
+  fs.writeJsonSync(outputPath, payload, { spaces: 2 });
+  console.log(`    [完成] 已生成 mds-payload.json (${payload.length} 条), 路径: ${outputPath}`);
+
+  return payload;
+};
+
+module.exports = { generateMdsPayload };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentscope-ai/i18n",
-  "version": "0.1.9",
+  "version": "1.0.0",
   "description": "A tool for translating Chinese content in frontend code repositories",
   "keywords": [
     "i18n",