Local Translator Sidecar

本项目是一个基于 Argos Translate 的完全离线、便携式翻译引擎，专为 Sidecar 模式（如 Tauri、Electron）优化。

✨ 核心特性

• 📦 零依赖部署: 强制模型路径指向程序同级 packages/ 目录。
• 🔌 硬件版本独立: 提供 CPU、NVIDIA (CUDA)、AMD (ROCm) 三种独立构建方案，按需分发。
• ⚡ 极致加速: 针对不同架构集成 ctranslate2 专用后端。

---

🛠️ 构建环境准备 (实现完全独立)

注意：由于 PyInstaller 会抓取当前 Python 环境中的所有库，要生成不包含 A 卡驱动的 CPU 版本，必须使用独立的虚拟环境。

1. 下载模型 (通用)

python 01download_models.py

2. 创建隔离环境

建议在项目根目录下为不同目标创建独立环境：

# 创建 CPU 环境
python -m venv venv_cpu
# 创建 NVIDIA 环境 (需在带 N 卡机器上操作最佳)
python -m venv venv_cuda
# 创建 AMD 环境
python -m venv venv_rocm

---

📦 针对性打包指南

方案 A: 纯 CPU 版 (最高兼容性)

如果你在 AMD 显卡的机器上，必须在此纯净环境下打包，确保不引入 ROCm 依赖。

# 1. 激活 CPU 环境
source venv_cpu/bin/activate  # Linux
.\venv_cpu\Scripts\Activate   # Windows

# 2. 仅安装基础库
pip install ctranslate2 argostranslate pyinstaller

# 3. 打包
pyinstaller --onefile --console --name "translate_engine_cpu" `
    --hidden-import "argostranslate.definitions" --hidden-import "argostranslate.networking" `
    --hidden-import "argostranslate.package" --hidden-import "argostranslate.settings" `
    --hidden-import "argostranslate.translate" 02translate.py

---

方案 B: NVIDIA CUDA 加速版

建议在拥有 NVIDIA GPU 且安装了 CUDA Toolkit 的机器上执行。

# 1. 激活 CUDA 环境
source venv_cuda/bin/activate

# 2. 安装 CUDA 专用后端
pip install "ctranslate2[cuda]" argostranslate pyinstaller

# 3. 打包
pyinstaller --onefile --console --name "translate_engine_cuda" [同上的 hidden-import 参数] 02translate.py

---

方案 C: AMD ROCm 加速版 (Linux Only)

这是你当前显卡（A 卡）环境下的最优选。

# 1. 激活 ROCm 环境
source venv_rocm/bin/activate

# 2. 安装 ROCm 专用后端
pip install "ctranslate2[rocm]" argostranslate pyinstaller

# 3. 打包
pyinstaller --onefile --console --name "translate_engine_rocm" [同上的 hidden-import 参数] 02translate.py

---

🚚 部署与 Sidecar 调用

目录结构参考

deploy/
├── translate_engine_cpu      # 默认 fallback
├── translate_engine_cuda     # N 卡用户
├── translate_engine_rocm     # A 卡用户 (Linux)
└── packages/                 # 模型文件夹

自动切换逻辑 (Tauri/Electron 伪代码)

// 在你的主程序中检测硬件
const backend = detectGPU() === 'NVIDIA' ? 'cuda' : (detectGPU() === 'AMD' ? 'rocm' : 'cpu');
const command = Sidecar.bin(`translate_engine_${backend}`);
command.spawn();

---

📄 FAQ

Q: 我在 A 卡机器上，能打出 CPU 版吗？ A: 可以。 只要你像上面“方案 A”那样，在一个没有安装 ctranslate2[rocm] 的全新 venv 中打包，PyInstaller 就不会把 A 卡的驱动库包进去，产物就是纯 CPU 驱动的。

Q: 为什么打包命令里的 --name 很重要？ A: 它决定了生成的二进制文件名。通过区分文件名，你可以把三个版本的二进制文件放在同一个安装包里，让你的 App 根据用户电脑配置“见机行事”。