Xtranslate

Intelligently translate PDF, Word, Excel, PPT, TXT, and RTF files with format preservation, layout optimization, and multi-engine support including batch pro...

Security Scan

The skill mostly implements a document translation tool, but there are clear inconsistencies and a few security/privacy concerns (undeclared API env vars, hard-coded crypto key, and local file I/O) that you should understand before installing.

Purpose & Capability

The skill claims to be a document translator (cloud/local/built-in), and the code and SKILL.md show support for cloud providers (DeepSeek, OpenAI, Anthropic, SiliconFlow). However the registry metadata declared no required environment variables while both SKILL.md and config_loader.py expect multiple cloud API keys (DEEPSEEK_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, SILICONFLOW_API_KEY, CUSTOM_API_KEY). That mismatch (no declared env vars but code requiring them) is incoherent and should be clarified.

Instruction Scope

The SKILL.md instructs the agent to run the included Python entrypoint (src/main.py) for translating files and batch folders — that is consistent with the stated purpose. The runtime instructions and code will read and write local files (input files, translation outputs, translation_monitor.json, summary files, output directories) and may traverse directories when given a folder. The instructions do not direct the agent to read unrelated OS secrets or shell history, but the skill will create/modify files in the working directory and uses targets.txt/output_path.txt if present.

Install Mechanism

There is no install spec (instruction-only skill) but the bundle includes Python source and a requirements.txt listing many third-party packages (openai, cryptography, ollama, pdf2docx, python-docx, etc.). No external binary downloads or obscure URLs are used in the manifest, which lowers supply-chain risk, but installing the listed Python packages will pull code from public registries.

Credentials

The SKILL.md and config files expect multiple cloud API keys matching the supported cloud engines — that is proportional to supporting cloud translation. However: (1) the registry metadata does not declare these required env vars (incoherence), (2) API keys are stored via src/crypto_utils.py using a hard-coded password/salt ('Xtranslate_Secret_Key' and fixed salt), which provides only obfuscation and is reversible by anyone with the code; and (3) the code will read env vars directly (config_loader.py) without explicit permission prompts. These factors increase privacy risk for sensitive API keys.

Persistence & Privilege

The skill does not request always:true and does not appear to modify other skills or system-wide agent settings. It will create and write local files (translation outputs, translation_monitor.json, summary text files) in the user's workspace. Autonomous invocation is allowed by default (not flagged on its own) — note that allowing the agent to run this skill plus supplying API keys increases the blast radius for any misuse of those keys.

What to consider before installing

Summary and recommended next steps before installing or running Xtranslate: 1) Environment variables and API keys: SKILL.md and the code expect multiple cloud API keys (DeepSeek, OpenAI, Anthropic, SiliconFlow, and a custom key), but the registry metadata did not declare them — assume these keys will be used if you select a cloud engine. Only provide keys you trust and you are willing to allow the code to call external model APIs. 2) Stored 'encryption' is not secure: API keys saved via the GUI use a built-in CryptoUtils with a hard-coded password and salt. Anyone with access to the code can decrypt those stored keys. Do not rely on this for secure secret storage; prefer environment variables or a secure credential store under your control. 3) Network/endpoint review: The skill is designed to contact third-party model endpoints. If you plan to use cloud engines, review translator.py (not fully shown in the SKILL.md) to confirm which URLs are used and whether requests include full document content. If privacy is important, use the 'ollama' (local) or 'python' offline engine and test behavior in an isolated environment first. 4) File I/O and persistence: The tool will read input files, may recurse directories for batch jobs, and will write translation_monitor.json, summary files, and output documents. Run it in a safe directory and inspect files it writes. Clean up logs/monitor files if they contain sensitive paths or metadata. 5) Code quality and runtime behavior: Some GUI code appears truncated in the provided bundle (syntax/logic issues visible in truncated snippets), so you should run the code in a controlled environment and/or manually inspect translator.py and gui.py before use to ensure there are no crashes or unintended behaviors. 6) Recommended precautions: (a) test with the local/offline engine first, (b) run in a sandbox/VM if you will supply production API keys or sensitive documents, (c) inspect network connections (e.g., via a proxy) to confirm which data is sent externally, and (d) consider replacing the hard-coded crypto mechanism with a secure credential store if you will use this long-term. If you want, I can: (1) list the exact places in the code that read environment variables and where they are used, (2) search translator.py/network calls for remote endpoints and payload shapes, or (3) point out specific lines implementing the key storage/decryption so you can evaluate risk further.

Xtranslate 智能翻译工具 / Intelligent Translation Tool

OpenClaw调用方式 / OpenClaw Invocation Method

