Metadata-Version: 2.4
Name: qwen-mt-cli
Version: 0.3.8
Summary: Qwen-MT CLI - Command-line translation tool powered by Qwen-MT with vector-based term matching
Project-URL: Homepage, https://github.com/leiyu/qwen-mt-cli
Project-URL: Repository, https://github.com/leiyu/qwen-mt-cli
Project-URL: Issues, https://github.com/leiyu/qwen-mt-cli/issues
Author-email: 镭屿 <jiayu.cly@alibaba-inc.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: cli,dashscope,i18n,localization,qwen,translation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Internationalization
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: dashscope>=1.0
Requires-Dist: openai>=1.0
Requires-Dist: openpyxl>=3.1
Requires-Dist: pandas>=2.0
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: rich>=13.0
Requires-Dist: zvec>=0.3
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# QMT - Qwen-MT CLI

基于通义千问机器翻译模型 (Qwen-MT) 的命令行翻译工具。支持单句翻译、交互式 REPL、CSV/Excel 批量翻译，并提供术语表、翻译记忆、领域提示、向量语义匹配等专业翻译辅助功能。

## 安装

需要 Python >= 3.10。

```bash
pip install qwen-mt-cli
```

或从源码安装：

```bash
git clone https://github.com/leoleils/qwen-mt-cli.git
cd qwen-mt-cli
pip install -e .
```

安装后即可使用 `qmt` 命令。

## 配置

