@ansstory/hias 1.0.6 → 1.0.8

package/README.md

@@ -1,14 +1,14 @@
 # hias-cli
 
-> Personal scaffolding CLI with built-in i18n translation toolkit.
+> 个人脚手架 CLI，内置国际化翻译工具链。
 
-## Install
+## 安装
 
 ```sh
 npm i @ansstory/hias -g
 ```
 
-## Usage
+## 使用
 
 ```
 hias <command> [options]
@@ -16,17 +16,17 @@ hias <command> [options]
 
 ---
 
-## Quick Start (i18n Translation)
+## 快速开始（国际化翻译）
 
-### 1. Set up API credentials
+### 1. 配置 API 密钥
 
-Register a translation provider and create a config file in your project:
+注册一个翻译服务商，然后在项目中生成配置文件：
 
 ```sh
 hias setting
 ```
 
-Edit `.hias/setting.json` with your `appId` and `secretKey`:
+编辑 `.hias/setting.json`，填入 `appId` 和 `secretKey`：
 
 ```json
 {
@@ -38,56 +38,56 @@ Edit `.hias/setting.json` with your `appId` and `secretKey`:
 }
 ```
 
-> **No API key?** Leave both empty for fallback mode — Chinese text is used as keys directly. The i18n migration still completes.
+> **没有 API 密钥？** 留空即可使用回退模式——中文原文直接作为 key，国际化迁移仍然可以完成。
 
-### 2. Preview changes (recommended)
+### 2. 预览变更（推荐）
 
 ```sh
 hias tfo src/views myNamespace --dry-run
 ```
 
-Shows a line-level diff and prompts `Apply changes? (y/N)`.
+显示行级 diff 并提示 `Apply changes? (y/N)`。
 
-### 3. Apply translation
+### 3. 执行翻译
 
 ```sh
 hias tfo src/views myNamespace
 ```
 
-Locale files are written to `.hias/lang/myNamespace/`. If `replaceOriginalFile` is `true`, source files are overwritten in place.
+语言包文件生成到 `.hias/lang/myNamespace/`。若 `replaceOriginalFile` 为 `true`，则直接覆盖源文件。
 
 ---
 
-## Commands
+## 命令
 
-### `create <project>` (alias: `crt`)
+### `create <project>`（别名: `crt`）
 
-Create a project from a framework template.
+从框架模板创建项目。
 
-An interactive prompt will list all available frameworks. After selection, the template is downloaded from Gitee and placed into `<project>/`.
+交互式提示列出所有可用框架。选择后模板将从 Gitee 下载到 `<project>/` 目录。
 
 ```sh
 hias create my-app
 ```
 
-**Available frameworks:**
+**可用框架：**
 
-| Name         | Description                 |
-| ------------ | --------------------------- |
-| `vue2`       | Vue 2 template              |
-| `vue3`       | Vue 3 template              |
-| `vue-ts`     | Vue 3 + TypeScript template |
-| `uni-vite`   | uni-app + Vite template     |
-| `nuxt-web`   | Nuxt.js web template        |
-| `vue-screen` | Vue data screen template    |
-| `react`      | React JSX template          |
-| `react-ts`   | React TypeScript template   |
+| 名称         | 说明                    |
+| ------------ | ----------------------- |
+| `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]`
 
-Add a Vue component file.
+添加 Vue 组件文件。
 
 ```sh
 hias adv Demo -d src/components
@@ -96,7 +96,7 @@ hias adv index -d src/views/demo
 
 ### `adr <name> [options]`
 
-Add a React JSX component file.
+添加 React JSX 组件文件。
 
 ```sh
 hias adr Demo -d src/components
@@ -104,7 +104,7 @@ hias adr Demo -d src/components
 
 ### `adrt <name> [options]`
 
-Add a React TSX component file.
+添加 React TSX 组件文件。
 
 ```sh
 hias adrt Demo -d src/components
@@ -112,7 +112,7 @@ hias adrt Demo -d src/components
 
 ### `adrd <name> [options]`
 
