日常写 UI 文案、需求说明、Issue 或技术文档时，真正麻烦的往往不是查到一个单词，而是确认一句话在当前场景里应该怎么说。例如“箭头方向需要切换”可能是图标方向要反转，也可能是展开和收起时箭头要随状态改变。直译不一定错，但很容易不自然。

humar 是一个用 Rust 写的命令行翻译记忆工具。它面向中英短语工作流：调用兼容 Responses API 的模型生成场景化翻译卡片，把成功结果保存到本地词库，之后可以检索、回看和复习，而不是每次都从零开始问模型。

它解决的不是一次翻译

普通翻译工具的流程是“输入一句话，得到一句话”。但在开发和产品协作里，同类表达会反复出现：

  • UI 状态、按钮和提示语
  • 设计反馈和修改意见
  • 技术文档、Issue 与代码注释
  • 中英双语沟通中的固定表达

这些表达通常不止一种译法，语气和上下文也会影响选择。humar 将一次翻译保存为一张结构化卡片，其中包括：

  • 推荐译法
  • 不同场景下的备选译法与说明
  • 容易混淆的术语提醒
  • 中英例句
  • 可直接复用的短语

这样翻译结果不只是一次性聊天记录，而是可以逐步积累的个人术语库。

安装与配置

humar 0.2.1 是一个二进制 crate，可以直接安装：

cargo install humar

翻译功能需要配置一个兼容 Responses API 的网关。当前 provider 为 openai-compatible，也是默认值。可以把密钥放在环境变量中，再配置网关地址和模型：

export HUMAR_API_KEY="your-api-key"

humar config base-url "https://your-gateway.example"
humar config model "your-model"

也可以使用 humar config api-key <api-key> 保存密钥。环境变量 HUMAR_API_KEY 的优先级更高，适合不想把密钥写入本地配置文件的场景。需要注意：如果该环境变量被显式设为空值，程序会报错，而不会悄悄回退到已保存的密钥。

第一次在交互式终端中翻译、且配置尚不完整时，humar 会依次询问 provider、API key、model 和 base URL，并写入本地 config.json。

翻译一条工作用语

配置完成后，直接把短语作为参数传入：

humar "箭头方向需要切换"

输出会以推荐译法为主，再给出适合设计反馈、交互行为、技术文档或按钮文案等场景的表达，并补充术语和例句。例如这里会区分：

  • 方向本身不对，需要改成相反方向时，reverse 或 flip 更合适；
  • 两种 UI 状态之间来回变化时，toggle 更准确；
  • 如果描述的是状态驱动的表现，change based on the state 更明确。

默认情况下，翻译成功后会自动保存。只想临时查一次时可以加 --no-save：

humar --no-save "适配夜间主题"

这条命令不会写入词库。

本地词库：保存、浏览和回看

每个保存的词条都有 UUID、原文、翻译方向、完整翻译卡片、创建时间和复习统计。数据以本地 JSONL 文件保存，不依赖远程账户或数据库。

常用命令如下：

# 浏览词库；交互式终端会选择词条并展示详情
humar list

# 按 ID 再次查看完整翻译卡片和复习统计
humar show <id>

# 手动加入已有的术语对，不调用模型
humar add \
  --source "夜间主题" \
  --target "dark mode" \
  --source-lang zh \
  --target-lang en

手动添加适合已经有团队术语表、产品文案规范或固定译法的项目。这样常用词不用重复调用 API，也可以和模型生成的翻译放在同一个词库里。

game：把词库变成复习题

词库积累到一定数量后，humar game 会在终端中生成练习：

humar game

当前版本会从词条中生成几种题型：

  • 中文写英文
  • 英文写中文
  • 根据场景选择更合适的译法
  • 根据术语提醒进行判断

复习记录会保存已见次数、答对次数、答错次数和最近复习时间。出错更多的词条会优先进入后续题目，因此它更接近一个轻量的错题本，而不只是随机抽词。

模型输出与数据边界

humar 不把模型返回的自然语言直接当作词库内容。它要求 Responses API 返回可解析的结构化翻译卡片，并校验推荐译法、场景翻译、例句和短语等必填内容。响应不符合结构时会返回明确错误，不会写入不完整词条。

另一边，待翻译文本会发送到你配置的 API 网关。因此不要把密钥、未公开客户资料或其他敏感内容直接作为翻译文本；网关的日志、数据保留和合规策略需要由使用者自行确认。

适合谁

humar 适合需要频繁处理短句和术语、又希望把结果长期积累下来的开发者、设计师、产品经理和技术写作者。它不是通用长文档翻译器，也不尝试替代人工语言判断；它把“问模型得到建议”“选择合适表达”“保存以后复习”连成了一个终端工作流。

对于 Rust CLI 项目来说，它的实现也很直接：clap 处理命令行，reqwest 调用网关，serde 写入 JSONL，终端交互使用 dialoguer。没有额外服务端，数据和配置都留在本机，方便从一个小工具开始形成自己的表达记忆库。

项目地址：humar on crates.io

参考：