# 本地多语言翻译工具

该仓库包含两个脚本，用于将简体中文的字幕 (`srt_to_zh_hant.py`) 和 Excel UI 文本 (`excel_to_zh_hant.py`) 自动翻译成繁體、英文、日文、韩文，并可选接入 OpenAI API 作为翻译后端。

## 环境准备

1. **Python & 虚拟环境**
   ```bash
   python3 -m venv venv
   source venv/bin/activate
   python -m pip install --upgrade pip
   ```
2. **安装依赖**
   ```bash
   python -m pip install -r requirements.txt
   ```
   - 首次执行会自动从 Hugging Face 下载 NLLB-200 distilled 模型（约 2.6GB）到 `.models/nllb-200`。
   - 中国大陆环境建议准备代理或提前下载模型文件后手动放入 `.models/nllb-200`。

3. **OpenAI（可选）**
   - 若需使用 ChatGPT 翻译，设置 `OPENAI_API_KEY` 或在命令中传入 `--openai-api-key`，并使用 `--backend openai`。

## `srt_to_zh_hant.py` 使用说明

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| `--backend {local,openai}` | `local` | 选择本地 NLLB 模型或 OpenAI API。 |
| `--include-tw-hk` | 关闭 | 额外生成 `Subtitle_ZH_Hant_TW`、`Subtitle_ZH_Hant_HK`。 |
| `--show-lang` | 关闭 | 输出“正在翻译 xx”提示。 |
| `--openai-model` | `gpt-4o-mini` | OpenAI 模型名。 |
| `--openai-api-key` | 环境变量 | OpenAI API Key。 |
| `--model-cache-dir` | `.models/nllb-200` | 本地模型缓存目录。 |
| `--batch-size`/`--max-length` | 4 / 512 | 控制推理性能。 |

### 目录约定
- 待翻简体字幕：`Subtitle_Trans_CN`
- 输出目录：
  - `Subtitle_ZH_Hant`（通用繁體，默认）
  - `Subtitle_ZH_Hant_TW`、`Subtitle_ZH_Hant_HK`（加 `--include-tw-hk` 时生成）
  - `Subtitle_EN`、`Subtitle_JP`、`Subtitle_KOREAN`

### 示例
```bash
# 默认：本地模型 + 通用繁体/英/日/韩
python srt_to_zh_hant.py

# 同时输出台繁和港繁，并显示每种语言进度
python srt_to_zh_hant.py --include-tw-hk --show-lang

# 改用 ChatGPT
python srt_to_zh_hant.py --backend openai --openai-model gpt-4o-mini
```

## `excel_to_zh_hant.py` 简述
- 扫描 `./excel` 目录下的 `.xlsx` 文件，为未翻译的文件创建 `_zh-Hant.xlsx` 副本。
- 自动插入六列翻译结果：通用繁體、台繁、港繁、英文、日文、韩文，列名引用 `translator.py` 中的 `SUPPORTED_AI_LANGS`。
- 根据备注列中包含“无需翻译/不翻译”的行跳过翻译。
- 支持与字幕脚本相同的 CLI 选项（`--backend`、`--openai-*`、`--model-cache-dir` 等）。

运行示例：
```bash
python excel_to_zh_hant.py
# 或使用 ChatGPT
python excel_to_zh_hant.py --backend openai --openai-model gpt-4o-mini
```

## 常见问题
- **无法连接 PyPI / Hugging Face**：配置系统代理、使用国内镜像或手动下载模型文件。
- **缺少 Torch / SentencePiece**：确保已在虚拟环境中执行 `pip install -r requirements.txt`，如遇网络问题可手动下载 wheel 安装。
- **第一次运行耗时较长**：NLLB 模型较大，下载与首次加载会花费几分钟，请耐心等待。