LinguaHaru · AIGC 内容生成

想象一下这样的场景：你拿到一份200页的日文技术文档，需要在几个小时内把它翻译成中文，PDF里的排版、表格、图片注释一个都不能乱；或者你追更的生肉漫画更新了，生肉到熟肉之间总有一道语言鸿沟。传统方式是你手动复制粘贴到DeepL/Google Translate，再一个个把译文粘回去——排版全毁，效率极低。

LinguaHaru 解决的就是这个痛点。它是一个开源的下一代 AI 翻译工具，支持 Office 文档、PDF、字幕、图片、视频、实时语音等几乎所有常见格式的一键高质量翻译，而且解压即用，有 Docker 一键部署，也有原生桌面端界面。

LinguaHaru Logo

背景：为什么需要 LinguaHaru

AI 翻译工具并不稀缺——DeepL、Google Translate、ChatGPT 都能翻文字。但当我们把翻译任务搬到具体的工作场景时，通用翻译工具的局限立刻暴露：

排版灾难。 一份带有多级标题、表格、图表注释的 Word 文档扔进 Google Translate，译文格式往往面目全非。LinguaHaru 通过专门的文档解析管道（docx/pptx/xlsx/pdf pipeline）精确保留原始布局，表格保持合并单元格、图表标题跟随原文。

批量翻译缺乏质量控制。 翻译长篇小说、技术手册时，同一个人名、地名、产品名每次译得不一样——术语不一致是专业翻译的大忌。LinguaHaru 内置**术语表（Glossary）**功能，用户可上传 CSV 格式的术语库，强制指定某些词汇的译文，杜绝一词多译。

格式孤岛。 SRT字幕、ASS动画字幕、EPUB电子书、JSON配置文件……每种格式都有自己独特的语法结构，通用翻译工具无法理解这些结构，随意切割文本会导致字幕时间轴错位、JSON结构被破坏。LinguaHaru 为每种格式编写了专门的解析器和回填器，确保翻译后格式完整可用。

实时翻译缺失。 看外语直播、听外语讲座时，没有实时的双语字幕辅助理解。LinguaHaru 支持麦克风实时语音翻译（通过 Whisper + Gemini Live），边说边译，边听边看双语字幕。

这个项目由独立开发者 YANG-Haruka（GitHub ID: 34500224）主导维护，采用 GPL-3.0 开源协议，代码质量在同类开源项目中属于上乘。

核心功能：全格式覆盖的翻译引擎

LinguaHaru 的核心架构非常清晰——一个共享后端引擎，两套前端界面。

文档翻译：排版零损失

桌面端用户将文件拖入窗口，Web 端用户上传文件，翻译引擎自动识别文件类型（docx/pptx/xlsx/pdf/epub/txt/md/html/json/csv 等），分发给对应的 Translator 类处理。每个 Translator 内部都是一个完整的管道：

解析阶段：读取原文件，提取文本内容及元数据（字体、样式、位置、颜色）
预处理阶段：智能分批（避免单次 LLM 调用 token 爆表）、占位符保护（代码块、邮箱、URL 不翻译）、术语表注入
翻译阶段：并发请求多个 LLM API（支持 OpenAI GPT系列、DeepSeek、Gemini、Ollama 本地模型等），内置速率限制和失败重试
回填阶段：将译文按原始位置写回，保持样式、格式完全一致
QA检查：翻译质量复核，检测漏译、术语一致性

翻译前后对比演示

图1：翻译前后对比——漫画、PDF论文、Word、Excel，排版与格式完整保留

以 PDF 为例，LinguaHaru 区分数字文本 PDF（直接提取文字翻译）和扫描图片 PDF（调用 PP-OCRv6 识别文字后翻译）。如果检测到是扫描版，会自动切换到漫画/OCR模式，利用 GPU 加速（onnxruntime-gpu），识别速度比 CPU 快约 60 倍。

插件系统：按需扩展

基础安装包保持小巧（约50MB），插件系统让用户按需安装扩展模块：

插件	能力	硬件需求
PDF翻译	BabelDOC 引擎，保留排版的PDF翻译	CPU
图片OCR	图片内文字识别并回填；PP-OCRv6	GPU 自动加速（~60x）
漫画模式	气泡识别、抹字、译文回填，支持校对后导出	GPU 推荐
视频翻译	视频自动转写+字幕翻译	GPU 推荐
实时语音	麦克风/系统音频实时双语字幕	GPU 推荐

插件安装后自动检测 NVIDIA 显卡并安装 GPU 运行时，卸载插件会完整回收其带来的依赖——不会有残留污染。

