npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

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 --json

config 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 --json

config 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