内容
# 双语内容同步代理
**英文** | [中文](README.zh-CN.md)
> 独立创始人操作系统代理 #4 — 保持 `en.json` 和 `zh.json`（或任何语言对）同步。差异检测，通过 Claude 翻译缺失的键，队列中以 markdown 审查文件，应用已批准的编辑返回到本地 JSON。绝不未经人工批准自动写入。
[](LICENSE)
[](https://pypi.org/project/bilingual-content-sync-agent/)
[](#)
[](https://anthropic.com)
由 [Alex Ji](https://github.com/alex-jb) 为 [VibeXForge](https://github.com/alex-jb/vibex) 的 925 个英中 i18n 字符串而建。源于这个想法：
> *每个功能首先发布英文版本。中文本通常几天或几周后才跟上。跟踪哪些键已经过时是人工劳动，我在凌晨 1 点做这件事。其他 11 位创始人也一样。*
## 它能做什么
```
en.json + zh.json
↓
差异检测（查找英文中存在的键，在中文中缺失/为空/重复）
↓
通过 Claude Sonnet 翻译（内置 vibex-tone 词汇表）
↓
队列/待处理/<时间戳>-review.md
↓
创始人使用 Obsidian 编辑，移动到队列/已批准/
↓
应用 → 写回 zh.json（保留嵌套 + 键顺序）
```
## 命令行界面
```bash
# 覆盖率报告
bilingual-sync stats --en locales/en.json --zh locales/zh.json
# 显示缺失的内容（不调用大型语言模型）
bilingual-sync diff --en locales/en.json --zh locales/zh.json
# 翻译 + 编写审查文件（调用大型语言模型）
bilingual-sync draft \
--en locales/en.json \
--zh locales/zh.json \
--glossary glossary.json \
--tone "独立软件，游戏化，霓虹像素，对等"
# 人工审查后 → 将文件移动到队列/已批准/，然后：
bilingual-sync apply --en locales/en.json --zh locales/zh.json
```
## 词汇表文件
词汇表键强制一致翻译品牌术语。没有它，Claude 会选择合理的默认值，但这些默认值在不同运行中可能会有所不同。
```json
{
"Forge": "锻造",
"Dojo": "道场",
"Vibe": "氛围",
"Login": "登录",
"Sign up": "注册"
}
```
## 什么被标记为“缺失”
当 ZH 中缺少某个键时，会被标记为缺失：
- 该键在 `zh.json` 中不存在
- ZH 值为空字符串
- ZH 值与 EN 值字节相等（常见的复制粘贴错误 — 容易忽略，没有工具）
## 设计选择
- **人工审查不可或缺。** UI 字符串每个用户每次会话都会看到。一次糟糕的翻译影响所有用户，远比五天的补齐要糟糕。该代理绝不会在没有明确批准和应用步骤的情况下写入 `zh.json`。
- **默认 Sonnet，而不是 Haiku。** 冷 UI 翻译正是 naive Haiku 输出过于直译的任务（“Login” → “登入” 而不是 “登录”）。Sonnet 的细微差别值得花费 3 倍的成本，适用于 925 个字符串（~$0.50 总计）。
- **批量调用。** 每次调用 50 个键是 token 预算的最佳选择。完整的 vibex 目录 = ~20 次调用 = ~$0.50。
- **保留占位符 + HTML。** 系统明确禁止翻译 `{name}`、`<span>`、ICU 模式。如果 Claude 破坏了这一点，审查文件中会标记出来。
- **构建在 solo-founder-os 上。** AnthropicClient 处理优雅的降级 + 自动将 token 使用记录到 `~/.bilingual-content-sync-agent/usage.jsonl`（成本审计代理每月会读取它）。
## 路线图
- [x] **v0.1** — 差异检测/草稿/应用/统计 CLI · 人工审查队列 · Sonnet 草稿 · 43 个测试 · 优雅降级
- [ ] **v0.2** — 多语言支持（EN→ES，EN→JA 等）— 相同的代码路径，不同的词汇表
- [ ] **v0.3** — 监视模式：提交时重新运行，标记过时的键到 GitHub PR
- [ ] **v0.4** — 上下文预览：显示键在 React 组件中出现的位置
- [ ] **v0.5** — 反向同步：检测 ZH 独有孤立键（已删除的功能，但 ZH 被遗忘）
## MCP 服务器（Claude Desktop / Cursor / Zed）
从 AI 助手翻译缺失的 i18n 键。
```bash
pip install 'bilingual-content-sync-agent[mcp]'
```
```json
{
"mcpServers": {
"bilingual-sync": {
"command": "bilingual-sync-mcp",
"env": { "ANTHROPIC_API_KEY": "..." }
}
}
}
```
工具：`diff_locales(en, zh)` · `translate_missing(en, zh, ...)` · `apply_approved(en, zh)`
## 许可证
MIT。
## 🧩 [Solo Founder OS](https://github.com/alex-jb/solo-founder-os) 栈的一部分
一个不断增长的 MIT 许可代理集合，共享 `solo-founder-os` 作为其基础 — cron、eval、reflexion、AnthropicClient、人工审查队列、通知器。每个代理都独立有用；它们一起覆盖了整个单人公司工作流程。
🌐 整个栈在 [vibexforge.com](https://vibexforge.com) 上已投入生产。
| 代理 | 功能 |
|---|---|
| [solo-founder-os](https://github.com/alex-jb/solo-founder-os) | 共享基础库（cron · eval · reflexion · 技能库 · DGM-lite）。其他代理都依赖于它。 |
| [build-quality-agent](https://github.com/alex-jb/build-quality-agent) | 预推送 Claude 差异审查器 + 本地构建运行器 — 在发布前捕获可能导致 CI 失败的更改。 |
| [customer-discovery-agent](https://github.com/alex-jb/customer-discovery-agent) | Reddit 痛点爬虫 + Claude 聚类，用于产品验证。 |
| [funnel-analytics-agent](https://github.com/alex-jb/funnel-analytics-agent) | 每日创始人简报 + 9 个来源的实时 PH-day 警报。 |
| [orallexa-marketing-agent](https://github.com/alex-jb/orallexa-marketing-agent) | AI 营销代理 — 提交项目一次，获取 X / Reddit / HN / Dev.to / 小红书 + 7 个平台的原生帖子。支持 [vibexforge.com](https://vibexforge.com)。 |
| [vc-outreach-agent](https://github.com/alex-jb/vc-outreach-agent) | 冷邮件草稿 — 投资者（vc 模式）或付费客户（客户模式，v0.9.0 中与客户 outreach 合并）。人工审查队列 + SMTP 发送器。 |
| [cost-audit-agent](https://github.com/alex-jb/cost-audit-agent) | 6 个提供商（Vercel / Anthropic / OpenPanel / HyperDX / Supabase / GitHub Actions）的月度账单审计，带有美元标记的浪费发现。 |
| [customer-support-agent](https://github.com/alex-jb/customer-support-agent) | 分类用户消息 → 自动草稿回复 → 人工审查队列。关闭 L5 客户支持层。 |
| [payments-agent](https://github.com/alex-jb/payments-agent) | 过期发票提醒草稿。Stripe 形状的类型 + MockProvider 备用 + 严格的货币安全提示规则。 |
*每个代理的单独行在其 README 中省略。安装您需要的代理 — `pip install <agent-name>`。*