两大前端：桌面端 vs Web 控制台

Qt 桌面端：原生 Windows 应用，Fluent Design，支持浅色/深色模式、悬浮实时字幕、全局热键截图翻译、系统托盘运行。适合本地高频使用。
Web 控制台：FastAPI + uvicorn，浏览器内运行全功能，支持多用户会话隔离、局域网共享（部署在服务器上，团队成员通过浏览器访问）、公共服务器模式（设置 API Key 后对外提供服务）。

翻译质量保障体系

LinguaHaru 在翻译质量上做了大量工程努力：

翻译缓存：相同文本段不重复请求 LLM，节省成本、加速处理
原子化增量写盘：每批次翻完后立即写入磁盘，崩溃安全，任务可精确续传
并发限流：智能分批 + per-model 速率限制，避免 API 429 错误
多引擎兜底：主引擎失败自动切换备选模型

据项目文档，6.0 引擎比上一代提速 90% 以上，主要归功于并发请求优化和翻译缓存机制。

技术架构：双前端共享的后端引擎

从代码结构看，LinguaHaru 采用清晰的分层架构：

qt_app/          ← PySide6 + Fluent Widgets 桌面端
webapp/          ← FastAPI Web 控制台（独立 HTTP 包装层）
core/            ← 共享后端引擎（无 UI 依赖，纯 Python）
  backend.py     ← 业务编排层：translator 路由、config 管理
  translators/   ← 各类文件的 Translator 实现（Word/PDF/Excel/…)
  pipelines/     ← 专项管道：video/stt/subtitle/…
  llm/           ← LLM API 封装（OpenAI/Gemini/Ollama）
  glossary/      ← 术语表管理
  ocr/           ← OCR 引擎封装
  pdf/           ← PDF 处理
  speechio/      ← 实时语音
  video/         ← 视频处理
plugins/         ← 可选插件（PDF/图片OCR/漫画/视频/语音）
requirements/
  base.txt       ← 两端共享核心依赖
  web.txt        ← FastAPI + uvicorn
  qt.txt         ← PySide6 + Fluent Widgets

关键依赖（requirements/base.txt）：

openai>=1.59.6：调用 OpenAI 兼容 API（GPT-4o、DeepSeek 等均通过 OpenAI SDK）
tiktoken>=0.8.0：精确 token 计数，控制每次翻译的文本长度
python-docx/python-pptx/openpyxl：Office 文档读写
requests>=2.31：Ollama/LM-Studio 本地模型调用
bs4/lxml：HTML/XML 解析
tenacity：重试逻辑
rich>=13.0：终端高亮输出

Web 端依赖（requirements/web.txt）：

fastapi>=0.115：HTTP 服务框架
uvicorn>=0.30：ASGI 服务器
websockets>=12：实时语音翻译的 WebSocket 支持

架构亮点：

无 UI 依赖的后端：core/backend.py 不 import 任何 UI 库，同时被 Qt 桌面端和 Web 端复用
插件热插拔：插件通过 core/plugins_registry 动态加载/卸载，不影响核心运行
PyInstaller 兼容：支持打包成单文件可执行文件（Windows .exe），sys._MEIPASS 处理打包资源路径
多后端支持：既支持 OpenAI/DeepSeek/Gemini 云端 API，也支持 Ollama/LM-Studio 本地部署（离线可用）

测试覆盖： 项目包含 30+ 个 test_*.py 文件，覆盖各文件类型的翻译往返测试（roundtrip）、边界情况、稳定性与规则、多用户会话等，测试基础设施完善。

局限与争议

尽管 LinguaHaru 功能强大，也存在一些需要注意的局限：

依赖外部 LLM API，成本不可忽视。 项目本身免费开源，但翻译能力完全依赖 OpenAI/DeepSeek 等付费 API（本地 Ollama 需要自行部署）。大规模使用时，API 费用可能成为瓶颈。

PDF 翻译质量受格式影响。 扫描版 PDF（无文字层）依赖 OCR 识别质量，如果扫描本身模糊或排版密集，识别率和翻译准确性会下降。

实时语音翻译插件较重。 视频翻译、实时语音功能需要 torch/paddle/onnxruntime 等重型依赖，加上 GPU 驱动，安装复杂度较高，不适合纯 CPU 环境。

不支持在线翻译模型直接调用。 虽然支持 Ollama 本地部署，但配置比直接用 API Key 复杂，对普通用户门槛略高。

项目目前（2026年）仍处于活跃开发中，API 接口和插件系统可能有 Breaking Change，使用前建议查看 Release Notes。

