@ansstory/hias 1.0.6 → 1.0.8

package/README.en-US.md

@@ -0,0 +1,551 @@
+# hias-cli
+
+> Personal scaffolding CLI with built-in i18n translation toolkit.
+
+## Install
+
+```sh
+npm i @ansstory/hias -g
+```
+
+## Usage
+
+```
+hias <command> [options]
+```
+
+---
+
+## Quick Start (i18n Translation)
+
+### 1. Set up API credentials
+
+Register a translation provider and create a config file in your project:
+
+```sh
+hias setting
+```
+
+Edit `.hias/setting.json` with your `appId` and `secretKey`:
+
+```json
+{
+  "translationSetting": {
+    "appId": "your_app_id",
+    "secretKey": "your_secret_key",
+    "provider": "baidu"
+  }
+}
+```
+
+> **No API key?** Leave both empty for fallback mode — Chinese text is used as keys directly. The i18n migration still completes.
+
+### 2. Preview changes (recommended)
+
+```sh
+hias tfo src/views myNamespace --dry-run
+```
+
+Shows a line-level diff and prompts `Apply changes? (y/N)`.
+
+### 3. Apply translation
+
+```sh
+hias tfo src/views myNamespace
+```
+
+Locale files are written to `.hias/lang/myNamespace/`. If `replaceOriginalFile` is `true`, source files are overwritten in place.
+
+---
+
+## Commands
+
+### `create <project>` (alias: `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>/`.
+
+```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   |
+
+---
+
+### `adv <name> [options]`
+
+Add a Vue component file.
+
+```sh
+hias adv Demo -d src/components
+hias adv index -d src/views/demo
+```
+
+### `adr <name> [options]`
+
+Add a React JSX component file.
+
+```sh
+hias adr Demo -d src/components
+```
+
+### `adrt <name> [options]`
+
+Add a React TSX component file.
+
+```sh
+hias adrt Demo -d src/components
+```
+
+### `adrd <name> [options]`
+
+Add a Redux JSX store file.
+
+```sh
+hias adrd useDemoStore -d src/store/modules
+```
+
+### `adrdt <name> [options]`
+
+Add a Redux TSX store file.
+
+```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. |
+
+If `name` is `index`, the component file is named after the parent folder instead.
+
+---
+
+### `close-port <ports...>`
+
+Kill processes occupying one or more ports.
+
+```sh
+hias close-port 8076 8077
+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`).
+
+---
+
+### `lang [language]`
+
+Set or view the CLI language.
+
+```sh
+hias lang zh-CN
+hias lang en
+hias lang -l           # show current language
+```
+
+| Option       | Description                           |
+| ------------ | ------------------------------------- |
+| `-l, --list` | Display the currently active language |
+
+Supported languages: `en`, `zh-CN`.
+
+Language preference is stored in `~/.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.
+
+#### `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 |
+
+**Supported file types:** `.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       |
+
+#### `setting`
+
+Generate a project-level translation config file.
+
+```sh
+hias setting
+```
+
+Creates `.hias/setting.json` in the current project directory.
+
+#### `global-setting`
+
+Generate a global translation config file.
+
+```sh
+hias global-setting
+```
+
+Creates or updates `~/.hias-cli/config.json`. Preserves any existing `language` setting.
+
+#### `clear-config`
+
+Remove the global config directory `~/.hias-cli`.
+
+```sh
+hias clear-config
+```
+
+To fully uninstall the CLI and remove user config, run:
+
+```sh
+hias uninstall -g
+```
+
+This command first runs `hias clear-config`, then runs `npm uninstall @ansstory/hias -g`. npm v7+ no longer runs the old `preuninstall` / `postuninstall` lifecycle scripts during package removal, so `npm uninstall` alone will not delete config files in the home directory.
+
+#### `gitignore`
+
+Add `.hias` to the project's `.gitignore` file. Creates `.gitignore` if it doesn't exist, or appends the entry if it already exists.
+
+```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.
+
+```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
+```
+
+**Behavior:** When `replaceOriginalFile` was `true`, original source files are restored; when it was `false`, only the output directory `.hias/lang/<name>/` is removed.
+
+**`--keep` behavior:** Backups are sorted by directory name (timestamp), the oldest ones are removed until only N remain. No action if total backups ≤ 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 |
+
+---
+
+## 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 global-setting`)
+3. **Defaults** — hardcoded defaults (shown below)
+
+### Setting File Format
+
+```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": ""
+  }
+}
+```
+
+### 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                                                                                                                                                                  |
+
+### Translation Providers
+
+| Provider          | `provider` value | `appId`          | `secretKey`       |
+| ----------------- | ---------------- | ---------------- | ----------------- |
+| Baidu Translate   | `"baidu"`        | Baidu AppId      | Baidu SecretKey   |
+| Tencent Cloud TMT | `"tencent"`      | Tencent SecretId | Tencent 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).
+
+> **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.
+
+### 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
+
+#### Tencent Cloud 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
+
+---
+
+## Output Structure
+
+After translation, the following directory structure is created (assuming `locales: ["zh-CN", "en-US", "ja-JP"]`):
+
+```
+.hias/
+├── setting.json              # project-level config
+├── 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)
+└── .langbackup/
+    └── <timestamp>_<namespace>/
+        └── <file>.vue.bak    # original file backup
+```
+
+Locale files use a nested `{ namespace: { key: value } }` format, making them ready for use with `vue-i18n` or similar libraries via module registration.
+
+---
+
+## 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
+
+Comments (`//`, `/* */`, `<!-- -->`) are correctly skipped. `data-*` and `aria-*` attributes are excluded.
+
+### 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)  |
+
+### Locale File Format
+
+**When translation succeeds** (English-based keys, truncated to 40 characters):
+
+```json
+// zh-CN.json
+{ "demo": { "interest": "兴趣", "test": "测试" } }
+// en-US.json
+{ "demo": { "interest": "interest", "test": "test" } }
+// ja-JP.json (if locales includes ja-JP)
+{ "demo": { "interest": "興味", "test": "テスト" } }
+```
+
+**When translation fails** (auto-generated short keys from Chinese, truncated to 40 characters):
+
+```json
+// zh-CN.json and en-US.json
+{ "demo": { "提起妈妈的手_一股酸痛便涌上心头": "提起妈妈的手，一股酸痛便涌上心头...", "test": "测试" } }
+```
+
+### Key Generation Rules
+
+| 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   |
+
+Keys are deduplicated: if two texts produce the same truncated key, `_1`, `_2`, etc. are appended.
+
+### Translation API Fallback Warning
+
+When the translation API call fails (network error, invalid credentials, or rate limit), the tool logs a warning message to the console, e.g.:
+
+```
+⚠ 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.
+
+> **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.
+
+### 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.
+
+- 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
+
+### 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.
+
+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.
+
+### Namespace Normalization
+
+Existing `$t('oldNamespace.key')` calls in source files are automatically updated to the current namespace name during translation.
+
+### Dry-Run Mode
+
+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.
+
+### `i18nCallTemplate` Customization
+
+The `i18nCallTemplate` field controls the i18n function name and call format:
+
+| 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')`            |
+
+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')`.
+
+### 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
+
+---
+
+## Global Config
+
+The global config file is located at `~/.hias-cli/config.json` and is shared by both the language setting and translation settings:
+
+```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": ""
+  }
+}
+```
+
+Managed by:
+
+- **`hias lang <language>`** — sets `language`
+- **`hias global-setting`** — creates/updates `translationSetting`
+- **`hias clear-config`** — removes `~/.hias-cli`
+- **`hias uninstall -g`** — runs `hias clear-config`, then uninstalls the global package
+
+---
+
+## 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 |
+| `global-setting`        | –     | Generate global translation config        |
+| `gitignore`             | –     | Add `.hias` to `.gitignore`               |
+| `rollback`              | –     | Roll back the last translation operation  |