Jta - JSON 翻译智能体

English | 简体中文

AI 驱动的智能体式 JSON 翻译工具，具备智能质量优化功能

Jta 是一个生产级的命令行工具，使用 AI 翻译 JSON 国际化文件，具有卓越的准确性和一致性。遵循 Andrew Ng 的翻译智能体方法论，它具备真正的智能体反思机制（翻译 → 反思 → 改进）、自动术语检测和强大的格式保护功能，适用于生产级翻译。

✨ 核心特性

🤖 智能体翻译与自我优化

• 真正的智能体反思：遵循 Andrew Ng 的翻译智能体方法，采用两步反思机制
• LLM 驱动的质量评估：AI 从 4 个维度评估翻译：准确性、流畅性、风格、术语
• 专家建议：LLM 生成建设性的批评和改进建议
• 迭代改进：AI 基于自己的专家反馈优化翻译
• 成本：每批次 3 次 API 调用（翻译 → 反思 → 改进），以获得最高质量

📚 智能术语管理

• 自动检测：使用 LLM 识别内容中的重要术语
• 保留术语：品牌名称、技术术语等永不翻译
• 一致术语：领域特定术语在所有内容中统一翻译
• 可编辑词典：保存到 .jta-terminology.json，支持手动优化

🔒 强大的格式保护

自动保护： - 占位符：{variable}、{{count}}、%s、%(name)d - HTML 标签：<b>、<span class="highlight">、<a href="https://github.com/ckanner/jta/raw/v1.1.0/"> - URL：https://example.com、http://api.example.com/v1 - Markdown：**粗体**、*斜体*、[链接](url)

⚡ 智能增量翻译

• 仅翻译新增或修改的内容
• 保留现有的高质量翻译
• 自动移除过时的键
• 节省时间和 API 成本（更新时通常可减少 80-90%）

🎯 灵活的键过滤

• 通配符模式：settings.*、user.**、*.title
• 精确控制：包含或排除特定部分
• 递归通配符：使用 ** 翻译整个子部分

🌍 RTL 语言支持

• 阿拉伯语、希伯来语、波斯语、乌尔都语的双向文本处理
• RTL 上下文中 LTR 内容的自动方向标记
• 阿拉伯文字语言的智能标点转换

🚀 生产级性能

• 可配置并发的批处理
• 指数退避的重试逻辑
• 优雅的错误处理和恢复
• 进度指示器和详细统计

🎨 多提供商支持

• OpenAI：所有模型，包括 GPT-5、GPT-5 mini、GPT-5 nano、GPT-4o 等
• Anthropic：所有 Claude 模型，包括 Claude Sonnet 4.5、Claude Haiku 4.5、Claude Opus 4.1 等
• Gemini：所有 Gemini 模型，包括 Gemini 2.5 Flash、Gemini 2.5 Pro 等

📦 安装

Homebrew（macOS/Linux）- 推荐

在 macOS 或 Linux 上安装 Jta 最简单的方法：

# 添加 tap
brew tap hikanner/jta

# 安装 Jta
brew install jta

# 验证安装
jta --version

升级：

brew upgrade jta

卸载：

brew uninstall jta
brew untap hikanner/jta

下载二进制文件

从 GitHub Releases 下载适合您平台的最新版本：

• macOS：jta-darwin-amd64 或 jta-darwin-arm64（Apple Silicon）
• Linux：jta-linux-amd64 或 jta-linux-arm64
• Windows：jta-windows-amd64.exe

# macOS/Linux 示例
curl -L https://github.com/hikanner/jta/releases/latest/download/jta-darwin-arm64 -o jta
chmod +x jta
sudo mv jta /usr/local/bin/

使用 Go Install

go install github.com/hikanner/jta/cmd/jta@latest

从源码构建

git clone https://github.com/hikanner/jta.git
cd jta
go build -o jta cmd/jta/main.go

🚀 快速开始

安装

# 通过 Homebrew 安装（macOS/Linux 推荐）
brew tap hikanner/jta
brew install jta