设置 DashScope API Key（[申请地址](https://dashscope.console.aliyun.com/)）：

```bash
export DASHSCOPE_API_KEY="sk-xxxxxxxx"
```

也可以通过 `--api-key` 参数逐次传入。

## 快速开始

```bash
# 翻译文本
qmt "你好世界" -t English

# 指定模型
qmt "Hello World" -t Chinese -m qwen-mt-plus

# 翻译文件
qmt -f article.txt -t English

# 管道输入
echo "你好" | qmt -t English

# 流式输出
qmt "你好世界" -t English --stream

# 交互式模式
qmt -i -t English
```

## 可用模型

| 模型 | 特点 | 流式 | 语言数 |
|------|------|------|--------|
| `qwen-mt-plus` | 最高翻译质量，适用于专业领域 | - | 92 |
| `qwen-mt-flash` | 通用首选，效果/速度/成本平衡 (默认) | 支持 | 92 |
| `qwen-mt-lite` | 最快响应速度，适用于实时场景 | 支持 | 31 |

## 批量翻译

支持 CSV (.csv/.tsv) 和 Excel (.xlsx/.xls) 文件的批量翻译。翻译文件第一列内容，结果追加为新列。

```bash
# CSV 批量翻译
qmt -B input.csv -t English

# Excel 批量翻译（所有 sheet）
qmt -B input.xlsx -t Korean

# 指定输出文件
qmt -B input.csv -O output.csv -t English

# 首行也翻译（无表头模式）
qmt -B input.csv -t English --no-header

# 断点恢复（中断后从上次位置继续）
qmt -B input.csv -t English --resume
```

默认行为：
- 首行视为表头，不翻译（`--no-header` 可改变此行为）
- 输出文件自动命名为 `原文件名_translated.ext`
- Excel 文件翻译所有工作表
- 触发 API 限流时自动指数退避重试（2s -> 4s -> 8s -> 16s -> 32s，最多 5 次）
- 支持 `--resume` 断点恢复，中断后可继续翻译

## 术语管理

固定术语确保特定词汇翻译一致。保存在项目目录 `.qmt/terms.csv`。

```bash
# 添加术语
qmt terms add "React" "React"
qmt terms add "组件" "コンポーネント"

# 查看术语列表
qmt terms list

# 删除术语
qmt terms remove "React"

# 清空所有术语
qmt terms clear

# 从 CSV/TSV 文件批量导入
qmt terms import terms.csv

# 翻译时使用内联术语（不保存）
qmt "React组件开发" -t Japanese --terms "React:React,组件:コンポーネント"
```

## 翻译记忆

提供参考翻译对，帮助模型保持翻译风格一致。保存在 `.qmt/memory.csv`。

```bash
# 添加翻译记忆
qmt memory add "你好世界" "Hello World"

# 查看记忆列表
qmt memory list

# 删除记忆
qmt memory remove "你好世界"

# 清空所有记忆
qmt memory clear

# 从文件批量导入
qmt memory import memory.csv
```

## 向量语义匹配

当术语或翻译记忆条目较多时（默认超过 20 条），QMT 自动启用向量语义匹配，从大量条目中智能筛选与当前翻译内容最相关的 Top-K 条（默认 10 条）传给模型，而不是全量传入。

底层使用 zvec 向量数据库（HNSW 索引 + 余弦距离）存储嵌入向量，通过 DashScope `text-embedding-v3` 模型生成向量嵌入进行语义检索。向量索引以二进制格式存储在 `.qmt/terms.zvec/` 和 `.qmt/memory.zvec/`，首次翻译时自动构建，后续增量同步。

```bash
# 默认行为：术语/记忆超过 20 条时自动启用
qmt "进入副本后需要先组队" -t Korean -v

# 控制返回条数（默认 10）
qmt "进入副本" -t Korean --top-k 5

# 调整启用阈值（默认 20，设高则不启用）
qmt "进入副本" -t Korean --threshold 50

# 批量翻译时自动预嵌入所有源文本，逐行筛选最相关术语/记忆
qmt -B input.xlsx -t Korean -v
```

### --learn 自动学习

翻译结果可自动写回翻译记忆库，并即时同步向量索引：

```bash
# 单条翻译 + 自动学习
qmt "锻造装备需要金币" -t Korean --learn

# 批量翻译 + 批量学习（所有成功翻译自动写入记忆）
qmt -B input.csv -t Korean --learn

# 交互模式中切换学习
qmt -i -t Korean
# 输入 /learn 开启自动学习
```

## 向量索引管理

当术语库条目较多时（如 25000+），首次翻译需要嵌入所有术语会非常耗时。推荐提前构建向量索引：

```bash
# 查看当前索引状态
qmt vectordb status

# 从 CSV 重建全部向量索引（术语 + 翻译记忆）
qmt vectordb rebuild

# 清除所有向量索引（不影响 CSV 数据）
qmt vectordb clear
```

`rebuild` 会调用 DashScope embedding API 逐批嵌入所有术语/记忆，构建完成后后续翻译即可使用向量语义匹配。如果未预先构建索引且术语超过 500 条，翻译时会自动降级为截取前 N 条。

## 领域提示

领域提示告诉模型翻译的专业领域和风格要求，支持两级存储：

- **项目级** — 保存在当前目录 `.qmt/domain.md`，优先级最高
- **全局级** — 保存在 `~/.qmt/domain.md`，作为默认值

```bash
# 设置项目级领域
qmt domain set "technology"

# 设置全局级领域
qmt domain set "medical translation, formal tone" --global

# 查看当前配置
qmt domain show

# 清除项目级领域
qmt domain clear

# 清除全局级领域
qmt domain clear --global
```

优先级：命令行 `-d` 参数 > 项目级 > 全局级。

翻译时自动加载已保存的领域提示，无需每次手动指定：

```bash
# 先设置领域
qmt domain set "game localization, martial arts world view"

# 后续翻译自动生效
qmt "仙缘副本" -t Korean
qmt -B game_strings.xlsx -t Korean
```

## 交互式模式

```bash
qmt -i -t English
```

交互模式下可用命令：

| 命令 | 说明 |
|------|------|
| `/help` | 显示帮助 |
| `/target <lang>` | 切换目标语言 |
| `/source <lang>` | 切换源语言 |
| `/model <name>` | 切换模型 |
| `/stream` | 切换流式输出 |
| `/domain <text>` | 设置领域提示 |
| `/domain save [global]` | 保存当前领域到项目/全局 |
| `/domain clear` | 清除当前领域 |
| `/topk <n>` | 设置语义匹配 Top-K |
| `/learn` | 切换翻译记忆自动学习 |
| `/info` | 显示当前设置 |
| `exit` / `quit` | 退出 |

## 完整参数一览

```
qmt [TEXT] [OPTIONS]

参数:
  TEXT                    待翻译文本

选项:
  -t, --target TEXT       目标语言 (默认 Chinese)
  -s, --source TEXT       源语言 (默认 auto)
  -m, --model TEXT        模型 (plus/flash/lite, 默认 flash)
  -f, --file PATH         翻译文件内容
  -d, --domain TEXT       领域提示
  -i, --interactive       交互式模式
  --stream                流式输出
  --terms TEXT            内联术语 (源:译,源:译)
  --terms-file PATH       术语文件 (CSV/TSV)
  --memory-file PATH      记忆文件 (CSV/TSV)
  -B, --batch PATH        批量翻译文件 (CSV/Excel)
  -O, --output PATH       批量翻译输出文件
  --no-header             CSV/Excel 无表头模式
  --resume                断点恢复
  --top-k INT             语义匹配返回条数 (默认 10)
  --threshold INT         语义匹配启用阈值 (默认 20)
  --learn                 翻译结果自动写入翻译记忆
  --api-key TEXT          API Key
  -v, --verbose           显示详细信息
  --no-store              不加载本地术语/记忆库
  -h, --help              显示帮助
  -V, --version           显示版本
```

## 项目结构

```
src/qmt/
  cli.py          # CLI 入口与命令定义
  client.py       # Qwen-MT API 客户端
  batch.py        # CSV/Excel 批量翻译
  interactive.py  # 交互式 REPL
  matcher.py      # 向量语义匹配编排层
  embedding.py    # DashScope text-embedding-v3 嵌入 (zvec QwenDenseEmbedding)
  vectorstore.py  # 向量索引存储 (zvec HNSW)
  store.py        # 本地持久化存储 (术语/记忆/领域)
  models.py       # 数据模型
  parsers.py      # 输入解析
  formatters.py   # 终端输出格式化
  constants.py    # 常量定义
  exceptions.py   # 自定义异常
```

## 开发

```bash
# 安装开发依赖
pip install -e ".[dev]"

# 代码检查
ruff check src/qmt/

# 格式化
ruff format src/qmt/

# 运行测试
pytest
```

## License

Apache-2.0
