project-translator-cli 0.20.1 → 0.21.3

package/README.md

@@ -1,14 +1,37 @@
 # Project Translator CLI
 
-CLI for Project Translator.
+Project Translator 的命令行工具。
 
-## Install
+## 安装
 
 ```bash
 npx project-translator-cli --help
 ```
 
-## Common Commands
+## 常用命令
+
+### 初始化配置与 schema
+
+在目标项目目录执行：
+
+```bash
+project-translator-cli config init
+project-translator-cli config validate --json
+```
+
+`config init` 默认在当前工作目录创建 `project.translation.json` 和 `project.translation.schema.json`，通过 `$schema` 关联编辑器补全与校验，写入前使用同一份内置 schema 验证模板。已有配置不覆盖；已有相同 schema 可复用，不同内容会报错并保留。模板不读取全局凭据，使用 `OPENAI_API_KEY` 环境变量引用，翻译映射为空；按实际服务调整供应商、模型并添加映射后再运行翻译。schema 通过仅代表结构合法，不代表服务连接或翻译结果已验证。
+
+```bash
+# 自定义工作区和配置位置，schema 生成在配置旁边
+project-translator-cli config init --workspace ./my-project --config config/translation.json --json
+
+# 单独导出完整 schema，不需要项目配置；相对路径基于 workspace（默认为当前目录）
+project-translator-cli config schema --out schemas/project.translation.schema.json --json
+```
+
+`config schema` 会创建缺失的父目录，并更新指定输出文件；`--json` 输出实际 schema 路径。`config init` 仅初始化项目配置，不操作全局配置，不执行翻译。
+
+### 翻译与配置操作
 
 ```bash
 npx project-translator-cli translate project --workspace . --config project.translation.json
@@ -17,4 +40,63 @@ npx project-translator-cli config list --workspace . --config project.translatio
 npx project-translator-cli config validate --workspace . --config project.translation.json
 ```
 
+## 缓存与重译判断
+
+语言码在运行时统一为小写连字符形式，例如 `pt-BR`、`PT_BR` 和 `pt-br` 均视为 `pt-br`；`--lang` 采用相同规则，配置中的文件路径保持原样。
+
+缓存只读取工作区的标准小写文件，例如 `.translation-cache/translations_pt_br.json`，不扫描、合并历史文件或生成迁移备份。旧文件名需在翻译任务停止后一次性改为标准名；标准文件已存在时先核对内容，避免覆盖新记录。标准缓存采用临时文件加重命名写入。损坏缓存会报错并停止相应流程，不静默当成空缓存重译。
+
+`translationIntervalDays: -1` 或 `0` 仅关闭到期重译。目标缺失、无缓存记录或源内容变化仍需要处理；正数间隔到期时，即使源未变化也会重新处理。
+
+文本摘要和 JSON 结果的 `cacheDecisionReasons` 按数据库判定次数统计：
+
+| 原因 | 含义 |
+| --- | --- |
+| `hash_match` / `stat_match` | 缓存命中，源未变化，跳过 |
+| `target_missing` | 目标文件不存在或不是文件 |
+| `record_missing` | 当前语言缺少源文件记录 |
+| `processing_kind_changed` | 当前处理方式与历史明确记录的 `processing_kind` 不同，需要重新处理 |
+| `draft_target_preserved` | 命中草稿跳过规则且目标已存在，保留目标及原历史 |
+| `source_changed` | 源文件哈希改变 |
+| `interval_elapsed` | 正数间隔已到期 |
+| `error` | 判定过程出错，停止处理 |
+
+这些是文件处理决策，不是 API 调用次数；草稿、二进制和仅复制规则还会进一步决定是否翻译。扫描日志 `Checking file` 不代表已调用翻译服务。
+
+历史记录的 `processing_kind` 区分 `translated`、`draft_copy`、`copy_only` 和 `binary_copy`。成功且结果有效的翻译即使与源文相同也会更新历史。旧缓存缺少该字段时视为状态未知，不推断为 `translated`，也不因此触发重新处理；目标存在时仍按源哈希和间隔判断（`-1`/`0` 关闭到期重译）。仅已有明确状态与当前处理方式不同时才产生 `processing_kind_changed`。
+
+命中草稿跳过规则时，已有目标始终保持原样，不修改其历史、时间或状态，即使源文变化或间隔到期也不覆盖。目标缺失时才独占创建源文副本并记录 `draft_copy`。仅复制和二进制处理保留原有同步行为。这里的 `translate_datetime` 对复制状态表示处理完成时间，不表示完成了语言翻译。
+
+失败、取消、非法返回码以及非空源文对应的空最终响应不会登记成功。流式和分块模式同样要求完整、有效的最终结果；仅收到部分片段不算成功。历史缺失不会通过扫描伪造成功记录，下次实际处理完成时才补记。
+
+## 中断翻译
+
+按 Ctrl+C 会请求取消，在处理链观察到取消信号后完成收尾并输出摘要，退出码为 `130`。主动取消不作为文件翻译失败打印堆栈或累计失败数；此前完成的文件、跳过数、失败数和已累计 Token 保留，数据库关闭时刷入待保存历史。未完成的文件不记成功。取消是协作式的，等待网络响应期间不保证立即退出。
+
+## 全局配置
+
+供应商、密钥和默认参数可以放在专有配置目录，供所有项目共用。项目里的 `project.translation.json` 继续保存文件和文件夹映射。
+
+| 项 | 位置 |
+| --- | --- |
+| 默认目录 | `~/.project-translator` |
+| 配置文件 | `~/.project-translator/config.json` |
+| 覆盖目录 | 环境变量 `PROJECT_TRANSLATOR_CONFIG_DIR` |
+
+```bash
+npx project-translator-cli config path
+npx project-translator-cli config set currentVendor cliproxyapi --global
+npx project-translator-cli config set vendors '[{"name":"cliproxyapi","apiEndpoint":"http://127.0.0.1:9/v1","model":"demo"}]' --type json --global
+npx project-translator-cli config list --effective --json
+```
+
+翻译始终使用合并后的有效配置：
+
+- 项目配置覆盖同名全局字段。
+- `vendors` 按名称合并。项目里的字段覆盖同名全局 vendor，未列出的全局 vendor 仍然可用。
+- 项目配置文件存在时，`specifiedFiles` 和 `specifiedFolders` 只取项目配置。
+- 项目配置文件不存在时，有效配置就是全局配置。
+
+`--global` 只读写专有目录中的全局配置。`--effective` 只用于读取合并结果，不能用于 `set`、`add`、`remove`。
+
 Repository: `https://github.com/Project-Translation/project_translator`