# 或从 GitHub Releases 下载二进制文件
# 详见安装部分

查看支持的语言

# 列出所有支持的语言
jta --list-languages

基本用法

# 翻译为单一语言
jta en.json --to zh

# 翻译为多种语言
jta en.json --to zh,ja,ko

# 指定输出目录
jta en.json --to zh --output ./locales/

配置 AI 提供商

# 使用环境变量（推荐）
export OPENAI_API_KEY=sk-...
jta en.json --to zh

# 或直接指定
jta en.json --to zh --provider anthropic --api-key sk-ant-...

高级用法

# 增量翻译（仅翻译新增/修改的内容）
jta en.json --to zh --incremental

# 跳过术语检测（使用现有术语）
jta en.json --to zh --skip-terminology

# 完全禁用术语管理
jta en.json --to zh --no-terminology

# 重新检测术语（源语言更改时）
jta zh.json --to en --redetect-terms

# 仅翻译特定键
jta en.json --to zh --keys "settings.*,user.*"

# 排除某些键
jta en.json --to zh --exclude-keys "admin.*,internal.*"

# 非交互模式（用于 CI/CD）
jta en.json --to zh,ja,ko -y

# CI/CD 中的增量翻译
jta en.json --to zh --incremental -y

📖 文档

术语管理

Jta 自动检测源文件中的重要术语并确保翻译一致：

• 保留术语：品牌名称、技术术语等永不翻译（例如：API、OAuth、GitHub）
• 一致术语：必须统一翻译的领域术语（例如：credits、workspace、premium）

文件结构：

术语存储在专用目录中（默认为 .jta/）：

.jta/
├── terminology.json       # 术语定义（源语言）
├── terminology.zh.json    # 中文翻译
├── terminology.ja.json    # 日文翻译
└── terminology.ko.json    # 韩文翻译

terminology.json（源语言术语）：

{
  "version": "1.0",
  "sourceLanguage": "en",
  "detectedAt": "2025-01-26T10:30:00Z",
  "preserveTerms": ["API", "OAuth", "JSON"],
  "consistentTerms": ["credits", "workspace", "prompt"]
}

terminology.zh.json（翻译）：

{
  "version": "1.0",
  "sourceLanguage": "en",
  "targetLanguage": "zh",
  "translatedAt": "2025-01-26T10:31:00Z",
  "translations": {
    "credits": "积分",
    "workspace": "工作空间",
    "prompt": "提示词"
  }
}

工作流程： 1. 首次运行：检测术语 → 保存到 terminology.json → 翻译为目标语言 2. 后续运行：加载现有术语 → 仅翻译缺失的术语 3. 新语言：使用现有的 terminology.json → 创建 terminology.{lang}.json

自定义术语目录：

# 使用共享术语目录
jta en.json --to zh --terminology-dir ../shared-terms/

# 多个项目可以共享相同的术语
jta projectA/en.json --to zh --terminology-dir ~/company-terms/
jta projectB/en.json --to ja --terminology-dir ~/company-terms/

增量翻译

默认行为：完整翻译 - Jta 默认翻译所有内容以获得最高质量和一致性 - 简单且可预测：jta en.json --to zh 始终生成完整翻译

增量模式（可选）： 使用 --incremental 标志时，Jta 智能地：

1. 检测新增键
2. 识别修改的内容
3. 保留未更改的翻译
4. 移除已删除的键

这可以节省时间和 API 成本（更新时通常减少 80-90%）。

用法：

# 首次：完整翻译
jta en.json --to zh

# 更新后：增量翻译（节省成本）
jta en.json --to zh --incremental

# 重新翻译所有内容（如果对现有翻译不满意）
jta en.json --to zh

最佳实践： - 开发阶段：使用 --incremental 进行频繁更新 - 生产发布：使用完整翻译以获得最高质量 - CI/CD：使用 --incremental -y 进行自动化更新

格式保护

Jta 自动保护：

