# 翻译存储格式设计

## 设计目标
设计一个高效、可扩展的翻译数据存储格式，支持：
1. 双语对照存储
2. 多版本翻译管理
3. 快速检索和访问
4. 与现有 Typst 系统集成

## 存储格式方案

### 方案 1: JSON 格式（推荐）
```json
{
  "metadata": {
    "source_language": "en",
    "target_language": "zh",
    "translation_engine": "deepl",
    "created_at": "2024-01-15T10:30:00Z",
    "version": "1.0"
  },
  "content": [
    {
      "id": "para_001",
      "source_text": "This is an example paragraph.",
      "translated_text": "这是一个示例段落。",
      "context": "introduction",
      "quality_score": 0.95
    },
    {
      "id": "para_002", 
      "source_text": "Typst is very useful for document processing.",
      "translated_text": "Typst 对于文档处理非常有用。",
      "context": "features",
      "quality_score": 0.92
    }
  ]
}
```

### 方案 2: Typst 原生数据格式
```typst
#let translation_data = (
  (
    id: "para_001",
    en: "This is an example paragraph.",
    zh: "这是一个示例段落。",
    context: "introduction",
    quality: 0.95
  ),
  (
    id: "para_002",
    en: "Typst is very useful for document processing.", 
    zh: "Typst 对于文档处理非常有用。",
    context: "features",
    quality: 0.92
  )
)
```

### 方案 3: Markdown 扩展格式
```markdown
---
translation_meta:
  source: en
  target: zh  
  engine: deepl
  created: 2024-01-15T10:30:00Z
  version: 1.0
---

<!-- translation:para_001 -->
This is an example paragraph.

<!-- translation:para_001 -->
这是一个示例段落。

<!-- translation:para_002 -->
Typst is very useful for document processing.

<!-- translation:para_002 -->
Typst 对于文档处理非常有用。
```

## 推荐方案：JSON 格式

### 优点：
1. **标准化**: JSON 是通用数据交换格式
2. **可扩展**: 易于添加新字段和元数据
3. **工具支持**: 丰富的解析和操作库
4. **版本控制友好**: 易于 Git 管理

### 数据结构细节

```json
{
  "metadata": {
    "document_id": "book_123",
    "source_file": "english_book.md",
    "source_language": "en",
    "target_language": "zh",
    "translation_engine": "deepl+gpt4",
    "engine_version": "1.2",
    "created_at": "2024-01-15T10:30:00Z",
    "last_modified": "2024-01-15T14:20:00Z",
    "total_segments": 150,
    "average_quality": 0.93,
    "cost": 3.75
  },
  "segments": [
    {
      "segment_id": "s_001",
      "original_text": "This is the first paragraph.",
      "translated_text": "这是第一个段落。",
      "context_before": "",
      "context_after": "The second paragraph follows.",
      "character_count": 28,
      "word_count": 6,
      "translation_engine": "deepl",
      "confidence_score": 0.96,
      "quality_rating": "excellent",
      "review_status": "approved",
      "review_notes": "",
      "created_at": "2024-01-15T10:31:00Z",
      "modified_at": "2024-01-15T10:31:00Z"
    }
  ],
  "statistics": {
    "total_characters": 4500,
    "total_words": 900,
    "translation_time": "00:15:30",
    "average_segment_length": 30,
    "quality_distribution": {
      "excellent": 120,
      "good": 25,
      "fair": 5,
      "poor": 0
    }
  }
}
```

## 文件组织方案

### 目录结构
```
translations/
├── books/
│   ├── book_123/
│   │   ├── source.md
│   │   ├── translation_v1.json
│   │   ├── translation_v2.json
│   │   └── reviews/
│   │       ├── human_review_v1.json
│   │       └── quality_report.md
│   └── book_456/
├── articles/
└── cache/
    ├── deepl_cache.json
    └── openai_cache.json
```

### 缓存机制
```json
// cache/deepl_cache.json
{
  "cache_version": "1.0",
  "entries": [
    {
      "source_text": "This is an example.",
      "source_hash": "a1b2c3d4e5f6",
      "translated_text": "这是一个示例。",
      "engine": "deepl",
      "timestamp": "2024-01-15T10:30:00Z",
      "usage_count": 5
    }
  ]
}
```

## 与 Typst 集成方案

### 数据加载函数
```typst
#import "translation-utils.typ": load_translation_data

#let translation = load_translation_data("translations/book_123/translation_v1.json")

// 在文档中使用翻译
#show: doc => bilingual_document(
  translation: translation,
  display_mode: "parallel",
  doc: doc
)
```

### 显示模式实现
```typst
#let bilingual_document(translation, display_mode, doc) = {
  // 根据显示模式渲染双语内容
  match display_mode {
    "parallel" => parallel_layout(translation, doc),
    "alternating" => alternating_layout(translation, doc),
    "hover" => hover_layout(translation, doc),
    _ => single_language_layout(translation, doc)
  }
}
```

## 性能优化

1. **分块存储**: 大型文档按章节分割
2. **索引文件**: 创建快速查找索引
3. **压缩存储**: 对重复文本进行压缩
4. **增量更新**: 只更新修改的段落

## 迁移策略

1. **阶段 1**: 实现基础 JSON 存储格式
2. **阶段 2**: 添加缓存和索引功能
3. **阶段 3**: 实现版本管理和差异比较
4. **阶段 4**: 添加质量评估和人工审核功能

这个设计提供了灵活、可扩展的翻译存储解决方案，能够很好地与现有的 PDF 处理系统集成。