# llmtrans

**Repository Path**: thammer/llmtrans

## Basic Information

- **Project Name**: llmtrans
- **Description**: 一个基于大模型的命令行翻译工具，借鉴自google的translate-shell。最常见的用法是使用大模型强大的翻译功能，翻译man，help。
- **Primary Language**: C++
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-26
- **Last Updated**: 2026-01-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# llmtrans - 命令行翻译工具

一个基于大语言模型的命令行翻译工具，支持多种模型提供商，能够保持原文格式，具备缓存机制，避免重复翻译。

## 功能特性

- 🚀 支持多种大模型提供商（OpenAI、DeepSeek、Qwen、Moonshot、智谱AI等）
- 📝 智能格式识别和保持（man页面、代码、表格、列表等）
- 💾 本地缓存机制，节省API调用成本
- ⚙️ 灵活的配置管理（环境变量 + JSON配置文件）
- 🔄 自动重试机制，提高成功率
- 📊 详细的日志输出，便于调试

## 安装和构建

### 依赖要求

- C++17 或更高版本
- CMake 3.16 或更高版本
- OpenSSL（用于哈希计算）
- libcurlpp（用于HTTP请求）

### 构建步骤

```bash
# 克隆项目
git clone <repository-url>
cd llmtrans

# 创建构建目录
mkdir build && cd build

# 安装依赖
sudo apt update
sudo apt install -y libssl-dev libcurlpp-dev

# 配置和构建
cmake ..
make -j$(nproc)

# 安装(可选)
sudo make install
```

### 构建 DEB 包

```bash
# 在 build 目录中
cmake ..
make -j$(nproc)

# 生成 DEB 包
cpack

# 生成的包文件: llmtrans-1.0.0-Linux.deb
# 或: llmtrans_1.0.0_amd64.deb (取决于配置)
```

### 安装 DEB 包

```bash
# 安装 DEB 包
sudo dpkg -i llmtrans_1.0.0_amd64.deb

# 如果有依赖问题,运行:
sudo apt-get install -f

# 卸载
sudo dpkg -r llmtrans
```

## 使用方法

### 基本用法

```bash
# 配置运行参数
llmtrans --config

# 翻译man页面
man ls | llmtrans

# 翻译文件内容
cat README.md | llmtrans

# 翻译命令输出
ps aux | llmtrans
```

### 命令行参数

```bash
llmtrans [选项]

选项:
  --from LANG     源语言 (默认: auto)
  --to LANG       目标语言 (默认: zh)
  --provider NAME 提供商 (openai, deepseek, qwen, moonshot, zhipu)
  --model NAME    模型名称
  --config        交互式配置运行参数
  --verbose       启用详细输出
  --help          显示帮助信息
```

### 环境变量配置

```bash
# 通用配置
export OPENAI_API_KEY="your_api_key"
export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_MODEL="gpt-3.5-turbo"

# 各服务商专用配置
export DEEPSEEK_API_KEY="your_deepseek_key"
export QWEN_API_KEY="your_qwen_key"
export MOONSHOT_API_KEY="your_moonshot_key"
export ZHIPU_API_KEY="your_zhipu_key"

# 翻译配置
export LLMTRANS_SOURCE_LANG="en"
export LLMTRANS_TARGET_LANG="zh"
export LLMTRANS_PROVIDER="deepseek"
export LLMTRANS_VERBOSE="1"
export LLMTRANS_CACHE="1"
```

### 配置文件

创建 `~/.config/llmtrans/config.json`：

```json
{
    "api": {
        "api_key": "your_api_key_here",
        "base_url": "https://api.deepseek.com/v1",
        "model": "deepseek-chat",
        "provider": "deepseek"
    },
    "translation": {
        "source_lang": "auto",
        "target_lang": "zh",
        "max_tokens": 4000,
        "temperature": 0.3,
        "preserve_formatting": true
    },
    "behavior": {
        "retry_count": 3,
        "timeout_seconds": 30,
        "enable_cache": true,
        "verbose_mode": false
    },
    "cache": {
        "cache_dir": "~/.cache/llmtrans",
        "max_cache_size": 0
    }
}
```

## 支持的模型提供商

### OpenAI

- Base URL: `https://api.openai.com/v1`
- 模型: `gpt-3.5-turbo`, `gpt-4`, `gpt-4-turbo`

### DeepSeek

- Base URL: `https://api.deepseek.com/v1`
- 模型: `deepseek-chat`

### 通义千问 (Qwen)

- Base URL: `https://dashscope.aliyuncs.com/compatible-mode/v1`
- 模型: `qwen-turbo`, `qwen-plus`, `qwen-max`

### Moonshot AI

- Base URL: `https://api.moonshot.cn/v1`
- 模型: `moonshot-v1-8k`, `moonshot-v1-32k`

### 智谱AI

- Base URL: `https://open.bigmodel.cn/api/paas/v4`
- 模型: `glm-4`

## 配置优先级

1. 命令行参数（最高优先级）
2. 环境变量
3. 配置文件
4. 默认配置（最低优先级）

## 缓存机制

- 缓存位置: `~/.cache/llmtrans/`
- 缓存键: `hash(原文内容 + 源语言 + 目标语言)`
- 缓存格式: JSON文件，每个翻译结果单独存储
- 大小限制: 可配置，默认无限制

## 错误处理

- 网络错误: 自动重试，指数退避
- API错误: 显示详细错误信息
- 配置错误: 提示配置问题
- 翻译失败: 输出原文内容

## 开发说明

### 项目结构

```
llmtrans/
├── src/
│   ├── main.cpp              # 主程序
│   ├── core/                 # 核心模块
│   ├── config/               # 配置管理
│   ├── api/                  # API调用
│   ├── utils/                # 工具函数
│   └── cache/                # 缓存系统
├── config/                   # 配置模板
├── CMakeLists.txt           # 构建配置
└── README.md               # 使用说明
```

### 扩展新模型提供商

1. 在 `config/default_config.json` 中添加提供商配置
2. 确保API兼容OpenAI格式
3. 设置正确的base_url和默认模型

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！