• 变量：{variable}、{{count}}、%s
• HTML 标签：<b>、<span class="highlight">
• URL：https://example.com
• Markdown：**粗体**、*斜体*

🎯 支持的 AI 提供商

提供商	模型	环境变量
OpenAI	所有 OpenAI 模型（GPT-5、GPT-5 mini、GPT-5 nano、GPT-4o 等）	OPENAI_API_KEY
Anthropic	所有 Claude 模型（Claude Sonnet 4.5、Claude Haiku 4.5、Claude Opus 4.1 等）	ANTHROPIC_API_KEY
Gemini	所有 Gemini 模型（Gemini 2.5 Flash、Gemini 2.5 Pro 等）	GEMINI_API_KEY

您可以使用 --model 标志指定这些提供商支持的任何模型。

🌍 支持的语言

Jta 支持 27 种语言，包含完整的元数据（国旗、文字系统和数字系统）：

列出所有支持的语言

# 查看所有支持的语言
jta --list-languages

输出：

🌍 Supported Languages

Left-to-Right (LTR):
  🇬🇧  en      English (English)
  🇨🇳  zh      中文(简体) (Chinese (Simplified))
  🇹🇼  zh-TW   中文(繁体) (Chinese (Traditional))
  🇯🇵  ja      日本語 (Japanese)
  🇰🇷  ko      한국어 (Korean)
  🇪🇸  es      Español (Spanish)
  🇫🇷  fr      Français (French)
  🇩🇪  de      Deutsch (German)
  🇮🇹  it      Italiano (Italian)
  🇵🇹  pt      Português (Portuguese)
  🇷🇺  ru      Русский (Russian)
  🇮🇳  hi      हिन्दी (Hindi)
  🇧🇩  bn      বাংলা (Bengali)
  🇹🇭  th      ไทย (Thai)
  🇻🇳  vi      Tiếng Việt (Vietnamese)
  🇮🇩  id      Bahasa Indonesia (Indonesian)
  🇲🇾  ms      Bahasa Melayu (Malay)
  🇳🇱  nl      Nederlands (Dutch)
  🇵🇱  pl      Polski (Polish)
  🇹🇷  tr      Türkçe (Turkish)
  🇱🇰  si      සිංහල (Sinhala)
  🇳🇵  ne      नेपाली (Nepali)
  🇲🇲  my      မြန်မာ (Burmese)

Right-to-Left (RTL):
  🇸🇦  ar      العربية (Arabic)
  🇮🇷  fa      فارسی (Persian)
  🇮🇱  he      עברית (Hebrew)
  🇵🇰  ur      اردو (Urdu)

Total: 27 languages

RTL 语言支持

对从右到左（RTL）语言（阿拉伯语、波斯语、希伯来语、乌尔都语）的特殊支持： - 自动双向文本标记 - 阿拉伯文字语言的智能标点转换 - 正确处理嵌入的 LTR 内容（URL、数字、代码）

语言示例

# 翻译为简体中文
jta en.json --to zh

# 翻译为繁体中文
jta en.json --to zh-TW

# 翻译为多种亚洲语言
jta en.json --to zh,ja,ko,th,vi

# 翻译为 RTL 语言
jta en.json --to ar,fa,he

# 翻译为欧洲语言
jta en.json --to es,fr,de,it,pt,nl

🏗️ 架构

Jta 遵循清晰、模块化的架构，具有明确的关注点分离：

系统架构

