TransX CLI — DLX 翻译工具

面向终端、脚本和 Agent 的 DLX 翻译工具。

感谢 LINUX DO 社区，没有始皇的福利就没有这个CLI

文档站：https://gusheng107.github.io/transx-cli/

写在最前

非官方项目。 本项目不提供 API Key 或翻译服务。

平台

• Windows 10/11（PowerShell / CMD / Windows Terminal）
• macOS（Apple Silicon 与 Intel，zsh / bash）
• Linux（x64 / arm64，bash / zsh）

需要 Node.js > 22。

安装

npx @gushengcode/transx-cli@latest install

这会把 transx 装到用户目录，并把启动入口加进 PATH：

Windows：    %LOCALAPPDATA%\.transx\bin\transx.cmd
macOS/Linux：~/.transx/bin/transx
配置目录：    ~/.transx/

重新打开终端后，直接运行 transx 进入交互界面，或查看完整帮助：

transx help

AI Agent Skill

仓库提供 transx-translate Skill，可选择 Python 脚本、Node.js 脚本或 TransX CLI。三种方式支持相同的文本与文件翻译，并共用 ~/.transx/history/。

推荐通过 Skills CLI 全局安装：

npx skills add GuSheng107/transx-cli --skill transx-translate -g

首次使用时，Agent 会检测本机环境并让用户选择一种调用方式；之后本地 SKILL.md 会精简为对应流程。切换模式只修改 Skill 文档和偏好，不会删除附带脚本或卸载 CLI。

脚本依赖使用固定版本：

python -m pip install -r ./skills/transx-translate/requirements.txt
npm ci --omit=dev --prefix ./skills/transx-translate

也可以在文档站 Skills 页面下载 ZIP 手动安装。

配置 API Key

在 Linux.do Connect 获取 DLX API Key，然后初始化：

transx init

Key 是隐藏输入的，保存在 ~/.transx/credentials.json，源码、npm 包和日志里都不会出现你的 Key。

非交互环境（比如 CI）可以从 stdin 传：

printf '%s' "$DLX_API_KEY" | transx init --key-stdin

也可以临时用环境变量 DLX_API_KEY 覆盖本地配置，不写盘。

翻译

给 AI Agent 调用时建议始终带 --json：

transx translate "Hello world" --to ZH --json

从 stdin 读：

echo "Hello world" | transx translate --to ZH --json

翻译文件：

transx translate --file ./readme.md --to ZH --json
transx translate --file ./report.docx --to ZH
transx translate --file ./paper.pdf --to ZH --timeout 60

支持 txt、md、csv、log、docx、xlsx、pptx、pdf。译文默认写入源文件目录，文件名为 <源文件名>_<目标语言>；PDF 输出 DOCX。无法创建文件时返回文本或 JSON。

单条文本上限 1500 字符。文件上限 20MB、可翻译文本上限 100000 字符、最多 500 次请求。文件按段落、同格式文字或单元格分批请求，并输出进度。

完整参数：

-t, --to <lang>              目标语言（必填）
-s, --source <lang>          源语言，默认 auto
-f, --file <path>            从文件提取文本翻译（与位置文本互斥）
-o, --output <path>          指定译文文件路径
    --json                   输出 AI 友好的 JSON
    --timeout <seconds>      本次请求超时

成功输出：

{"ok":true,"data":"你好，世界","source_lang":"auto","target_lang":"ZH","provider":"dlx"}

失败走 stderr，非零退出码，方便脚本捕获：

{"ok":false,"error":{"code":"CONFIG_NOT_INITIALIZED","message":"缺少 DLX API Key，请先运行 transx init"}}

查看支持的语言代码（不需要联网或初始化）：

transx languages
transx languages --json

DLX 接口支持 31 个目标语言代码。中文使用 ZH（简体）或 ZH-HANT（繁体）；源语言可使用 AUTO。

翻译历史

每条成功的翻译都会落到本地历史，不记录 URL 和 API Key。历史按中国时间拆分到 YYYY-MM-DD.json，时间格式 YYYY-MM-DD HH:mm:ss.SSS。

transx history                         # 最近 20 条
transx history --limit 50 --offset 100
transx history --from "2026-08-01" --to "2026-08-03"
transx history --since 7d --json

搜索文本原文/译文或文件记录中的源文件名/译文文件名：

transx history search "环境审查" --json

查看文件状态、清理：

transx history status
transx history clear --oldest 100
transx history clear --keep 1000
transx history clear --older-than 30d --yes
transx history clear --from "2026-07-01" --to "2026-07-31" --yes
transx history clear --all --yes

查看历史命令自身的帮助：

transx history help

文件翻译历史只保存源文件和译文文件的路径、文件名，不保存文件正文。历史目录 ~/.transx/history/，含 index.json 和按日期拆分的文件。

配置

transx config                  # 查看 URL 模板和完整 API Key
transx config set-key          # 重新输入 Key（隐藏）
transx config set-key --stdin  # 从 stdin 读 Key
transx config reset key        # 删掉 Key
transx config reset all        # 重置全部

transx config 会显示完整 API Key，但不会显示拼接后的请求 URL。

版本与更新

transx version          # 当前版本
transx version --check  # 对比 npm 上的最新版
transx update           # 拉最新版并重新安装

update 走 npm Registry 拉最新版，原子替换启动入口；旧版本目录会保留，方便排查或回退。

隐私和安全

• 待翻译内容会发送到 DLX 服务。
• API Key 存在 ~/.transx/credentials.json，POSIX 系统文件权限 0600。
• 不收集任何遥测。
• API Key 不会编译进程序。

开发

npm install
npm run check    # 类型检查
npm test         # 测试
npm run build    # 编译到 dist/
npm pack --dry-run

要求 Node.js > 22。每次提交会在 Windows、macOS、Linux 三系统跑类型检查、构建和打包检查。

许可

MIT License。

友情链接

• LINUX DO