行业意义与增长趋势

LinguaHaru 的出现填补了开源领域文档级 AI 翻译工具的空白。回顾 AI 翻译工具的发展历程：

机器翻译时代（2016年前）：统计机器翻译（SMT），译文质量差，无法处理复杂文档
神经网络翻译时代（2016-2022）：DeepL/Google NMT 译文质量大幅提升，但仍是通用工具，不懂文档结构
LLM翻译时代（2023-今）：GPT-4o/Claude 等大模型具备上下文理解能力，LLM 翻译质量显著优于 NMT，但通用 LLM 不理解 docx/pdf/ass 等文件格式
文档感知 LLM 翻译（现在）：LinguaHaru 这类产品将 LLM 翻译能力与文档格式理解结合，既发挥 LLM 的高质量，又保留文档的原始结构

这一趋势的代表性开源项目包括：LLaMA Translate、Argos Translate，以及 LinguaHaru。LinguaHaru 在格式支持丰富度（20+格式）、前端完成度（双端支持）、插件生态上处于领先位置。

截至目前，LinguaHaru 在 GitHub 获得 268 Stars，虽然不算爆火，但对于一个专注于垂直场景的工具类开源项目而言，这个数字表明它已经找到了稳定的需求群体——翻译工作者、漫画爱好者、学术研究者、技术文档团队。

快速上手

# 方式一：Docker 一键部署 Web 版（推荐）
git clone https://github.com/YANG-Haruka/LinguaHaru.git
cd LinguaHaru
docker compose up
# 浏览器打开 http://localhost:8080

# 方式二：桌面端
# 下载 Release 中的 Windows 便携版 .exe，解压即用

# 方式三：源码运行
pip install -r requirements/base.txt -r requirements/web.txt
python -m webapp.server

LinguaHaru Logo

背景：为什么需要 LinguaHaru

AI 翻译工具并不稀缺——DeepL、Google Translate、ChatGPT 都能翻文字。但当我们把翻译任务搬到具体的工作场景时，通用翻译工具的局限立刻暴露：

这个项目由独立开发者 YANG-Haruka（GitHub ID: 34500224）主导维护，采用 GPL-3.0 开源协议，代码质量在同类开源项目中属于上乘。

核心功能：全格式覆盖的翻译引擎

LinguaHaru 的核心架构非常清晰——一个共享后端引擎，两套前端界面。

文档翻译：排版零损失

解析阶段：读取原文件，提取文本内容及元数据（字体、样式、位置、颜色）
预处理阶段：智能分批（避免单次 LLM 调用 token 爆表）、占位符保护（代码块、邮箱、URL 不翻译）、术语表注入
翻译阶段：并发请求多个 LLM API（支持 OpenAI GPT系列、DeepSeek、Gemini、Ollama 本地模型等），内置速率限制和失败重试
回填阶段：将译文按原始位置写回，保持样式、格式完全一致
QA检查：翻译质量复核，检测漏译、术语一致性

翻译前后对比演示

图1：翻译前后对比——漫画、PDF论文、Word、Excel，排版与格式完整保留

插件系统：按需扩展

基础安装包保持小巧（约50MB），插件系统让用户按需安装扩展模块：

插件	能力	硬件需求
PDF翻译	BabelDOC 引擎，保留排版的PDF翻译	CPU
图片OCR	图片内文字识别并回填；PP-OCRv6	GPU 自动加速（~60x）
漫画模式	气泡识别、抹字、译文回填，支持校对后导出	GPU 推荐
视频翻译	视频自动转写+字幕翻译	GPU 推荐
实时语音	麦克风/系统音频实时双语字幕	GPU 推荐

插件安装后自动检测 NVIDIA 显卡并安装 GPU 运行时，卸载插件会完整回收其带来的依赖——不会有残留污染。

两大前端：桌面端 vs Web 控制台

Qt 桌面端：原生 Windows 应用，Fluent Design，支持浅色/深色模式、悬浮实时字幕、全局热键截图翻译、系统托盘运行。适合本地高频使用。
Web 控制台：FastAPI + uvicorn，浏览器内运行全功能，支持多用户会话隔离、局域网共享（部署在服务器上，团队成员通过浏览器访问）、公共服务器模式（设置 API Key 后对外提供服务）。

翻译质量保障体系

LinguaHaru 在翻译质量上做了大量工程努力：

翻译缓存：相同文本段不重复请求 LLM，节省成本、加速处理
原子化增量写盘：每批次翻完后立即写入磁盘，崩溃安全，任务可精确续传
并发限流：智能分批 + per-model 速率限制，避免 API 429 错误
多引擎兜底：主引擎失败自动切换备选模型