-Add a Redux JSX store file.
+添加 Redux JSX Store 文件。
 
 ```sh
 hias adrd useDemoStore -d src/store/modules
@@ -120,25 +120,25 @@ hias adrd useDemoStore -d src/store/modules
 
 ### `adrdt <name> [options]`
 
-Add a Redux TSX store file.
+添加 Redux TSX Store 文件。
 
 ```sh
 hias adrdt useDemoStore -d src/store/modules
 ```
 
-#### Common options for component commands
+#### 组件命令通用选项
 
-| Option              | Description                                                                   |
-| ------------------- | ----------------------------------------------------------------------------- |
-| `-d, --dest <path>` | Target folder. Defaults to `src/components`. Accepts Windows backslash paths. |
+| 选项                | 说明                                                       |
+| ------------------- | ---------------------------------------------------------- |
+| `-d, --dest <path>` | 目标文件夹，默认 `src/components`，支持 Windows 反斜杠路径 |
 
-If `name` is `index`, the component file is named after the parent folder instead.
+如果 `name` 为 `index`，则组件文件以父文件夹名命名。
 
 ---
 
 ### `close-port <ports...>`
 
-Kill processes occupying one or more ports.
+关闭占用一个或多个端口的进程。
 
 ```sh
 hias close-port 8076 8077
@@ -146,141 +146,155 @@ hias close-port 8076,8077
 hias close-port 3000
 ```
 
-Supports both space-separated and comma-separated port lists. Works on Windows (`netstat` + `taskkill`), macOS, and Linux (`lsof` + `kill`).
+支持空格分隔和逗号分隔的端口列表。兼容 Windows（`netstat` + `taskkill`）、macOS 和 Linux（`lsof` + `kill`）。
 
 ---
 
 ### `lang [language]`
 
-Set or view the CLI language.
+设置或查看 CLI 语言。
 
 ```sh
 hias lang zh-CN
 hias lang en
