file_translator

File Translator Plugin

Translate common Office documents inside Dify while keeping layout, fonts, and basic styling intact.

Overview

Field	Value
Author	xuyangyang
Version	0.0.1
Plugin Type	Tool Provider
Supported UI	Apps, Workflows, Agents

The plugin wraps several file translators (TXT / DOCX / XLSX / PPTX). Each tool downloads the source file, streams text to an LLM in token-aware batches, then writes the translated content back to a copy of the original document.

---

Provided Tools

Tool YAML	Purpose
tools/txt_translator.yaml	Line-preserving text file translation
tools/docx_translator.yaml	Paragraph/run-preserving Word translation
tools/xlsx_translator.yaml	Cell-preserving Excel translation
tools/ppt_translator.yaml	Shape/run-preserving PowerPoint translation

All tools expose the same parameter set; only the output format changes.

---

Features

• Structure-aware rewriting keeps paragraphs, bullet points, and table cells aligned.
• Automatic batching with retry and fallback ensures long documents are covered, even when a chunk exceeds the model’s token limit.
• Uses whatever LLM configuration you supply through Dify (temperature, model name, max tokens, etc.).
• Generates predictable filenames such as slides.translated.ja.pptx.

---

Installation

1. Package the plugin:
   dify-plugin plugin package /path/to/file_translator
2. Upload the generated .difypkg in Dify’s Plugin Management console.
3. Enable the tools you need for your App/Workflow.

No extra environment variables or API keys are required beyond the LLM credentials already configured in Dify.

---

Usage

1. In a workflow node (or tool call), select one of the translators.
2. Supply the required parameters:

Parameter	Type	Required	Notes
file_url	string	Yes	Dify-uploaded file URL or accessible HTTP(S) link.
file_name	string	Yes	Used to infer extension and generate the output name.
model	object	Yes	Full LLM configuration object (e.g. from previous node or App settings).
target_lang	string	No	Defaults to en. Accepts language names or codes understood by the LLM.
chunk_tokens	int	No	Max tokens per request (default 1800, clamped to 200–6000).
overlap_tokens	int	No	Optional overlap for context continuity (default 60).

3. Collect the response:
   • A binary blob message containing the translated document.
   • A text summary confirming completion.

---

Output

• File MIME type matches the input format (.txt, .docx, .xlsx, .pptx).
• Original filename is preserved with .translated.<lang> appended before the extension.
• When the source has no translatable content, the original file is returned unchanged with an informational message.

---

Requirements

The plugin’s runtime depends on:

dify_plugin>=0.2.0,<0.3.0
openpyxl==3.1.5
python-docx==1.1.2
python-pptx==0.6.23

These are pulled automatically during packaging/execution.

---

Notes & Limitations

• Excel support requires .xlsx. Legacy .xls files should be converted first.
• Formatting is preserved at run/cell level; complex scripting, animations, or embedded objects are not modified.
• If the LLM fails to translate a line after backoff retries, the original text is left in place to avoid data loss.
• PPT translation now splits oversized chunks recursively so every slide receives an attempt even when token limits are tight.

---

Development

To run the plugin locally for debugging:

pip install -r requirements.txt
python -m main

Ensure .env is configured with your Dify remote debugging credentials (see GUIDE.md for details).

---

License

Distributed under the MIT License. See LICENSE for full text.