graph TB
    subgraph "🖥️ Presentation Layer"
        CLI[CLI Interface

Cobra + Viper]
        UI[Terminal UI

Lipgloss + Spinner]
    end

    subgraph "🔧 Application Layer"
        APP[App Controller

Workflow Orchestration]
    end

    subgraph "⚙️ Domain Layer"
        subgraph "Translation Engine"
            ENGINE[Translation Engine

Core Orchestrator]
            BATCH[Batch Processor

Concurrent Processing]
            REFLECT[Reflection Engine ⭐

Agentic Quality Control]
        end

        subgraph "Supporting Services"
            TERM[Terminology Manager

Auto-detection + Dictionary]
            INCR[Incremental Translator

Diff Analysis]
            FILTER[Key Filter

Pattern Matching]
            FORMAT[Format Protector

Placeholder Preservation]
            RTL[RTL Processor

Bidirectional Text]
        end
    end

    subgraph "🔌 Infrastructure Layer"
        subgraph "AI Providers"
            OPENAI[OpenAI Provider

GPT-5]
            ANTHROPIC[Anthropic Provider

Claude Sonnet 4.5]
            GEMINI[Gemini Provider

Gemini 2.5 Flash]
        end

        subgraph "Storage"
            JSON[JSON Repository

File I/O]
        end
    end

    subgraph "📦 Domain Models"
        MODELS[Domain Models

Translation • Terminology • Language]
    end

    CLI --> APP
    UI --> APP
    APP --> ENGINE
    ENGINE --> BATCH
    ENGINE --> REFLECT
    ENGINE --> TERM
    ENGINE --> INCR
    ENGINE --> FILTER
    ENGINE --> FORMAT
    ENGINE --> RTL

    BATCH --> OPENAI
    BATCH --> ANTHROPIC
    BATCH --> GEMINI
    REFLECT --> OPENAI
    REFLECT --> ANTHROPIC
    REFLECT --> GEMINI
    TERM --> OPENAI
    TERM --> ANTHROPIC
    TERM --> GEMINI

    TERM --> JSON
    INCR --> JSON

    ENGINE -.-> MODELS
    TERM -.-> MODELS
    BATCH -.-> MODELS

    style REFLECT fill:#ff6b6b,stroke:#c92a2a,stroke-width:3px,color:#fff
    style ENGINE fill:#4ecdc4,stroke:#087f5b,stroke-width:2px
    style CLI fill:#96f2d7,stroke:#087f5b
    style UI fill:#96f2d7,stroke:#087f5b

模块职责

模块	职责	关键特性
CLI	命令行界面	参数解析、帮助文本、命令执行
UI	终端展示	彩色输出、加载动画、进度条、表格
App	应用程序编排	工作流协调、错误处理、结果格式化
Translation Engine	核心翻译逻辑	批次管理、工作流控制、结果组装
Batch Processor	并发处理	并行 API 调用、重试逻辑、速率限制
Reflection Engine ⭐	智能体质量控制	LLM 自我评估、改进建议
Terminology Manager	术语管理	自动检测、词典构建、术语翻译
Incremental Translator	增量处理	差异分析、选择性翻译、合并逻辑
Key Filter	选择性翻译	模式匹配、包含/排除规则
Format Protector	格式保护	占位符检测、HTML/URL/Markdown 保护
RTL Processor	RTL 语言支持	双向标记、标点转换
AI Providers	LLM 集成	API 抽象、响应解析、错误处理
JSON Repository	数据持久化	文件 I/O、JSON 序列化、验证

翻译工作流

sequenceDiagram
    participant User
    participant CLI
    participant App
    participant Engine
    participant Term as Terminology

Manager
    participant Batch as Batch

Processor
    participant Reflect as Reflection

Engine ⭐
    participant AI as AI Provider

    User->>CLI: jta translate source.json
    CLI->>App: Execute command

    rect rgb(240, 248, 255)
        Note over App,Engine: Phase 1: Preparation
        App->>Engine: Load & analyze JSON
        Engine->>Term: Detect/load terminology
        Term->>AI: Detect terms via LLM
        AI-->>Term: Return terms
        Engine->>Engine: Apply key filters
        Engine->>Engine: Create batches
    end

    rect rgb(255, 250, 240)
        Note over Batch,AI: Phase 2: Translation
        Engine->>Batch: Process batches (concurrent)
        loop For each batch
            Batch->>AI: Translate with terminology
            AI-->>Batch: Return translations
        end
    end

    rect rgb(255, 240, 245)
        Note over Reflect,AI: Phase 3: Agentic Reflection ⭐
        Engine->>Reflect: Review translations
        Reflect->>AI: Step 1: Evaluate quality
        AI-->>Reflect: Suggestions
        Reflect->>AI: Step 2: Apply improvements
        AI-->>Reflect: Improved translations
    end

    rect rgb(240, 255, 240)
        Note over Engine,App: Phase 4: Finalization
        Engine->>Engine: Process RTL if needed
        Engine->>Engine: Merge results
        Engine->>App: Return result
        App->>CLI: Format output
        CLI->>User: Display statistics
    end

