# TranslateTools

**Repository Path**: BigCalr/TranslateTools

## Basic Information

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

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 图片文字翻译工具

这个项目现在提供两种使用方式：

1. 桌面软件
2. 命令行工具

两种方式都支持这样的流程：

1. 输入一张图片。
2. 识别图片中的中文文字。
3. 把识别出的文字翻译成指定语言。
4. 擦除原文字区域。
5. 把翻译后的文字重新绘制回图片并输出新图片。

同时也支持选择一个文件夹，遍历里面的图片，批量执行同样的翻译任务，并保存到输出目录。

当前版本优先做成了本地桌面软件，便于普通用户直接打开使用，同时保留命令行方式，方便批处理或后续集成。

## 方案说明

- OCR: `rapidocr-onnxruntime`
- 翻译: `deep-translator` 的 Google 翻译适配器
- 图像处理: `opencv-python`
- 文字绘制: `Pillow`

## 环境要求

- Python 3.10+
- 可以联网访问 Google 翻译服务
- 建议系统安装支持多语言的字体，例如 Noto Sans CJK

## 安装

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .
```

## 启动桌面软件

```bash
image-translator-gui
```

桌面软件支持：

- 选择单张图片，翻译后保存为新图片
- 选择一个文件夹，自动遍历图片并批量保存
- 设置目标语言
- 设置 OCR 置信度和重绘边距
- 指定字体文件，避免目标语言显示异常
- 如果系统没有可用中文界面字体，软件会自动回退为英文界面，避免乱码

### 桌面软件使用流程

#### 单图模式

1. 选择“单张图片”
2. 选择输入图片
3. 选择输出文件位置
4. 选择目标语言
5. 点击“开始翻译”

#### 文件夹模式

1. 选择“整个文件夹”
2. 选择输入文件夹
3. 选择输出文件夹
4. 设置是否递归处理子文件夹
5. 点击“开始翻译”

文件夹模式下会保留原始目录结构，并在文件名后自动追加目标语言后缀，例如：

- `banner.png` -> `banner_ru.png`
- `ad.jpg` -> `ad_en.jpg`

## 用法

```bash
image-translator input.jpg --target en --output output.png
```

也可以显式指定字体：

```bash
image-translator input.jpg --target ja --output output-ja.png --font /usr/share/fonts/truetype/noto/NotoSansCJK-Regular.ttc
```

文件夹批量模式：

```bash
image-translator ./input-folder --input-mode folder --target ru --output ./translated-folder
```

如果不想递归处理子文件夹：

```bash
image-translator ./input-folder --input-mode folder --target ru --output ./translated-folder --non-recursive
```

## 参数

- `input`: 输入图片路径
- `--input-mode`: 输入模式，`file` 为单图，`folder` 为文件夹批量
- `--target`: 目标语言代码，例如 `en`、`ja`、`fr`、`ko`
- `--output`: 输出图片路径
- `--source`: 源语言，默认 `zh-CN`
- `--font`: 指定绘制翻译文字时使用的字体文件
- `--min-confidence`: OCR 最低置信度，默认 `0.45`
- `--padding`: 擦除和重绘区域的额外边距，默认 `6`
- `--non-recursive`: 文件夹模式下不递归处理子文件夹
- `--verbose`: 输出详细日志

## 示例

```bash
image-translator ./examples/demo.png --target en --output ./examples/demo-en.png --verbose
```

```bash
image-translator ./materials --input-mode folder --target ru --output ./materials-translated
```

## 软件打包

如果你要把它发给别人直接双击使用，可以用 PyInstaller 打包：

```bash
source .venv/bin/activate
pip install pyinstaller
pyinstaller -F -w -n image-translator src/image_translator/gui.py
```

打包后生成的可执行文件会在 `dist/` 目录下。

### Windows 版本打包

当前这个仓库已经补好了 Windows 打包文件：

- `image-translator.spec`
- `scripts/build_windows.ps1`

注意：Windows exe 必须在 Windows Python 环境下构建，不能在当前 Linux/WSL 环境里直接产出原生 exe。

在 Windows PowerShell 中执行：

```powershell
Set-ExecutionPolicy -Scope Process Bypass
./scripts/build_windows.ps1
```

如果你的机器没有 `py -3.11`，也可以手动指定：

```powershell
./scripts/build_windows.ps1 -Python "C:\Python311\python.exe"
```

执行完成后，Windows 可执行文件会输出到 `dist/image-translator.exe`。

### Windows 打包前提

- 建议使用 Windows 11 或 Windows 10
- 建议使用 Python 3.11
- 机器需要能联网安装依赖
- 如果你希望 GUI 显示中文，Windows 系统一般自带微软雅黑等字体，不需要额外处理

### 直接交付三平台二进制

如果你的目标是“别人拿到文件直接运行”，不希望他们自己装 Python 或执行命令，那么正确方案不是让对方本地打包，而是由仓库统一产出三平台二进制包。

这个仓库现在已经补齐了三平台打包能力：

- Linux: `scripts/build_linux.sh`
- macOS: `scripts/build_macos.sh`
- Windows: `scripts/build_windows.ps1`
- 统一打包入口: `scripts/build_binary.py`
- GitHub Actions 自动构建: `.github/workflows/build-binaries.yml`

工作方式如下：

1. 你在 GitHub 上推送一个版本标签，例如 `v0.1.0`
2. Actions 会自动在 Windows、macOS、Linux 三个平台各自构建原生二进制
3. 构建产物会自动上传为 workflow artifact
4. 如果是版本标签，还会自动附加到 GitHub Release

最终你会得到三份可分发文件：

- `image-translator-windows-x64.zip`
- `image-translator-macos-universal.zip`
- `image-translator-linux-x64.tar.gz`

你的用户只需要：

1. 下载对应平台的压缩包
2. 解压
3. 直接运行里面的二进制文件

不需要安装 Python，不需要执行任何打包命令。

### 在 GitHub 上触发三平台构建

#### 手动触发

把仓库推到 GitHub 后，在 Actions 页面运行 `Build Binaries` 工作流。

#### 按版本自动触发

```bash
git tag v0.1.0
git push origin v0.1.0
```

推送后会自动生成 Release 附件，直接给别人下载即可。

## 已知限制

- 当前按 OCR 检测框逐块翻译，不会做复杂版面重排。
- 原图中文本如果有弯曲、艺术字、强透视或复杂背景，输出效果会下降。
- 翻译依赖在线服务，离线环境下不能直接使用。
- 批量模式下如果某些图片失败，不会中断整个批次，其余图片会继续处理。

## 后续可扩展方向

- 增加任务历史和失败重试
- 增加可视化预览和翻译前后对比
- 增加 Gradio 或 Flask 网页界面
- 增加离线翻译引擎
- 增加段落合并和更精细的排版策略