@ansstory/hias 1.0.4 → 1.0.6

package/README.zh-CN.md

@@ -0,0 +1,531 @@
+# hias-cli
+
+> 个人脚手架 CLI，内置国际化翻译工具链。
+
+## 安装
+
+```sh
+npm i @ansstory/hias -g
+```
+
+## 使用
+
+```
+hias <command> [options]
+```
+
+---
+
+## 快速开始（国际化翻译）
+
+### 1. 配置 API 密钥
+
+注册一个翻译服务商，然后在项目中生成配置文件：
+
+```sh
+hias setting
+```
+
+编辑 `.hias/setting.json`，填入 `appId` 和 `secretKey`：
+
+```json
+{
+  "translationSetting": {
+    "appId": "your_app_id",
+    "secretKey": "your_secret_key",
+    "provider": "baidu"
+  }
+}
+```
+
+> **没有 API 密钥？** 留空即可使用回退模式——中文原文直接作为 key，国际化迁移仍然可以完成。
+
+### 2. 预览变更（推荐）
+
+```sh
+hias tfo src/views myNamespace --dry-run
+```
+
+显示行级 diff 并提示 `Apply changes? (y/N)`。
+
+### 3. 执行翻译
+
+```sh
+hias tfo src/views myNamespace
+```
+
+语言包文件生成到 `.hias/lang/myNamespace/`。若 `replaceOriginalFile` 为 `true`，则直接覆盖源文件。
+
+---
+
+## 命令
+
+### `create <project>`（别名: `crt`）
+
+从框架模板创建项目。
+
+交互式提示列出所有可用框架。选择后模板将从 Gitee 下载到 `<project>/` 目录。
+
+```sh
+hias create my-app
+```
+
+**可用框架：**
+
+| 名称         | 说明                    |
+| ------------ | ----------------------- |
+| `vue2`       | Vue 2 模板              |
+| `vue3`       | Vue 3 模板              |
+| `vue-ts`     | Vue 3 + TypeScript 模板 |
+| `uni-vite`   | uni-app + Vite 模板     |
+| `nuxt-web`   | Nuxt.js 网页模板        |
+| `vue-screen` | Vue 数据大屏模板        |
+| `react`      | React JSX 模板          |
+| `react-ts`   | React TypeScript 模板   |
+
+---
+
+### `adv <name> [options]`
+
+添加 Vue 组件文件。
+
+```sh
+hias adv Demo -d src/components
+hias adv index -d src/views/demo
+```
+
+### `adr <name> [options]`
+
+添加 React JSX 组件文件。
+
+```sh
+hias adr Demo -d src/components
+```
+
+### `adrt <name> [options]`
+
+添加 React TSX 组件文件。
+
+```sh
+hias adrt Demo -d src/components
+```
+
+### `adrd <name> [options]`
+
+添加 Redux JSX Store 文件。
+
+```sh
+hias adrd useDemoStore -d src/store/modules
+```
+
+### `adrdt <name> [options]`
+
+添加 Redux TSX Store 文件。
+
+```sh
+hias adrdt useDemoStore -d src/store/modules
+```
+
+#### 组件命令通用选项
+
+| 选项                | 说明                                                       |
+| ------------------- | ---------------------------------------------------------- |
+| `-d, --dest <path>` | 目标文件夹，默认 `src/components`，支持 Windows 反斜杠路径 |
+
+如果 `name` 为 `index`，则组件文件以父文件夹名命名。
+
+---
+
+### `close-port <ports...>`
+
+关闭占用一个或多个端口的进程。
+
+```sh
+hias close-port 8076 8077
+hias close-port 8076,8077
+hias close-port 3000
+```
+
+支持空格分隔和逗号分隔的端口列表。兼容 Windows（`netstat` + `taskkill`）、macOS 和 Linux（`lsof` + `kill`）。
+
+---
+
+### `lang [language]`
+
+设置或查看 CLI 语言。
+
+```sh
+hias lang zh-CN
+hias lang en
+hias lang -l           # 查看当前语言
+```
+
+| 选项         | 说明         |
+| ------------ | ------------ |
+| `-l, --list` | 显示当前语言 |
+
+支持的语言：`en`、`zh-CN`。
+
+语言偏好存储在 `~/.hias-cli/config.json` 中。
+
+---
+
+### 翻译命令
+
+翻译系统从源文件中提取中文，替换为 `$t()` 国际化调用，并生成语言包 JSON 文件。支持百度翻译 API 和腾讯云 TMT API。
+
+#### `tf [file] [name]`
+
+翻译单个文件。
+
+```sh
+hias tf src/views/index.vue vue
+hias tf src/views/index.vue vue --verbose
+```
+
+| 参数 / 选项          | 说明                                                                  |
+| -------------------- | --------------------------------------------------------------------- |
+| `file`（位置参数）   | 要翻译的文件路径                                                      |
+| `name`（位置参数）   | 国际化命名空间 key（默认使用父目录名）                                |
+| `-n, --name <name>`  | 指定命名空间的另一种方式                                              |
+| `--dry-run`          | 预览变更但不实际修改文件（显示行级 diff，确认后执行）                 |
+| `-v, --verbose`      | 显示详细逐文件日志，替代进度 spinner                                  |
+| `--show-extractions` | 仅展示所有提取到的中文文本及其文件和位置，不执行翻译也不发送 API 请求 |
+
+**支持的文件类型：** `.vue`、`.js`、`.ts`、`.jsx`、`.tsx`、`.json`
+
+#### `tfo [folder] [name]`
+
+递归翻译文件夹内所有支持的文件。
+
+```sh
+hias tfo src/views views
+hias tfo src/views views --verbose
+```
+
+| 参数 / 选项           | 说明                                                                                                |
+| --------------------- | --------------------------------------------------------------------------------------------------- |
+| `folder`（位置参数）  | 文件夹路径                                                                                          |
+| `name`（位置参数）    | 国际化命名空间 key（默认使用文件夹名）                                                              |
+| `-n, --name <name>`   | 指定命名空间的另一种方式                                                                            |
+| `--dry-run`           | 预览变更但不实际修改文件（显示行级 diff，确认后执行）                                               |
+| `-v, --verbose`       | 显示详细逐文件日志，替代进度 spinner                                                                |
+| `--exclude <pattern>` | 排除匹配 glob 模式的文件（如 `**/*.test.js`、`node_modules/**`）。使用 minimatch 匹配。可多次指定。 |
+| `--show-extractions`  | 仅展示所有提取到的中文文本及其文件和位置，不执行翻译也不发送 API 请求                               |
+
+#### `setting`
+
+生成项目级翻译配置文件。
+
+```sh
+hias setting
+```
+
+在当前项目目录下创建 `.hias/setting.json`。
+
+#### `globalsetting`
+
+生成全局翻译配置文件。
+
+```sh
+hias globalsetting
+```
+
+创建或更新 `~/.hias-cli/config.json`，保留已有的 `language` 设置。
+
+#### `gitignore`
+
+将 `.hias` 添加到项目的 `.gitignore`。若文件不存在则创建，若已存在则追加条目。
+
+```sh
+hias gitignore
+```
+
+---
+
+#### `rollback`
+
+恢复上一次翻译操作的原文件并清理生成的输出。
+
+每次翻译运行会在 `.hias/.langbackup/<timestamp>_<name>/` 下创建一个快照。执行 `rollback` 会恢复最近一次快照并删除该快照，保留更早的快照供多次单步回滚。
+
+```sh
+hias rollback
+hias rollback --list              # 列出所有可用备份
+hias rollback --name 20250101_120000_vue  # 回滚指定备份
+hias rollback --keep 3            # 仅保留最近 3 个备份，删除更旧的
+```
+
+**行为：** 若当时 `replaceOriginalFile` 为 `true`，则还原原始源文件；若为 `false`，则仅删除输出目录 `.hias/lang/<name>/`。
+
+**`--keep` 行为：** 按备份目录名称（时间戳）排序，删除最旧的备份，只保留最近的 N 个。若备份总数 ≤ N 则不操作。
+
+| 选项             | 说明                                |
+| ---------------- | ----------------------------------- |
+| `-l, --list`     | 列出所有可用备份                    |
+| `--name <name>`  | 按名称回滚指定备份                  |
+| `--keep <count>` | 仅保留最近 N 个备份，删除更旧的备份 |
+
+---
+
+## 配置
+
+### 配置级联
+
+翻译设置按以下优先级解析：
+
+1. **项目级** — 当前工作目录下的 `.hias/setting.json`
+2. **全局** — `~/.hias-cli/config.json`（通过 `hias globalsetting` 创建）
+3. **默认值** — 硬编码的默认值（如下所示）
+
+### 设置文件格式
+
+```json
+{
+  "translationSetting": {
+    "locales": ["zh-CN", "en-US"],
+    "outDir": ".hias/lang",
+    "fallbackToKey": true,
+    "replaceOriginalFile": false,
+    "provider": "tencent",
+    "_provider_hint": "'baidu','tencent'",
+    "i18nCallTemplate": "$t",
+    "extensions": [".vue", ".js", ".ts", ".jsx", ".tsx", ".json"],
+    "appId": "",
+    "secretKey": ""
+  }
+}
+```
+
+### 配置字段说明
+
+| 字段                  | 类型       | 默认值               | 说明                                                                                                                               |
+| --------------------- | ---------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `locales`             | `string[]` | `["zh-CN", "en-US"]` | 语言代码列表。**第一个为源语言**，其余为目标语言。例如 `["zh-CN", "en-US", "ja-JP", "ko-KR"]` 会同时生成英文、日文、韩文三套语言包 |
+| `outDir`              | `string`   | `".hias/lang"`       | 生成的语言包和翻译副本的输出目录                                                                                                   |
+| `fallbackToKey`       | `boolean`  | `true`               | 翻译 API 不可用时是否生成 key                                                                                                      |
+| `replaceOriginalFile` | `boolean`  | `false`              | 为 `true` 时直接覆盖源文件（不复制到 `outDir`）                                                                                    |
+| `provider`            | `string`   | `"tencent"`          | 翻译服务商：`"baidu"` 或 `"tencent"`                                                                                               |
+| `i18nCallTemplate`    | `string`   | `"$t"`               | i18n 函数名。当包含 `{{key}}` 时直接替换；否则包装为 `$t('key')`                                                                   |
+| `extensions`          | `string[]` | —                    | 覆盖支持的文件扩展名（如 `[".vue", ".ts"]`），默认支持所有类型                                                                     |
+| `appId`               | `string`   | `""`                 | 百度 AppId 或腾讯 SecretId                                                                                                         |
+| `secretKey`           | `string`   | `""`                 | 百度 SecretKey 或腾讯 SecretKey                                                                                                    |
+
+### 翻译服务商
+
+| 服务商     | `provider` 值 | `appId`       | `secretKey`    |
+| ---------- | ------------- | ------------- | -------------- |
+| 百度翻译   | `"baidu"`     | 百度 AppId    | 百度 SecretKey |
+| 腾讯云 TMT | `"tencent"`   | 腾讯 SecretId | 腾讯 SecretKey |
+
+`appId` 和 `secretKey` 都留空则使用回退模式（中文原文同时作为 key 和 value）。
+
+> **配置校验：** 加载配置时会自动校验字段格式（如 `locales` 是否为数组、`provider` 是否为支持的枚举值、`appId`/`secretKey` 是否为字符串等）。格式不符合时将发出警告并回退至默认值，不会中断流程。
+
+### 翻译服务商配置
+
+#### 百度翻译
+
+1. 访问 [百度翻译开放平台](https://fanyi-api.baidu.com/) 注册账号
+2. 创建应用获取 **AppId** 和 **SecretKey**
+3. 配置文件中设置 `"provider": "baidu"`
+
+#### 腾讯云 TMT
+
+1. 访问 [腾讯云 TMT](https://console.cloud.tencent.com/tmt) 开通服务
+2. 创建 API 密钥获取 **SecretId**（填入 `appId`）和 **SecretKey**
+3. 配置文件中设置 `"provider": "tencent"`
+
+---
+
+## 输出结构
+
+翻译完成后会创建以下目录结构（假设 `locales: ["zh-CN", "en-US", "ja-JP"]`）：
+
+```
+.hias/
+├── setting.json              # 项目级配置文件
+├── lang/
+│   └── <命名空间>/
+│       ├── zh-CN.json        # 源语言包
+│       ├── en-US.json        # 目标语言包 ①
+│       ├── ja-JP.json        # 目标语言包 ②
+│       └── <file>.vue        # 翻译副本（仅 replaceOriginalFile=false 时）
+├── .translation-cache.json   # 翻译缓存（自动生成）
+└── .langbackup/
+    └── <时间戳>_<命名空间>/
+        └── <file>.vue.bak    # 原始文件备份
+```
+
+语言包采用 `{ namespace: { key: value } }` 嵌套格式，可直接用于 `vue-i18n` 等库的模块注册。
+
+---
+
+## 翻译行为
+
+### 源码提取
+
+工具扫描源文件并从以下位置提取中文：
+
+- **引号字符串**：`'中文'`、`"中文"`、`` `中文{expr}文` ``（模板字面量含表达式时拆分，仅提取静态中文段）
+- **Vue 模板**：`{{ '中文' }}`、`<div>中文</div>`
+- **Vue 复杂表达式**：`{{ isHidden || '中文' }}`、`{{ isHidden ?? '中文' }}`（提取表达式中的引号字符串）
+- **Vue 指令**：`v-if="text1 == '中文'"`（提取指令表达式中的内联字符串）
+- **JSX/TSX 文本节点**：`<span>中文 {name}</span>`（支持含表达式的混合文本）
+- **JSX/TSX 属性**：`<div title="中文">` 或 `<div title={'中文'}>`
+- **JSON 值**：`"key": "中文值"`
+- **HTML 普通属性**：`<div title="兴趣">`（Vue 模板中）
+
+注释（`//`、`/* */`、`<!-- -->`）会被正确跳过。`data-*` 和 `aria-*` 属性会被排除。
+
+### 替换模式
+
+| 上下文               | 替换前                    | 替换后                                             |
+| -------------------- | ------------------------- | -------------------------------------------------- |
+| Vue 模板文本节点     | `<div>兴趣</div>`         | `<div>{{ $t('demo.interest') }}</div>`             |
+| Vue 模板插值         | `{{ '兴趣' }}`            | `{{ $t('demo.interest') }}`                        |
+| Vue 复杂表达式       | <code>{{ isHidden &#124;&#124; '兴趣' }}</code> | <code>{{ isHidden &#124;&#124; $t('demo.interest') }}</code> |
+| Vue 指令表达式       | `v-if="text1 == '文本'"`  | `v-if="text1 == $t('demo.text')"`                  |
+| Vue script / JS / TS | `'兴趣'`                  | `$t('demo.interest')`                              |
+| JSX 文本节点         | `<div>兴趣</div>`         | `<div>{$t('demo.interest')}</div>`                 |
+| JSX 属性             | `<div title="兴趣">`      | `<div title={$t('demo.interest')}>`                |
+| Vue v-bind 属性      | `<div :title="'兴趣'">`   | `<div :title="$t('demo.interest')">`               |
+| 模板字面量           | `` `中文 ${name} 测试` `` | `` `$t('demo.chinese') ${name} $t('demo.test')` `` |
+| JSON 值              | `"兴趣"`                  | `"interest"`（直接替换为翻译结果）                 |
+
+### 语言包文件格式
+
+**翻译成功时**（基于英文的 key）：
+
+```json
+// zh-CN.json
+{ "demo": { "interest": "兴趣", "test": "测试" } }
+// en-US.json
+{ "demo": { "interest": "interest", "test": "test" } }
+// ja-JP.json（如果 locales 包含 ja-JP）
+{ "demo": { "interest": "興味", "test": "テスト" } }
+```
+
+**翻译失败时**（根据中文自动生成简短 key）：
+
+```json
+// zh-CN.json 和 en-US.json
+{ "demo": { "提起妈妈的手_一股酸痛便涌上心头": "提起妈妈的手，一股酸痛便涌上心头...", "test": "测试" } }
+```
+
+### Key 生成规则
+
+| 场景         | 来源     | Key 生成方式             | 最大长度 |
+| ------------ | -------- | ------------------------ | -------- |
+| API 翻译成功 | 英文译文 | 转 snake_case            | 40 字符  |
+| API 回退     | 原始中文 | 去标点、`。` → `_`，截断 | 40 字符  |
+
+Key 会去重：若两段文本生成相同的截断 key，则自动追加 `_1`、`_2`……
+
+### 翻译 API 回退警告
+
+当翻译 API 调用失败（网络错误、凭据无效或频率限制）时，工具会在控制台输出警告，例如：
+
+```
+⚠ Translation API failed, falling back to Chinese keys for this batch
+```
+
+然后回退到基于中文的自动生成 key（参见上方 [Key 生成规则](#key-生成规则)），确保即使没有 API 连接也能继续进行国际化迁移。
+
+> **逐文本回退：** 若批次内部分文本翻译成功、部分失败，仅失败文本走回退模式，成功文本仍使用英文 key。这避免了因单个文本翻译失败导致整批内容降级使用中文 key。
+
+### 翻译缓存
+
+每次成功的 API 翻译结果会缓存到 `.hias/.translation-cache.json`。下次翻译相同文本时（无论哪个命名空间），直接从缓存读取，避免重复的网络请求和 API 费用。
+
+- 缓存以原文为键、目标语言为二级键：`{ "text": { "en": "translated" } }`
+- 缓存文件破损或格式错误时自动忽略，不影响正常翻译流程
+- 缓存自动在"空闲时"落盘（`setImmediate` 延迟写入），不阻塞翻译管线
+
+### 未使用翻译清理
+
+替换中文为 `$t()` 调用后，工具会检查现有的语言包 JSON 文件，**移除源文件中不再引用的 key**，防止语言包随时间积累过期条目。
+
+清理操作仅针对本次翻译操作使用的命名空间，且仅移除在所有扫描源文件中引用数为零的 key。
+
+### 命名空间规范化
+
+源文件中已有的 `$t('旧命名空间.key')` 调用会在翻译时自动更新为当前命名空间。
+
+### 预览模式（--dry-run）
+
+指定 `--dry-run` 时，工具会显示所有变更的行级 diff，但不实际修改文件。预览结束后提示 `Apply changes? (y/N)` — 输入 `y` 或 `yes` 执行变更，其他任何输入取消。
+
+### `i18nCallTemplate` 自定义
+
+`i18nCallTemplate` 字段控制国际化函数名和调用格式：
+
+| 模板值                       | 生成结果                              |
+| ---------------------------- | ------------------------------------- |
+| `"$t"`（默认）               | `$t('demo.interest')`                 |
+| `"$te"`                      | `$te('demo.interest')`                |
+| `"{{key}}"`                  | `demo.interest`（裸 key，无函数调用） |
+| `"t('{{key}}')"`             | `t('demo.interest')`                  |
+| `"i18n.global.t('{{key}}')"` | `i18n.global.t('demo.interest')`      |
+
+当模板 **包含** `{{key}}` 时，`{{key}}` 会被替换为 `namespace.subKey`；当 **不包含** `{{key}}` 时，包装为 `template('namespace.subKey')`。
+
+### 工作流建议
+
+- **首次翻译前务必使用 `--dry-run`** 预览提取结果，确认无误后再执行
+- **针对单文件翻译**：`hias tfo src/views/MyComponent myComp`
+- **排除配置或生成文件**：`hias tfo src/views views --exclude "**/*.test.js" --exclude node_modules`
+- **按模块划分命名空间**：例如 `src/views/user/` → 命名空间 `user`，`src/views/admin/` → 命名空间 `admin`，保持语言包小巧聚焦
+- **启用 `replaceOriginalFile` 后及时回滚确认**：`hias rollback`
+- **多次回滚**：每次 `rollback` 撤销一个快照，可多次执行逐步回退
+- **重复翻译安全**：已有 `$t()` 调用会在重新提取前被剥离，重复运行只会添加剩余中文的翻译
+
+---
+
+## 全局配置
+
+全局配置文件位于 `~/.hias-cli/config.json`，语言设置和翻译设置共用此文件：
+
+```json
+{
+  "language": "zh-CN",
+  "translationSetting": {
+    "locales": ["zh-CN", "en-US"],
+    "outDir": ".hias/lang",
+    "fallbackToKey": true,
+    "replaceOriginalFile": false,
+    "provider": "tencent",
+    "_provider_hint": "'baidu','tencent'",
+    "i18nCallTemplate": "$t",
+    "extensions": [".vue", ".js", ".ts", ".jsx", ".tsx", ".json"],
+    "appId": "",
+    "secretKey": ""
+  }
+}
+```
+
+由以下命令管理：
+
+- **`hias lang <language>`** — 设置 `language`
+- **`hias globalsetting`** — 创建/更新 `translationSetting`
+
+---
+
+## 全部命令一览
+
+| 命令                    | 别名  | 说明                         |
+| ----------------------- | ----- | ---------------------------- |
+| `create <project>`      | `crt` | 从框架模板创建项目           |
+| `adv <name>`            | –     | 添加 Vue 组件                |
+| `adr <name>`            | –     | 添加 React JSX 组件          |
+| `adrt <name>`           | –     | 添加 React TSX 组件          |
+| `adrd <name>`           | –     | 添加 Redux JSX Store         |
+| `adrdt <name>`          | –     | 添加 Redux TSX Store         |
+| `close-port <ports...>` | –     | 关闭端口的进程               |
+| `lang [language]`       | –     | 设置或查看 CLI 语言          |
+| `tf [file] [name]`      | –     | 单个文件翻译                 |
+| `tfo [folder] [name]`   | –     | 递归翻译文件夹               |
+| `setting`               | –     | 生成项目级翻译配置           |
+| `globalsetting`         | –     | 生成全局翻译配置             |
+| `gitignore`             | –     | 添加 `.hias` 到 `.gitignore` |
+| `rollback`              | –     | 回滚上一次翻译操作           |

package/lib/config.js

@@ -1,18 +1,22 @@
-const foramworkUrl = {
-  'vue2': 'https://gitee.com/AnsStory/hias-vue2-template.git',
-  'vue3': 'https://gitee.com/AnsStory/hias-vue3-template.git',
-  'vue-ts': 'https://gitee.com/AnsStory/hias-vue-ts-template.git',
-  'uni-vite': 'https://gitee.com/AnsStory/hias-uni-vite.git',
-  'nuxt-web': 'https://gitee.com/AnsStory/hias-nuxt-web-tmp.git',
-  'vue-screen': 'https://gitee.com/AnsStory/hias-vite-screen.git',
-  'react': 'https://gitee.com/AnsStory/hias-react-template.git',
-  'react-ts': 'https://gitee.com/AnsStory/hias-react-ts-template.git',
-}
-const framwork = Object.keys(foramworkUrl)
-
-module.exports = {
-  // 可选择的框架
-  framwork,
-  // 框架对应的下载地址
-  foramworkUrl,
-}
+// 项目配置文件 - 定义支持的框架模板和对应的下载地址
+// 各框架模板的 Gitee 仓库地址映射表
+const foramworkUrl = {
+  vue2: 'https://gitee.com/AnsStory/hias-vue2-template.git',
+  vue3: 'https://gitee.com/AnsStory/hias-vue3-template.git',
+  'vue-ts': 'https://gitee.com/AnsStory/hias-vue-ts-template.git',
+  'uni-vite': 'https://gitee.com/AnsStory/hias-uni-vite.git',
+  'nuxt-web': 'https://gitee.com/AnsStory/hias-nuxt-web-tmp.git',
+  'vue-screen': 'https://gitee.com/AnsStory/hias-vite-screen.git',
+  react: 'https://gitee.com/AnsStory/hias-react-template.git',
+  'react-ts': 'https://gitee.com/AnsStory/hias-react-ts-template.git',
+}
+
+// 从 foramworkUrl 对象提取所有支持的框架名称
+const framwork = Object.keys(foramworkUrl)
+
+module.exports = {
+  // 可选择的框架列表
+  framwork,
+  // 框架对应的下载地址映射表
+  foramworkUrl,
+}