关键步骤：

1. 加载和分析：加载源 JSON，检测更改（增量模式）
2. 术语：自动检测或加载术语词典
3. 过滤：应用键过滤（如果指定）
4. 批处理：拆分为批次以进行高效处理
5. 翻译：发送到 AI 提供商，附带格式说明
6. 反思 ⭐：两步智能体质量改进（见下文）
7. 处理 RTL：应用双向文本处理（如果需要）
8. 合并：与未更改的翻译合并
9. 保存：使用美化格式写入最终输出

🔄 智能体反思机制

Jta 实现了 Andrew Ng 的翻译智能体方法，采用真正的两步反思过程：

步骤 1：初始翻译（1 次 API）

源文本："Welcome to {app_name}"
→ LLM 翻译
→ 结果："欢迎使用 {app_name}"

步骤 2：反思 - LLM 评估质量（1 次 API）

提示 LLM：
"从 4 个维度评估此翻译：
(i) 准确性 - 错误、误译、遗漏
(ii) 流畅性 - 语法、标点、重复
(iii) 风格 - 文化语境、语气匹配
(iv) 术语 - 一致性、领域术语

提供建设性的改进建议。"

→ LLM 响应：
"[welcome.message] 考虑使用'欢迎来到'而不是'欢迎使用'
以获得更温暖、更符合'Welcome to'的语气"

步骤 3：改进 - LLM 应用建议（1 次 API）

提示 LLM：
"原文：Welcome to {app_name}
初译：欢迎使用 {app_name}
建议：使用'欢迎来到'以获得更温暖的语气

编辑翻译，确保准确性、流畅性、风格、术语。"

→ LLM 响应：
"[welcome.message] 欢迎来到 {app_name}"

为什么采用这种方法？

优势： - ✅ LLM 自我评估：AI 发现人类/规则可能错过的细微质量问题 - ✅ 深度分析：评估准确性、流畅性、风格、文化语境 - ✅ 明确推理：生成具体、可操作的改进建议 - ✅ 更高质量：迭代优化产生更自然、准确的翻译

成本： - 每批次 3 次 API 调用（翻译 → 反思 → 改进） - 对于批次大小为 20 的 100 个键：共 15 次 API 调用（5 次翻译 + 5 次反思 + 5 次改进） - 权衡：3 倍成本换取显著更高的翻译质量

可配置： - 批次大小：--batch-size 10（更小 = 更安全，更大 = 更高效） - 模型选择：更强的模型（GPT-5、Claude Sonnet 4.5）可以更好地处理更大的批次

💡 示例

示例 1：首次翻译

$ jta en.json --to zh

📄 Loading source file...
✓ Source file loaded

📚 Loading terminology...
🔍 Detecting terminology...
✓ Detected 8 terms

🤖 Translating...
✓ Translation completed

💾 Saving translation...
✓ Saved to zh.json

📊 Translation Statistics
   Total items     100
   Success         100
   Failed          0
   Duration        45s
   API calls       15 (5 translate + 5 reflect + 5 improve)

生成的 .jta-terminology.json：

{
  "source_language": "en",
  "preserve_terms": ["GitHub", "API", "OAuth"],
  "consistent_terms": {
    "en": ["repository", "commit", "pull request"]
  }
}

示例 2：增量更新

```bash $ jta en.json --to zh

📄 Loading source file... ✓ Source file loaded

🔍 Analyzing changes... New: 5 keys Modified: 2 keys Unchanged: 93 keys

Continue? [Y/n] y

🤖 Translating... ✓ Trans