# translate-it

**Repository Path**: somata/translate-it

## Basic Information

- **Project Name**: translate-it
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-25
- **Last Updated**: 2026-04-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 辅助翻译工具

一个基于大语言模型的智能翻译工具，支持三步翻译流程，确保专业术语一致性和文档结构完整性。

## 功能特点

- **三步翻译流程**：
  1. 文档分析：生成优化大纲，提供上下文参考
  2. 关键词提取：自动提取专业术语并翻译，支持自定义术语
  3. 智能翻译：使用上下文和术语表进行精准翻译

- **智能文本处理**：
  - 保留 Markdown 格式和排版结构
  - 保护图片和表格（翻译后自动还原）
  - 智能文本切片（4K-8K 字符，保持句子完整性）
  - 数学公式处理（修正无意义空格，保持公式结构）

- **质量保障**：
  - 英文内容占比检测（自动重试失败翻译）
  - 并发执行（提高翻译速度）
  - 调试模式（显示流式输出和思考内容）

## 安装依赖

使用 `uv` 包管理器安装依赖：

```bash
# 安装依赖
uv sync

# 激活虚拟环境
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate  # Windows
```

## 配置

修改 `src/config.py` 文件：

```python
# API 配置
API_KEY = "your-api-key"
BASE_URL = "https://api.siliconflow.cn/v1"
MODEL = "Qwen/Qwen3-8B"  # 或其他支持的模型

# 文本切片配置
MIN_CHUNK_SIZE = 4000
MAX_CHUNK_SIZE = 8000
```

## 自定义术语

创建 `keywords.json` 文件，格式如下：

```json
{
  "domain generalization": "域泛化",
  "causal filtering": "因果滤波",
  "disentanglement": "解耦"
}
```

## 使用方法

### 基本用法

```bash
# 翻译文件
uv run src/main.py input.md -o output.md

# 使用自定义术语
uv run src/main.py input.md -o output.md --custom-terms keywords.json

# 启用调试模式（显示流式输出）
uv run src/main.py input.md -o output.md --debug

# 跳过文档分析（仅关键词提取+翻译）
uv run src/main.py input.md -o output.md --skip-analysis

# 跳过关键词提取（仅分析+翻译）
uv run src/main.py input.md -o output.md --skip-keywords
```

### 命令行参数

- `input`：输入文件路径
- `-o, --output`：输出文件路径（默认：translated.txt）
- `--custom-terms`：自定义术语文件路径（JSON 格式）
- `--skip-analysis`：跳过文档分析
- `--skip-keywords`：跳过关键词提取
- `--debug`：启用调试模式

## 项目结构

```
├── src/             # 源代码
│   ├── main.py       # 主入口
│   ├── client.py     # OpenAI 客户端
│   ├── config.py     # 配置文件
│   ├── document_analyzer.py  # 文档分析模块
│   ├── keyword_extractor.py   # 关键词提取模块
│   ├── translator.py          # 翻译模块
│   ├── text_processor.py      # 文本预处理（占位符）
│   ├── text_splitter.py       # 文本切片
│   └── quality_checker.py     # 翻译质量检测
├── keywords.json     # 自定义术语
├── README.md         # 项目说明
└── pyproject.toml    # 项目配置
```

## 工作流程

1. **输入文件** → 文本预处理（图片/表格占位）
2. **第零步**：文档分析（生成优化大纲）
3. **第一步**：关键词提取（包含自定义术语）
4. **第二步**：智能翻译（使用上下文和术语表）
5. **输出文件** → 还原图片/表格占位符

## 支持的模型

- Qwen/Qwen3-8B
- GLM-5.1
- 其他兼容 OpenAI API 的模型

## 注意事项

- 确保 API 密钥和模型配置正确
- 大文件可能需要更长的翻译时间
- 调试模式会显示更多输出信息，适合排查问题
- 数学公式会自动修正无意义空格（如 `\text{C a u s a l}` → `\text{Causal}`）

## 示例

### 输入输出示例

输入：
```markdown
# Introduction

Domain generalization is an important research topic in machine learning.
```

输出：
```markdown
# 引言

域泛化是机器学习中的一个重要研究课题。
```

## 许可证

MIT License