XteVision TransDocs 是什么？适合哪些用户？
XteVision TransDocs 是一个 Python 脚本与 Web 界面，用于在保持原始格式和样式的前提下翻译 Microsoft Office 文件和 PDF。它使用 Ollama、MLX 或 LMStudio 的 API，能够自动检测源语言（至少需要 50 个单词），也支持手动指定源语言。
该工具专为 生产级工作负载与个人翻译任务设计。它支持多种界面语言（EN、CN、DE）和三个可互换的 AI 后端，既适合个人用户，也适合企业部署。
TransDocs 能够做什么
通过分析文档中至少 50 个单词来检测源语言。
可通过 -s / --src_lang 参数覆盖检测，优化 OCR 结果。
翻译段落、表格、页眉和页脚，同时保留排版。
在有内嵌文本时直接使用，扫描页面则回退到 Poppler + Tesseract OCR。
可在 Ollama、MLX 或 LMStudio 之间任意选择，适配你的基础设施。
对于重要 PDF，可在翻译前用视觉模型逐页复核。
需要准备软件和系统包
python-docx、python-pptx、openpyxl、Pillow、pytesseract、python-dotenv、requests、langdetect、flask、werkzeugpoppler-utils（pdftoppm 或 pdftocairo 在 PATH 中）以及 tesseract-ocr 和你的文档所需的语言包TRANSDOC_API_TOKEN配置环境并安装依赖
cd TransDocs
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activatepip install -r requirements.txtsudo apt-get install -y poppler-utils tesseract-ocr tesseract-ocr-eng根据你的源文档需要，安装更多 Tesseract 语言包。
根据需要调整 .env 中的设置。完整的支持键列表请参见 配置 章节。
.env 文件中的运行时设置
可通过 .env 管理运行时设置，做法与 invoicer 类似。支持的键包括：
| 键 | 用途 |
|---|---|
| TRANSDOC_PROVIDER | 所选后端提供程序 |
| TRANSDOC_OLLAMA_URL | Ollama 基础 URL |
| TRANSDOC_MLX_URL | MLX 后端 URL |
| TRANSDOC_LM_STUDIO_URL | LMStudio 后端 URL |
| TRANSDOC_DEFAULT_MODEL | 未指定时的默认模型 |
| TRANSDOC_API_TOKEN | 后端的认证令牌 |
| TRANSDOC_UPLOAD_DIR | 上传文件目录 |
| TRANSDOC_OUTPUT_DIR | 翻译输出目录 |
| TRANSDOC_SECRET_KEY | Flask 会话密钥 |
| TRANSDOC_HOST | Web 界面绑定的主机 |
| TRANSDOC_PORT | Web 界面绑定的端口 |
| TRANSDOC_DEBUG | 启用 Flask 调试模式 |
| TRANSDOC_LOG_FILE | 日志文件路径 |
| TRANSDOC_TESSERACT_LANGS | 显式 OCR 语言（如 eng+deu） |
从终端翻译文档
transdoc.py 脚本可以从命令行运行。对于 PDF 输入，流程是混合式的：文本类 PDF 直接提取，扫描版或纯图像页面则回退到 OCR。若已知源语言，传入 -s 可改善 OCR 语言选择。CLI 与 Flask 应用都会自动加载 .env，且 CLI 支持通过 -p/--provider 和 -b/--base_url 选择后端。
| 参数 | 名称 | 说明 |
|---|---|---|
| -i | input_file | 输入文档路径（必填） |
| -o | output_file | 翻译后保存路径（必填） |
| -t | target_lang | 目标语言代码（如 en、de、fr）（必填） |
| -k | api_token | 认证用的 API 令牌（必填） |
| -m | model | 要使用的模型名称（如 llama3.2） |
| -s | src_lang | 源语言代码（省略时自动检测） |
自动检测源语言进行翻译：
python transdoc.py -i input.docx -o output.docx -t en -k your_api_token从指定源语言进行翻译：
python transdoc.py -i input.docx -o output.docx -t en -k your_api_token -s fr使用特定模型进行翻译：
python transdoc.py -i input.docx -o output.docx -t en -k your_api_token -m custom_model可选的 Flask 界面
Web 界面让用户无需使用命令行即可上传文档并接收翻译结果，从而提升易用性。这是基于 Flask 的参考实现，目前未经测试。
pip install flask werkzeugpython app.py在浏览器中打开 http://localhost:5000，然后：
.docx 文件监控与调试输出
脚本会将详细信息同时记录到控制台和名为 translation_debug.log 的文件。日志默认设置为 DEBUG 级别，捕获所有级别的消息。
若希望减少控制台输出的详细程度，可在脚本中调整日志级别：
console_handler.setLevel(logging.INFO) # 将 DEBUG 改为 INFO常见问题与解决方案
DEBUG。-s 手动指定源语言。TRANSDOC_TESSERACT_LANGS，例如 export TRANSDOC_TESSERACT_LANGS=eng+deu。pdftoppm 或 pdftocairo 在 PATH 中。translation_debug.log。app.run(debug=True, port=5001) 中更改端口。