-hias lang -l           # show current language
+hias lang -l           # 查看当前语言
 ```
 
-| Option       | Description                           |
-| ------------ | ------------------------------------- |
-| `-l, --list` | Display the currently active language |
+| 选项         | 说明         |
+| ------------ | ------------ |
+| `-l, --list` | 显示当前语言 |
 
-Supported languages: `en`, `zh-CN`.
+支持的语言：`en`、`zh-CN`。
 
-Language preference is stored in `~/.hias-cli/config.json`.
+语言偏好存储在 `~/.hias-cli/config.json` 中。
 
 ---
 
-### Translation Commands
+### 翻译命令
 
-The translation system extracts Chinese text from source files, replaces it with `$t()` i18n calls, and generates locale JSON files. Supports Baidu Translate API and Tencent Cloud TMT API.
+翻译系统从源文件中提取中文，替换为 `$t()` 国际化调用，并生成语言包 JSON 文件。支持百度翻译 API 和腾讯云 TMT API。
 
 #### `tf [file] [name]`
 
-Translate a single file.
+翻译单个文件。
 
 ```sh
 hias tf src/views/index.vue vue
 hias tf src/views/index.vue vue --verbose
 ```
 
-| Argument / Option    | Description                                                                                                                |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `file` (positional)  | Path to the file to translate                                                                                              |
-| `name` (positional)  | i18n namespace key (defaults to parent directory name)                                                                     |
-| `-n, --name <name>`  | Alternative way to specify the namespace                                                                                   |
-| `--dry-run`          | Preview changes without modifying files (shows line-level diff, prompts to apply)                                          |
-| `-v, --verbose`      | Show detailed per-file logs instead of a progress spinner                                                                  |
-| `--show-extractions` | Only display all extracted Chinese texts with file paths and positions, without performing translation or making API calls |
+| 参数 / 选项          | 说明                                                                  |
+| -------------------- | --------------------------------------------------------------------- |
+| `file`（位置参数）   | 要翻译的文件路径                                                      |
+| `name`（位置参数）   | 国际化命名空间 key（默认使用父目录名）                                |
+| `-n, --name <name>`  | 指定命名空间的另一种方式                                              |
+| `--dry-run`          | 预览变更但不实际修改文件（显示行级 diff，确认后执行）                 |
+| `-v, --verbose`      | 显示详细逐文件日志，替代进度 spinner                                  |
+| `--show-extractions` | 仅展示所有提取到的中文文本及其文件和位置，不执行翻译也不发送 API 请求 |
 
-**Supported file types:** `.vue`, `.js`, `.ts`, `.jsx`, `.tsx`, `.json`
+**支持的文件类型：** `.vue`、`.js`、`.ts`、`.jsx`、`.tsx`、`.json`
 
 #### `tfo [folder] [name]`
 
-Recursively translate all supported files in a folder.
+递归翻译文件夹内所有支持的文件。
 
 ```sh
 hias tfo src/views views
 hias tfo src/views views --verbose
 ```
 
-| Argument / Option     | Description                                                                                                                      |
-| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `folder` (positional) | Path to the folder                                                                                                               |
-| `name` (positional)   | i18n namespace key (defaults to folder name)                                                                                     |
-| `-n, --name <name>`   | Alternative way to specify the namespace                                                                                         |
-| `--dry-run`           | Preview changes without modifying files (shows line-level diff, prompts to apply)                                                |
-| `-v, --verbose`       | Show detailed per-file logs instead of a progress spinner                                                                        |
-| `--exclude <pattern>` | Exclude files matching a glob pattern (e.g. `**/*.test.js`, `node_modules/**`). Uses minimatch. Can be specified multiple times. |
-| `--show-extractions`  | Only display all extracted Chinese texts with file paths and positions, without performing translation or making API calls       |
+| 参数 / 选项           | 说明                                                                                                |
+| --------------------- | --------------------------------------------------------------------------------------------------- |
+| `folder`（位置参数）  | 文件夹路径                                                                                          |
+| `name`（位置参数）    | 国际化命名空间 key（默认使用文件夹名）                                                              |
+| `-n, --name <name>`   | 指定命名空间的另一种方式                                                                            |
+| `--dry-run`           | 预览变更但不实际修改文件（显示行级 diff，确认后执行）                                               |
+| `-v, --verbose`       | 显示详细逐文件日志，替代进度 spinner                                                                |
+| `--exclude <pattern>` | 排除匹配 glob 模式的文件（如 `**/*.test.js`、`node_modules/**`）。使用 minimatch 匹配。可多次指定。 |
+| `--show-extractions`  | 仅展示所有提取到的中文文本及其文件和位置，不执行翻译也不发送 API 请求                               |
 
 #### `setting`
 
-Generate a project-level translation config file.
+生成项目级翻译配置文件。
 
 ```sh
 hias setting
 ```
 
-Creates `.hias/setting.json` in the current project directory.
+在当前项目目录下创建 `.hias/setting.json`。
 
-#### `globalsetting`
+#### `global-setting`
 
-Generate a global translation config file.
+生成全局翻译配置文件。
 
 ```sh
-hias globalsetting
+hias global-setting
 ```
 
-Creates or updates `~/.hias-cli/config.json`. Preserves any existing `language` setting.
+创建或更新 `~/.hias-cli/config.json`，保留已有的 `language` 设置。
+
+#### `clear-config`
+
+删除全局配置目录 `~/.hias-cli`。
+
+```sh
+hias clear-config
+```
+
+如果需要完全卸载 CLI 并清理用户配置，请执行：
+
+```sh
+hias uninstall -g
+```
+
+该命令会先执行 `hias clear-config`，再执行 `npm uninstall @ansstory/hias -g`。npm v7+ 不会在卸载包时运行旧的 `preuninstall` / `postuninstall` 生命周期脚本，因此单独运行 `npm uninstall` 不会删除 home 目录下的配置文件。
 
 #### `gitignore`
 
-Add `.hias` to the project's `.gitignore` file. Creates `.gitignore` if it doesn't exist, or appends the entry if it already exists.
+将 `.hias` 添加到项目的 `.gitignore`。若文件不存在则创建，若已存在则追加条目。
 
 ```sh
 hias gitignore
 ```
 
-After running, the `.gitignore` file will contain an entry for `.hias`.
-
 ---
 
 #### `rollback`
 
-Restore files from the last translation operation and clean up generated output.
+恢复上一次翻译操作的原文件并清理生成的输出。
 
-Each translation run creates a snapshot in `.hias/.langbackup/<timestamp>_<name>/`. Running `rollback` restores the most recent snapshot and removes it, preserving older snapshots for further step-by-step rollback.
+每次翻译运行会在 `.hias/.langbackup/<timestamp>_<name>/` 下创建一个快照。执行 `rollback` 会恢复最近一次快照并删除该快照，保留更早的快照供多次单步回滚。
 
 ```sh
 hias rollback
-hias rollback --list              # list available backups
-hias rollback --name 20250101_120000_vue  # rollback a specific backup
-hias rollback --keep 3            # keep only the 3 most recent backups, remove older ones
+hias rollback --list              # 列出所有可用备份
+hias rollback --name 20250101_120000_vue  # 回滚指定备份
+hias rollback --keep 3            # 仅保留最近 3 个备份，删除更旧的
 ```
 
-**Behavior:** When `replaceOriginalFile` was `true`, original source files are restored; when it was `false`, only the output directory `.hias/lang/<name>/` is removed.
+**行为：** 若当时 `replaceOriginalFile` 为 `true`，则还原原始源文件；若为 `false`，则仅删除输出目录 `.hias/lang/<name>/`。
 
-**`--keep` behavior:** Backups are sorted by directory name (timestamp), the oldest ones are removed until only N remain. No action if total backups ≤ N.
+**`--keep` 行为：** 按备份目录名称（时间戳）排序，删除最旧的备份，只保留最近的 N 个。若备份总数 ≤ N 则不操作。
 
-| Option           | Description                                            |
-| ---------------- | ------------------------------------------------------ |
-| `-l, --list`     | List all available backups                             |
-| `--name <name>`  | Rollback a specific backup by name                     |
-| `--keep <count>` | Keep only the N most recent backups, remove older ones |
+| 选项             | 说明                                |
+| ---------------- | ----------------------------------- |
+| `-l, --list`     | 列出所有可用备份                    |
+| `--name <name>`  | 按名称回滚指定备份                  |
+| `--keep <count>` | 仅保留最近 N 个备份，删除更旧的备份 |
 
 ---
 
-## Configuration
+## 配置
 
-### Config Cascade
+### 配置级联
 
-Translation settings are resolved in the following priority order:
+翻译设置按以下优先级解析：
 
-1. **Project-level** — `.hias/setting.json` in the current working directory
-2. **Global** — `~/.hias-cli/config.json` (created by `hias globalsetting`)
-3. **Defaults** — hardcoded defaults (shown below)
+1. **项目级** — 当前工作目录下的 `.hias/setting.json`
+2. **全局** — `~/.hias-cli/config.json`（通过 `hias global-setting` 创建）
+3. **默认值** — 硬编码的默认值（如下所示）
 
-### Setting File Format
+### 设置文件格式
 
 ```json
 {
@@ -299,194 +313,194 @@ Translation settings are resolved in the following priority order:
 }
 ```
 
-### Configuration Fields
+### 配置字段说明
 
-| Field                 | Type       | Default              | Description                                                                                                                                                                                           |
-| --------------------- | ---------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `locales`             | `string[]` | `["zh-CN", "en-US"]` | Locale code list. **First entry is the source language**, the rest are target languages. E.g. `["zh-CN", "en-US", "ja-JP", "ko-KR"]` generates English, Japanese, and Korean locale files in one pass |
-| `outDir`              | `string`   | `".hias/lang"`       | Output directory for generated locale files and translated copies                                                                                                                                     |
-| `fallbackToKey`       | `boolean`  | `true`               | Whether to generate keys when translation API is unavailable                                                                                                                                          |
-| `replaceOriginalFile` | `boolean`  | `false`              | When `true`, overwrites source files in place (no copy to `outDir`)                                                                                                                                   |
-| `provider`            | `string`   | `"tencent"`          | Translation provider: `"baidu"` or `"tencent"`                                                                                                                                                        |
-| `i18nCallTemplate`    | `string`   | `"$t"`               | i18n function name. When containing `{{key}}`, it's replaced with `namespace.subKey`; otherwise the function wraps it as `$t('key')`                                                                  |
-| `extensions`          | `string[]` | —                    | Override supported file extensions (e.g. `[".vue", ".ts"]`). Defaults to all supported types                                                                                                          |
-| `appId`               | `string`   | `""`                 | Baidu AppId or Tencent SecretId                                                                                                                                                                       |
-| `secretKey`           | `string`   | `""`                 | Baidu SecretKey or Tencent 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                                                                                                    |
 
-### Translation Providers
+### 翻译服务商
 
-| Provider          | `provider` value | `appId`          | `secretKey`       |
-| ----------------- | ---------------- | ---------------- | ----------------- |
-| Baidu Translate   | `"baidu"`        | Baidu AppId      | Baidu SecretKey   |
-| Tencent Cloud TMT | `"tencent"`      | Tencent SecretId | Tencent SecretKey |
+| 服务商     | `provider` 值 | `appId`       | `secretKey`    |
+| ---------- | ------------- | ------------- | -------------- |
+| 百度翻译   | `"baidu"`     | 百度 AppId    | 百度 SecretKey |
+| 腾讯云 TMT | `"tencent"`   | 腾讯 SecretId | 腾讯 SecretKey |
 
-Leave both `appId` and `secretKey` empty to use fallback mode (Chinese text is used as-is for both key and value in locale files).
+`appId` 和 `secretKey` 都留空则使用回退模式（中文原文同时作为 key 和 value）。
 
-> **Config validation:** Settings are automatically validated when loaded (e.g., `locales` must be an array, `provider` must be a supported enum value, `appId`/`secretKey` must be strings). Invalid values trigger a warning and are reset to defaults without interrupting the workflow.
+> **配置校验：** 加载配置时会自动校验字段格式（如 `locales` 是否为数组、`provider` 是否为支持的枚举值、`appId`/`secretKey` 是否为字符串等）。格式不符合时将发出警告并回退至默认值，不会中断流程。
 
-### API Provider Setup
+### 翻译服务商配置
 
-#### Baidu Translate
+#### 百度翻译
 
-1. Visit [Baidu Translate Open Platform](https://fanyi-api.baidu.com/) and register
-2. Create an application to get **AppId** and **SecretKey**
-3. Set `"provider": "baidu"` in config
+1. 访问 [百度翻译开放平台](https://fanyi-api.baidu.com/) 注册账号
+2. 创建应用获取 **AppId** 和 **SecretKey**
+3. 配置文件中设置 `"provider": "baidu"`
 
-#### Tencent Cloud TMT
+#### 腾讯云 TMT
 
-1. Visit [Tencent Cloud TMT](https://console.cloud.tencent.com/tmt) and enable the service
-2. Create an API key to get **SecretId** (→ `appId`) and **SecretKey**
-3. Set `"provider": "tencent"` in config
+1. 访问 [腾讯云 TMT](https://console.cloud.tencent.com/tmt) 开通服务
+2. 创建 API 密钥获取 **SecretId**（填入 `appId`）和 **SecretKey**
+3. 配置文件中设置 `"provider": "tencent"`
 
 ---
 
-## Output Structure
+## 输出结构
 
-After translation, the following directory structure is created (assuming `locales: ["zh-CN", "en-US", "ja-JP"]`):
+翻译完成后会创建以下目录结构（假设 `locales: ["zh-CN", "en-US", "ja-JP"]`）：
 
 ```
 .hias/
-├── setting.json              # project-level config
+├── setting.json              # 项目级配置文件
 ├── lang/
-│   └── <namespace>/
-│       ├── zh-CN.json        # source locale
-│       ├── en-US.json        # target locale ①
-│       ├── ja-JP.json        # target locale ②
-│       └── <file>.vue        # translated copy (only if replaceOriginalFile=false)
-├── .translation-cache.json   # translation cache (auto-generated)
+│   └── <命名空间>/
+│       ├── zh-CN.json        # 源语言包
+│       ├── en-US.json        # 目标语言包 ①
+│       ├── ja-JP.json        # 目标语言包 ②
+│       └── <file>.vue        # 翻译副本（仅 replaceOriginalFile=false 时）
+├── .translation-cache.json   # 翻译缓存（自动生成）
 └── .langbackup/
-    └── <timestamp>_<namespace>/
-        └── <file>.vue.bak    # original file backup
+    └── <时间戳>_<命名空间>/
+        └── <file>.vue.bak    # 原始文件备份
 ```
 
-Locale files use a nested `{ namespace: { key: value } }` format, making them ready for use with `vue-i18n` or similar libraries via module registration.
+语言包采用 `{ namespace: { key: value } }` 嵌套格式，可直接用于 `vue-i18n` 等库的模块注册。
 
 ---
 
-## Translation Behavior
+## 翻译行为
 
-### Source Code Extraction
+### 源码提取
 
-The tool scans source files and extracts Chinese text from:
+工具扫描源文件并从以下位置提取中文：
 
-- **Quoted strings**: `'中文'`, `"中文"`, `` `中文{expr}文` `` (template literals with expressions are split, only static Chinese segments extracted)
-- **Vue templates**: `{{ '中文' }}`, `<div>中文</div>`, `:title="'中文'"`
-- **Vue complex expressions**: `{{ isHidden || '中文' }}`, `{{ isHidden ?? '中文' }}` (extracts inline quoted strings from expressions)
-- **Vue directives**: `v-if="text1 == '中文'"`, `v-for="..."` (extracts inline strings from directive expressions)
-- **JSX/TSX text nodes**: `<span>中文 {name}</span>` (mixed text with expressions supported)
-- **JSX/TSX attributes**: `<div title="中文">` or `<div title={'中文'}>`
-- **JSON values**: `"key": "中文值"`
-- **Plain HTML attributes**: `<div title="兴趣">` in Vue templates
+- **引号字符串**：`'中文'`、`"中文"`、`` `中文{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 模板中）
 
-Comments (`//`, `/* */`, `<!-- -->`) are correctly skipped. `data-*` and `aria-*` attributes are excluded.
+注释（`//`、`/* */`、`<!-- -->`）会被正确跳过。`data-*` 和 `aria-*` 属性会被排除。
 