当用户在OpenClaw中提出以下需求时，调用本技能： When users request the following in OpenClaw, invoke this skill:

用户指令 / User Commands	执行动作 / Execution Actions
"翻译文档" / "翻译文件" / "翻译PDF/Word"<br>"Translate document" / "Translate file" / "Translate PDF/Word"	调用程序自动翻译指定文件<br>Invoke program to automatically translate specified file
"批量翻译" / "翻译文件夹"<br>"Batch translation" / "Translate folder"	批量处理文件夹内所有支持格式的文件<br>Batch process all supported format files in folder

调用示例 / Invocation Examples

用户说 / User says："帮我翻译这个PDF文件"<br>"Help me translate this PDF file"

Claude执行 / Claude executes：

python src/main.py --file document.pdf --engine cloud

用户说 / User says："批量翻译这个文件夹"<br>"Batch translate this folder"

Claude执行 / Claude executes：

python src/main.py --dir ./documents --engine cloud --model "DeepSeek (V3/R1)"

核心指令 / Core Commands

当用户需要翻译文档时，执行以下流程：<br>When users need to translate documents, execute the following process:

1. 配置翻译引擎 → 云端模型 / Ollama本地 / Python内置<br>Configure translation engine → Cloud model / Ollama local / Python built-in
2. 指定文件 → 支持PDF/DOCX/XLSX/PPTX/TXT/RTF等格式<br>Specify file → Support PDF/DOCX/XLSX/PPTX/TXT/RTF and other formats
3. 执行翻译 → 程序自动提取文本、翻译、保留格式、优化排版<br>Execute translation → Program automatically extracts text, translates, preserves format, optimizes layout
4. 输出结果 → 生成翻译后的文件到指定目录<br>Output results → Generate translated files to specified directory

快速使用 / Quick Start

# 翻译单个文件 / Translate single file
python src/main.py --file document.pdf --engine cloud

# 批量翻译文件夹 / Batch translate folder
python src/main.py --dir ./documents --output ./translated

# 指定模型和语言方向 / Specify model and language direction
python src/main.py --file doc.docx --model "GPT-4o" --sl en --tl zh-CN

# 使用Ollama本地模型 / Use Ollama local model
python src/main.py --file doc.pdf --engine ollama

配置说明 / Configuration Guide

环境变量配置 / Environment Variable Configuration

# DeepSeek API密钥 / API Key
$env:DEEPSEEK_API_KEY="your-api-key-here"

# OpenAI API密钥 / API Key
$env:OPENAI_API_KEY="your-api-key-here"

# Anthropic API密钥 / API Key
$env:ANTHROPIC_API_KEY="your-api-key-here"

# SiliconFlow API密钥 / API Key
$env:SILICONFLOW_API_KEY="your-api-key-here"

支持的翻译引擎 / Supported Translation Engines

引擎 / Engine	说明 / Description	适用场景 / Use Cases
cloud	云端大模型(DeepSeek/GPT-4o/Claude等)<br>Cloud large models (DeepSeek/GPT-4o/Claude, etc.)	高质量翻译，推荐<br>High-quality translation, recommended
ollama	本地Ollama模型<br>Local Ollama model	隐私保护，离线使用<br>Privacy protection, offline use
python	内置translate库<br>Built-in translate library	紧急备用，质量一般<br>Emergency backup, average quality

支持的云端模型 / Supported Cloud Models

• DeepSeek (V3/R1)
• GPT-4o
• Claude 3.5 Sonnet
• SiliconFlow (Qwen2.5)
• 自定义 (OpenAI兼容接口)<br>Custom (OpenAI compatible interface)

性能优化配置 / Performance Optimization Configuration

• 智能批次优化: 自动调整批次大小以平衡速度和质量<br>Smart Batch Optimization: Automatically adjust batch size to balance speed and quality
• 并发处理: 支持多批次并行翻译（可配置）<br>Concurrent Processing: Support multi-batch parallel translation (configurable)
• 参数调优: temperature=0.3 平衡准确性和创造性<br>Parameter Tuning: temperature=0.3 balances accuracy and creativity
• 大文档优化: 针对90页以上文档的特殊优化配置<br>Large Document Optimization: Special optimization configuration for documents over 90 pages

输出结构 / Output Structure

output/                          # 输出文件夹（自动创建）<br># Output folder (automatically created)
├── translated_原文件名.docx     # 翻译后的Word文档<br># Translated Word document
├── translated_原文件名.pdf      # 翻译后的PDF（通过Word转换）<br># Translated PDF (converted from Word)
├── translated_原文件名.xlsx     # 翻译后的Excel<br># Translated Excel
├── translated_原文件名.pptx     # 翻译后的PPT<br># Translated PPT
tmp/                             # 临时文件夹<br># Temporary folder
└── [PDF转Word临时文件]          # 自动清理<br># [PDF to Word temporary files]  # Auto cleanup

