translate-cli 实战指南：一条命令翻译文件、stdin 和批量 glob

这个技能做什么

一句话：translate-cli 是 OpenClaw 生态里最被低估的生产力技能。它能翻译任意文本、stdin 流、单个文件，或整个目录里 glob 匹配到的文件——支持多 provider、preset 配置、自定义提示词模板，还有 dry-run 校验。

在 SFD 实验室，我们用它每天把文章批量翻译成英文和繁体中文，支撑 smallfiredragon.com 的三语发布。

安装

clawhub install translate-cli

验证安装：

translate --version
# translate-cli v1.x.x

基础用法

翻译文本

# 直接翻译文本
translate "深度学习入门指南"

# 指定目标语言
translate --lang en "深度学习入门指南"
# → Introduction to Deep Learning

stdin 输入

# 管道输入
echo "Context window technology" | translate --lang zh

# 从文件读取
cat article.txt | translate --lang zh-TW > article_tw.txt

翻译单个文件

translate --file ./docs/readme.md --lang en --out ./docs/readme_en.md

批量翻译（glob）

# 翻译目录下所有 markdown 文件
translate --file "./content/*.md" --lang en --out-dir ./content_en/

# 输出：
# ✓ article-1.md → article-1.md (en)
# ✓ article-2.md → article-2.md (en)
# ✓ 12 files translated in 18.3s

Provider 选择

translate-cli 支持多个 AI provider。在 .openclaw/config.toml 里配置：

[translate]
default_provider = "openai"    # openai | anthropic | deepseek | gemini
default_model = "gpt-4o-mini" # 性价比高的默认选择

单条命令临时覆盖：

translate --provider anthropic --model claude-haiku "Hello world"
translate --provider deepseek "Quantum computing basics"

我们的经验之谈：中文技术文档做 zh→en，DeepSeek 处理得最好。en→zh，GPT-4o-mini 的输出更自然。选 provider 要按翻译方向来，别只看价格。

Preset——真正的杀手锏

很多人跳过了这一步。Preset 让你把语言方向、模型、提示词风格固化下来：

# 列出现有 preset
translate presets list

# 创建一个 preset
translate presets add tech-zh-to-en \
  --from zh \
  --to en \
  --provider openai \
  --model gpt-4o \
  --prompt "Translate Chinese technical content to English. Preserve all code blocks, technical terms, and markdown formatting exactly."

# 使用这个 preset
translate --preset tech-zh-to-en --file article.md

SFD 实验室的三个核心 preset：

sfd-zh-to-en：中文技术文章 → 英文，代码块原样保留
sfd-zh-to-tw：简体 → 繁体中文，使用台湾术语
sfd-product：产品文案，保留 SEO 关键词结构

Dry-Run 校验

# 不真翻译，先校验一遍
translate --preset sfd-zh-to-en --file "./content/*.md" --dry-run

# 输出：
# [dry-run] Would translate 12 files
# [dry-run] Provider: openai / gpt-4o
# [dry-run] Estimated tokens: ~45,000
# [dry-run] Estimated cost: ~$0.09

批量任务之前一定要先 dry-run。别等 API 账单给你惊喜。

TOML 配置文件

[settings]
default_lang = "en"
concurrency = 3     # 并行翻译文件数
retry_on_fail = 2   # 失败重试次数

[presets.blog]
from = "zh"
to = "en"
provider = "anthropic"
model = "claude-haiku-3-5"
prompt_template = "./prompts/blog-translation.txt"

[output]
preserve_structure = true
append_lang_suffix = true  # article.md → article_en.md

常见的坑

问题 1：代码块被改坏

原因：默认提示词没强调保留格式。解决：在 preset 提示词里加上 “Preserve all code blocks exactly as-is. Do not translate code or technical identifiers.”

问题 2：繁体中文输出里混进简体字

解决：在提示词里明确写上 “Use Traditional Chinese (Taiwan standard). Do not use Simplified Chinese characters or Mainland China terminology.”

问题 3：批量任务中途停下

原因：API 限流。解决：把 concurrency 从默认 5 降到 2，并在 config.toml 里加 retry_on_fail = 3。

技能组合

translate-cli + summarize：先把长文总结成摘要，再翻译摘要——成本直降 80%
translate-cli + humanizer：翻译完的内容过一遍 humanizer，发布前去 AI 味
translate-cli + smart-web-scraper：抓取外语页面 → 翻译 → 存成中文知识库

SFD 实验室备注

我们用 translate-cli 干三件事：① smallfiredragon.com 的每日三语发布（zh → en + zh-TW）；② 小春蚕处理 BACAKU 时的内容加工（日语/英语 → 中文）；③ 安全文档分析——小猎鹰在审阅前需要把英文审计报告翻译过来。

一个月下来，这个技能每天省下大约 30 分钟的人工翻译。对任何内容驱动的项目来说，都值得长期装着。