-### Replacement Pattern
+### 替换模式
 
-| Context                    | Before                    | After                                              |
-| -------------------------- | ------------------------- | -------------------------------------------------- |
-| Vue template text node     | `<div>兴趣</div>`         | `<div>{{ $t('demo.interest') }}</div>`             |
-| Vue template interpolation | `{{ '兴趣' }}`            | `{{ $t('demo.interest') }}`                        |
-| Vue complex expression     | <code>{{ isHidden &#124;&#124; '兴趣' }}</code> | <code>{{ isHidden &#124;&#124; $t('demo.interest') }}</code> |
-| Vue directive expression   | `v-if="text1 == '文本'"`  | `v-if="text1 == $t('demo.text')"`                  |
-| Vue script / JS / TS       | `'兴趣'`                  | `$t('demo.interest')`                              |
-| JSX text node              | `<div>兴趣</div>`         | `<div>{$t('demo.interest')}</div>`                 |
-| JSX attribute              | `<div title="兴趣">`      | `<div title={$t('demo.interest')}>`                |
-| Vue v-bind attribute       | `<div :title="'兴趣'">`   | `<div :title="$t('demo.interest')">`               |
-| Template literal           | `` `中文 ${name} 测试` `` | `` `$t('demo.chinese') ${name} $t('demo.test')` `` |
-| JSON value                 | `"兴趣"`                  | `"interest"` (replaced with translation directly)  |
+| 上下文               | 替换前                    | 替换后                                             |
+| -------------------- | ------------------------- | -------------------------------------------------- |
+| 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"`（直接替换为翻译结果）                 |
 
-### Locale File Format
+### 语言包文件格式
 
-**When translation succeeds** (English-based keys, truncated to 40 characters):
+**翻译成功时**（基于英文的 key）：
 
 ```json
 // zh-CN.json
 { "demo": { "interest": "兴趣", "test": "测试" } }
 // en-US.json
 { "demo": { "interest": "interest", "test": "test" } }
-// ja-JP.json (if locales includes ja-JP)
+// ja-JP.json（如果 locales 包含 ja-JP）
 { "demo": { "interest": "興味", "test": "テスト" } }
 ```
 
-**When translation fails** (auto-generated short keys from Chinese, truncated to 40 characters):
+**翻译失败时**（根据中文自动生成简短 key）：
 
 ```json
-// zh-CN.json and en-US.json
+// zh-CN.json 和 en-US.json
 { "demo": { "提起妈妈的手_一股酸痛便涌上心头": "提起妈妈的手，一股酸痛便涌上心头...", "test": "测试" } }
 ```
 
-### Key Generation Rules
+### Key 生成规则
 
-| Scenario     | Source             | Key Generation                          | Max Length |
-| ------------ | ------------------ | --------------------------------------- | ---------- |
-| API success  | Translated English | snake_case of translation               | 40 chars   |
-| API fallback | Original Chinese   | first-line punctuation → `_`, truncated | 40 chars   |
+| 场景         | 来源     | Key 生成方式             | 最大长度 |
+| ------------ | -------- | ------------------------ | -------- |
+| API 翻译成功 | 英文译文 | 转 snake_case            | 40 字符  |
+| API 回退     | 原始中文 | 去标点、`。` → `_`，截断 | 40 字符  |
 
-Keys are deduplicated: if two texts produce the same truncated key, `_1`, `_2`, etc. are appended.
+Key 会去重：若两段文本生成相同的截断 key，则自动追加 `_1`、`_2`……
 
-### Translation API Fallback Warning
+### 翻译 API 回退警告
 
-When the translation API call fails (network error, invalid credentials, or rate limit), the tool logs a warning message to the console, e.g.:
+当翻译 API 调用失败（网络错误、凭据无效或频率限制）时，工具会在控制台输出警告，例如：
 
 ```
 ⚠ Translation API failed, falling back to Chinese keys for this batch
 ```
 
-It then falls back to Chinese-based auto-generated keys (see [Key Generation Rules](#key-generation-rules) above). This ensures the i18n migration can proceed even without API connectivity.
+然后回退到基于中文的自动生成 key（参见上方 [Key 生成规则](#key-生成规则)），确保即使没有 API 连接也能继续进行国际化迁移。
 
-> **Per-text fallback:** If some texts in a batch succeed while others fail, only the failed texts use fallback mode — successful texts still use English keys. This prevents a single failure from degrading the entire batch to Chinese keys.
+> **逐文本回退：** 若批次内部分文本翻译成功、部分失败，仅失败文本走回退模式，成功文本仍使用英文 key。这避免了因单个文本翻译失败导致整批内容降级使用中文 key。
 
-### Translation Cache
+### 翻译缓存
 
-Successful API translation results are cached to `.hias/.translation-cache.json`. The next time the same text is encountered (regardless of namespace), it's served from cache, avoiding redundant network requests and API costs.
+每次成功的 API 翻译结果会缓存到 `.hias/.translation-cache.json`。下次翻译相同文本时（无论哪个命名空间），直接从缓存读取，避免重复的网络请求和 API 费用。
 
-- Cache is keyed by original text with target language as sub-key: `{ "text": { "en": "translated" } }`
-- Corrupted or malformed cache files are silently ignored without affecting the normal flow
-- Writes are deferred (`setImmediate`) to avoid blocking the translation pipeline
+- 缓存以原文为键、目标语言为二级键：`{ "text": { "en": "translated" } }`
+- 缓存文件破损或格式错误时自动忽略，不影响正常翻译流程
+- 缓存自动在"空闲时"落盘（`setImmediate` 延迟写入），不阻塞翻译管线
 
-### Unused Translation Cleanup
+### 未使用翻译清理
 
-After replacing Chinese text with `$t()` calls, the tool checks existing locale JSON files and **removes keys that are no longer referenced anywhere in the source code**. This prevents locale files from accumulating stale entries over time.
+替换中文为 `$t()` 调用后，工具会检查现有的语言包 JSON 文件，**移除源文件中不再引用的 key**，防止语言包随时间积累过期条目。
 
-Cleanup runs against the same namespace used for the current translation operation, and only affects keys that have zero references across all scanned source files.
+清理操作仅针对本次翻译操作使用的命名空间，且仅移除在所有扫描源文件中引用数为零的 key。
 
-### Namespace Normalization
+### 命名空间规范化
 
-Existing `$t('oldNamespace.key')` calls in source files are automatically updated to the current namespace name during translation.
+源文件中已有的 `$t('旧命名空间.key')` 调用会在翻译时自动更新为当前命名空间。
 
-### Dry-Run Mode
+### 预览模式（--dry-run）
 
-When `--dry-run` is specified, the tool shows a line-level diff of all changes without actually modifying files. After the preview, it prompts `Apply changes? (y/N)` — entering `y` or `yes` executes the changes, anything else cancels.
+指定 `--dry-run` 时，工具会显示所有变更的行级 diff，但不实际修改文件。预览结束后提示 `Apply changes? (y/N)` — 输入 `y` 或 `yes` 执行变更，其他任何输入取消。
 
-### `i18nCallTemplate` Customization
+### `i18nCallTemplate` 自定义
 
-The `i18nCallTemplate` field controls the i18n function name and call format:
+`i18nCallTemplate` 字段控制国际化函数名和调用格式：
 
-| Template Value               | Generated Output                            |
-| ---------------------------- | ------------------------------------------- |
-| `"$t"` (default)             | `$t('demo.interest')`                       |
-| `"$te"`                      | `$te('demo.interest')`                      |
-| `"{{key}}"`                  | `demo.interest` (raw key, no function call) |
-| `"t('{{key}}')"`             | `t('demo.interest')`                        |
-| `"i18n.global.t('{{key}}')"` | `i18n.global.t('demo.interest')`            |
+| 模板值                       | 生成结果                              |
+| ---------------------------- | ------------------------------------- |
+| `"$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')`      |
 
-When the template **contains** `{{key}}`, it's a template string where `{{key}}` is replaced with `namespace.subKey`. When it does **not** contain `{{key}}`, it wraps as `template('namespace.subKey')`.
+当模板 **包含** `{{key}}` 时，`{{key}}` 会被替换为 `namespace.subKey`；当 **不包含** `{{key}}` 时，包装为 `template('namespace.subKey')`。
 
-### Workflow Tips
+### 工作流建议
 
-- **Always run `--dry-run` first** when trying translation on a new codebase to verify the extraction results
-- **Use `tfo` with a single file's parent folder** for targeted translation: `hias tfo src/views/MyComponent myComp`
-- **Use `--exclude` to skip config or generated files**: `hias tfo src/views views --exclude "**/*.test.js" --exclude node_modules`
-- **Use separate namespaces per module** to keep locale files small and focused. For example, `src/views/user/` → namespace `user`, `src/views/admin/` → namespace `admin`
-- **Run rollback after verifying** if `replaceOriginalFile` was on: `hias rollback`
-- **Multiple rollbacks**: each `rollback` undoes one snapshot. Run repeatedly to go back further
-- **Re-running translation**: existing `$t()` calls are stripped before re-extraction, so running twice is safe and will only add new translations for any remaining Chinese text
+- **首次翻译前务必使用 `--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()` 调用会在重新提取前被剥离，重复运行只会添加剩余中文的翻译
 
 ---
 
-## Global Config
+## 全局配置
 
-The global config file is located at `~/.hias-cli/config.json` and is shared by both the language setting and translation settings:
+全局配置文件位于 `~/.hias-cli/config.json`，语言设置和翻译设置共用此文件：
 
 ```json
 {
@@ -506,28 +520,30 @@ The global config file is located at `~/.hias-cli/config.json` and is shared by
 }
 ```
 
-Managed by:
+由以下命令管理：
 
-- **`hias lang <language>`** — sets `language`
-- **`hias globalsetting`** — creates/updates `translationSetting`
+- **`hias lang <language>`** — 设置 `language`
+- **`hias global-setting`** — 创建/更新 `translationSetting`
+- **`hias clear-config`** — 删除 `~/.hias-cli`
+- **`hias uninstall -g`** — 先执行 `hias clear-config`，再卸载全局包
 
 ---
 
-## All Commands Reference
-
-| Command                 | Alias | Description                               |
-| ----------------------- | ----- | ----------------------------------------- |
-| `create <project>`      | `crt` | Create project from framework template    |
-| `adv <name>`            | –     | Add Vue component                         |
-| `adr <name>`            | –     | Add React JSX component                   |
-| `adrt <name>`           | –     | Add React TSX component                   |
-| `adrd <name>`           | –     | Add Redux JSX store                       |
-| `adrdt <name>`          | –     | Add Redux TSX store                       |
-| `close-port <ports...>` | –     | Kill processes on ports                   |
-| `lang [language]`       | –     | Set or view CLI language                  |
-| `tf [file] [name]`      | –     | Translate a single file                   |
-| `tfo [folder] [name]`   | –     | Translate all files in a folder           |
-| `setting`               | –     | Generate project-level translation config |
-| `globalsetting`         | –     | Generate global translation config        |
-| `gitignore`             | –     | Add `.hias` to `.gitignore`               |
-| `rollback`              | –     | Roll back the last translation operation  |
+## 全部命令一览
+
+| 命令                    | 别名  | 说明                         |
+| ----------------------- | ----- | ---------------------------- |
+| `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`               | –     | 生成项目级翻译配置           |
+| `global-setting`        | –     | 生成全局翻译配置             |
+| `gitignore`             | –     | 添加 `.hias` 到 `.gitignore` |
+| `rollback`              | –     | 回滚上一次翻译操作           |