文件说明 / File Description

• 自动排版 - Word文档自动设置宋体/Times New Roman字体，1.25倍行距<br>Automatic Layout - Word documents automatically set SimSun/Times New Roman font, 1.25 line spacing
• 格式保留 - 保留原文档的表格、段落、样式等格式<br>Format Preservation - Preserve tables, paragraphs, styles and other formats of original documents
• 关键词引导 - 自动提取文档关键词，提升专业术语翻译准确性<br>Keyword Guidance - Automatically extract document keywords to improve professional term translation accuracy

功能特点 / Features

• ✅ 多格式支持 - PDF/DOCX/XLSX/PPTX/TXT/RTF/WPS<br>Multi-format Support - PDF/DOCX/XLSX/PPTX/TXT/RTF/WPS

• ✅ 格式保留 - 翻译后保留原文档结构和样式<br>Format Preservation - Preserve original document structure and style after translation

• ✅ 智能排版 - 自动优化Word字体和行距<br>Smart Layout - Automatically optimize Word fonts and line spacing

• ✅ 批量处理 - 支持文件夹批量翻译<br>Batch Processing - Support folder batch translation

• ✅ 多引擎支持 - 云端/本地/内置三种引擎可选<br>Multi-engine Support - Three engines available: cloud/local/built-in

• ✅ 关键词提取 - 使用jieba提取专业术语提升翻译质量<br>Keyword Extraction - Use jieba to extract professional terms to improve translation quality

• ✅ API加密 - API Key加密存储，确保安全<br>API Encryption - Encrypt API Key storage to ensure security

• ✅ 智能监控 - 全程记录翻译过程，自动性能分析<br>Smart Monitoring - Record translation process throughout, automatic performance analysis

• ✅ 自动优化 - 基于历史数据提供优化建议<br>Auto Optimization - Provide optimization suggestions based on historical data

• ✅ JSON批量 - 云模型采用JSON格式批量翻译，提升效率<br>JSON Batch - Cloud model uses JSON format for batch translation, improving efficiency

• ✅ 性能优化 - 智能批次调整，大文档处理速度提升25-30%<br>Performance Optimization - Smart batch adjustment, large document processing speed improved by 25-30%

• ✅ 并发加速 - 支持多批次并行处理，进一步提升效率<br>Concurrent Acceleration - Support multi-batch parallel processing, further improve efficiency

文件结构 / File Structure

Xtranslate/
├── SKILL.md                  # 核心指令 + 元数据<br># Core instructions + metadata
├── requirements.txt          # Python依赖列表<br># Python dependency list
├── Xtranslate.spec           # PyInstaller打包配置<br># PyInstaller packaging configuration
│
├── src/                      # 源代码目录<br># Source code directory
│   ├── config.py             # 全局配置（引擎、模型、语言等）<br># Global configuration (engines, models, languages, etc.)
│   ├── main.py               # 命令行入口程序<br># Command line entry program
│   ├── translator.py         # 翻译引擎模块<br># Translation engine module
│   ├── file_handler.py       # 文件读写处理器<br># File read/write processor
│   ├── analyzer.py           # 文本分析与关键词提取<br># Text analysis and keyword extraction
│   ├── formatter.py          # Word排版优化器<br># Word layout optimizer

│   ├── crypto_utils.py       # API Key加密工具<br># API Key encryption tool
│   ├── translation_monitor.py # 翻译过程监控器<br># Translation process monitor
│   └── ...
│
├── templates/                # 代码模板<br># Code templates
│   ├── module.py.md          # Python模块模板<br># Python module template
│   └── translator_engine.py.md # 新增引擎模板<br># New engine template
│
├── examples/                 # 代码示例<br># Code examples
│   ├── good.md               # 优秀代码示例<br># Excellent code examples
│   └── anti-pattern.md       # 反模式示例<br># Anti-pattern examples
│
├── references/               # 规范参考<br># Specification references
│   ├── naming-convention.md  # 命名规范<br># Naming convention
│   └── project-structure.md  # 项目结构规范<br># Project structure specification
│
├── scripts/                  # 辅助脚本<br># Auxiliary scripts
│   └── check-deps.py         # 依赖检查脚本<br># Dependency check script
│
├── translation_monitor.json  # 翻译监控记录文件<br># Translation monitoring record file
├── analyze_performance.py    # 性能分析脚本<br># Performance analysis script
├── view_monitor.py           # 监控记录查看脚本<br># Monitoring record viewing script
├── view_detail.py            # 详细记录查看脚本<br># Detailed record viewing script
│
├── build/                    # 构建文件<br># Build files
├── dist/                     # 可执行文件输出<br># Executable file output
│   └── Xtranslate.exe        # Windows可执行文件<br># Windows executable file
├── output/                   # 翻译结果输出<br># Translation result output
└── tmp/                      # 临时文件<br># Temporary files

