project-translator-cli
v0.21.3
Published
Project Translator CLI
Readme
Project Translator CLI
Project Translator 的命令行工具。
安装
npx project-translator-cli --help常用命令
初始化配置与 schema
在目标项目目录执行:
project-translator-cli config init
project-translator-cli config validate --jsonconfig init 默认在当前工作目录创建 project.translation.json 和 project.translation.schema.json,通过 $schema 关联编辑器补全与校验,写入前使用同一份内置 schema 验证模板。已有配置不覆盖;已有相同 schema 可复用,不同内容会报错并保留。模板不读取全局凭据,使用 OPENAI_API_KEY 环境变量引用,翻译映射为空;按实际服务调整供应商、模型并添加映射后再运行翻译。schema 通过仅代表结构合法,不代表服务连接或翻译结果已验证。
# 自定义工作区和配置位置,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 --jsonconfig schema 会创建缺失的父目录,并更新指定输出文件;--json 输出实际 schema 路径。config init 仅初始化项目配置,不操作全局配置,不执行翻译。
翻译与配置操作
npx project-translator-cli translate project --workspace . --config project.translation.json
npx project-translator-cli translate files --workspace . --config project.translation.json --lang zh-cn
npx project-translator-cli config list --workspace . --config project.translation.json --json
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 |
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