据项目文档，6.0 引擎比上一代提速 90% 以上，主要归功于并发请求优化和翻译缓存机制。

技术架构：双前端共享的后端引擎

从代码结构看，LinguaHaru 采用清晰的分层架构：

qt_app/          ← PySide6 + Fluent Widgets 桌面端
webapp/          ← FastAPI Web 控制台（独立 HTTP 包装层）
core/            ← 共享后端引擎（无 UI 依赖，纯 Python）
  backend.py     ← 业务编排层：translator 路由、config 管理
  translators/   ← 各类文件的 Translator 实现（Word/PDF/Excel/…)
  pipelines/     ← 专项管道：video/stt/subtitle/…
  llm/           ← LLM API 封装（OpenAI/Gemini/Ollama）
  glossary/      ← 术语表管理
  ocr/           ← OCR 引擎封装
  pdf/           ← PDF 处理
  speechio/      ← 实时语音
  video/         ← 视频处理
plugins/         ← 可选插件（PDF/图片OCR/漫画/视频/语音）
requirements/
  base.txt       ← 两端共享核心依赖
  web.txt        ← FastAPI + uvicorn
  qt.txt         ← PySide6 + Fluent Widgets

关键依赖（requirements/base.txt）：

openai>=1.59.6：调用 OpenAI 兼容 API（GPT-4o、DeepSeek 等均通过 OpenAI SDK）
tiktoken>=0.8.0：精确 token 计数，控制每次翻译的文本长度
python-docx/python-pptx/openpyxl：Office 文档读写
requests>=2.31：Ollama/LM-Studio 本地模型调用
bs4/lxml：HTML/XML 解析
tenacity：重试逻辑
rich>=13.0：终端高亮输出

Web 端依赖（requirements/web.txt）：

fastapi>=0.115：HTTP 服务框架
uvicorn>=0.30：ASGI 服务器
websockets>=12：实时语音翻译的 WebSocket 支持

架构亮点：

无 UI 依赖的后端：core/backend.py 不 import 任何 UI 库，同时被 Qt 桌面端和 Web 端复用
插件热插拔：插件通过 core/plugins_registry 动态加载/卸载，不影响核心运行
PyInstaller 兼容：支持打包成单文件可执行文件（Windows .exe），sys._MEIPASS 处理打包资源路径
多后端支持：既支持 OpenAI/DeepSeek/Gemini 云端 API，也支持 Ollama/LM-Studio 本地部署（离线可用）

局限与争议

尽管 LinguaHaru 功能强大，也存在一些需要注意的局限：

PDF 翻译质量受格式影响。 扫描版 PDF（无文字层）依赖 OCR 识别质量，如果扫描本身模糊或排版密集，识别率和翻译准确性会下降。

实时语音翻译插件较重。 视频翻译、实时语音功能需要 torch/paddle/onnxruntime 等重型依赖，加上 GPU 驱动，安装复杂度较高，不适合纯 CPU 环境。

不支持在线翻译模型直接调用。 虽然支持 Ollama 本地部署，但配置比直接用 API Key 复杂，对普通用户门槛略高。

项目目前（2026年）仍处于活跃开发中，API 接口和插件系统可能有 Breaking Change，使用前建议查看 Release Notes。

行业意义与增长趋势

LinguaHaru 的出现填补了开源领域文档级 AI 翻译工具的空白。回顾 AI 翻译工具的发展历程：

机器翻译时代（2016年前）：统计机器翻译（SMT），译文质量差，无法处理复杂文档
神经网络翻译时代（2016-2022）：DeepL/Google NMT 译文质量大幅提升，但仍是通用工具，不懂文档结构
LLM翻译时代（2023-今）：GPT-4o/Claude 等大模型具备上下文理解能力，LLM 翻译质量显著优于 NMT，但通用 LLM 不理解 docx/pdf/ass 等文件格式
文档感知 LLM 翻译（现在）：LinguaHaru 这类产品将 LLM 翻译能力与文档格式理解结合，既发挥 LLM 的高质量，又保留文档的原始结构

快速上手

# 方式一：Docker 一键部署 Web 版（推荐）
git clone https://github.com/YANG-Haruka/LinguaHaru.git
cd LinguaHaru
docker compose up
# 浏览器打开 http://localhost:8080

# 方式二：桌面端
# 下载 Release 中的 Windows 便携版 .exe，解压即用

# 方式三：源码运行
pip install -r requirements/base.txt -r requirements/web.txt
python -m webapp.server