模块说明 / Module Description

模块 / Module	功能 / Function
config.py	全局配置管理，包含模型配置、API设置、批次参数<br>Global configuration management, including model configuration, API settings, batch parameters
main.py	命令行入口，支持参数解析和批量处理<br>Command line entry, supports parameter parsing and batch processing
translator.py	翻译核心，支持cloud/ollama/python三种引擎<br>Translation core, supports cloud/ollama/python three engines
file_handler.py	多格式文件读写（Word/Excel/PPT/PDF/TXT等）<br>Multi-format file read/write (Word/Excel/PPT/PDF/TXT, etc.)
analyzer.py	使用jieba进行中文关键词提取<br>Use jieba for Chinese keyword extraction
formatter.py	Word文档自动排版优化<br>Word document automatic layout optimization

| crypto_utils.py | Fernet加密API Key<br>Fernet encrypt API Key | | translation_monitor.py | 翻译过程全程监控，性能统计与自动分析<br>Full-process monitoring of translation, performance statistics and automatic analysis |

依赖安装 / Dependency Installation

pip install -r requirements.txt

主要依赖 / Main Dependencies

• openai - 云端模型API调用<br>Cloud model API calls

• ollama - 本地Ollama模型<br>Local Ollama model

• python-docx - Word文档处理<br>Word document processing

• pdf2docx - PDF转Word<br>PDF to Word conversion

• openpyxl - Excel处理<br>Excel processing

• python-pptx - PPT处理<br>PPT processing

• jieba - 中文分词和关键词提取<br>Chinese word segmentation and keyword extraction

• cryptography - API Key加密<br>API Key encryption

• translate - Python内置翻译库<br>Python built-in translation library

• striprtf - RTF文件处理<br>RTF file processing

智能监控系统 / Smart Monitoring System

监控功能 / Monitoring Functions

• 全程记录 - 自动记录每次翻译的详细过程<br>Full Process Recording - Automatically record detailed process of each translation
• 性能统计 - 精确测量各阶段耗时<br>Performance Statistics - Accurately measure time consumption of each stage
• 自动分析 - 每10次翻译后生成性能报告<br>Automatic Analysis - Generate performance report after every 10 translations
• 优化建议 - 基于历史数据提供针对性优化方案<br>Optimization Suggestions - Provide targeted optimization solutions based on historical data

监控文件 / Monitoring Files

• translation_monitor.json - 存储所有翻译记录<br>translation_monitor.json - Store all translation records
• analyze_performance.py - 性能深度分析脚本<br>analyze_performance.py - Performance deep analysis script
• view_monitor.py - 查看记录概览<br>view_monitor.py - View record overview
• view_detail.py - 查看详细记录<br>view_detail.py - View detailed records

使用示例 / Usage Examples

# 查看翻译记录概览 / View translation record overview
python view_monitor.py

# 查看详细记录 / View detailed records
python view_detail.py

# 性能深度分析 / Performance deep analysis
python analyze_performance.py

故障排除 / Troubleshooting

问题 / Issues	解决方案 / Solutions
API Key错误 / API Key error	检查环境变量是否正确设置<br>Check if environment variables are correctly set
PDF转换失败 / PDF conversion failed	确保PDF非扫描件，有可选中文字<br>Ensure PDF is not scanned and has selectable text

| Ollama连接失败 / Ollama connection failed | 确保Ollama服务已启动<br>Ensure Ollama service is started | | 翻译质量差 / Poor translation quality | 尝试切换云端模型，或使用关键词引导<br>Try switching cloud models, or use keyword guidance | | 排版错乱 / Layout disorder | 检查原文档格式是否过于复杂<br>Check if original document format is too complex | | 翻译速度慢 / Slow translation speed | 使用analyze_performance.py分析性能瓶颈<br>Use analyze_performance.py to analyze performance bottlenecks | | 监控记录异常 / Monitoring record exception | 检查translation_monitor.json文件权限<br>Check translation_monitor.json file permissions | | 大文档处理过慢 / Large document processing too slow | 检查是否启用了性能优化配置<br>Check if performance optimization configuration is enabled | | 并发处理失败 / Concurrent processing failed | 降低concurrent参数或检查API限制<br>Reduce concurrent parameter or check API limits |

---

注意：本工具仅供个人学习研究使用，请遵守相关平台规则。