Leon/docutranslate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

更新readme

Browse Source
This commit is contained in:
xunbu
2025-09-06 00:08:54 +08:00
parent f4296c86c6
commit 08f07e9577
4 changed files with 372 additions and 363 deletions
Download Patch File Download Diff File Expand all files Collapse all files

318
README.md
View File

@@ -2,48 +2,53 @@
<img src="./DocuTranslate.png" alt="Project Logo" style="width: 150px"> <img src="./DocuTranslate.png" alt="Project Logo" style="width: 150px">
</p> </p>
# DocuTranslate <h1 align="center">DocuTranslate</h1>
[![GitHub stars](https://img.shields.io/github/stars/xunbu/docutranslate?style=flats&logo=github&color=blue)](https://github.com/xunbu/docutranslate) <p align="center">
[![github下载数](https://img.shields.io/github/downloads/xunbu/docutranslate/total?logo=github)](https://github.com/xunbu/docutranslate/releases) <a href="https://github.com/xunbu/docutranslate/stargazers"><img src="https://img.shields.io/github/stars/xunbu/docutranslate?style=flat-square&logo=github&color=blue" alt="GitHub stars"></a>
[![PyPI version](https://img.shields.io/pypi/v/docutranslate)](https://pypi.org/project/docutranslate/) <a href="https://github.com/xunbu/docutranslate/releases"><img src="https://img.shields.io/github/downloads/xunbu/docutranslate/total?logo=github&style=flat-square" alt="GitHub Downloads"></a>
[![python版本](https://img.shields.io/badge/Python-3.11+-3776AB?logo=python&logoColor=white)](https://www.python.org/) <a href="https://pypi.org/project/docutranslate/"><img src="https://img.shields.io/pypi/v/docutranslate?style=flat-square" alt="PyPI version"></a>
[![开源协议](https://img.shields.io/github/license/xunbu/docutranslate)](./LICENSE) <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.11+-3776AB?logo=python&logoColor=white&style=flat-square" alt="Python Version"></a>
<a href="./LICENSE"><img src="https://img.shields.io/github/license/xunbu/docutranslate?style=flat-square" alt="License"></a>
</p>
[**简体中文**](/README_ZH.md) / [**English**](/README.md) / [**日本語**](/README_JP.md) <p align="center">
<a href="/README_ZH.md"><strong>简体中文</strong></a> / <a href="/README.md"><strong>English</strong></a> / <a href="/README_JP.md"><strong>日本語</strong></a>
</p>
**DocuTranslate** is a file translation tool that combines advanced document analysis engines (such as [docling](https://github.com/docling-project/docling) and [minerU](https://mineru.net/)) with large language models (LLMs). It can accurately translate documents in a wide variety of formats. <p align="center">
An ultra-lightweight local file translation tool based on Large Language Models (LLMs), dedicated to providing an accurate, fast, and extensible translation experience.
</p>
The new version's architecture adopts **Workflow** as its core, providing a highly configurable and extensible solution for various types of translation tasks. - ✅ **Supports Multiple Formats**: Can translate various files such as `pdf`, `docx`, `xlsx`, `md`, `txt`, `json`, `epub`, `srt`, and more.
- ✅ **Automatic Glossary Generation**: Supports automatic generation of glossaries to ensure term alignment.
- ✅ **Supports Multiple Formats**: Capable of translating various files such as `pdf`, `docx`, `xlsx`, `md`, `txt`, `json`, `epub`, `srt`, and more. - ✅ **PDF Table, Formula, and Code Recognition**: With the `docling` and `mineru` PDF parsing engines, it can recognize and translate tables, formulas, and code frequently found in academic papers.
- ✅ **Table, Formula, and Code Recognition**: Utilizes `docling` and `mineru` to recognize and translate tables, formulas, and code frequently found in academic papers. - ✅ **JSON Translation**: Supports specifying the values to be translated in JSON via JSON paths (using `jsonpath-ng` syntax).
- ✅ **Automatic Glossary Generation**: Supports automatic glossary creation to ensure terminology consistency. - ✅ **Word/Excel Format-Preserving Translation**: Supports translating `docx` and `xlsx` files (currently not `doc` or `xls` files) while preserving the original formatting.
- ✅ **JSON Translation**: Allows specifying values to be translated in JSON using JSONPath (`jsonpath-ng` syntax) specifications. - ✅ **Multi-AI Platform Support**: Supports most AI platforms, enabling high-performance, concurrent AI translation with custom prompts.
- ✅ **High-Fidelity Word/Excel Translation**: Supports translation of `docx` and `xlsx` files (currently does not support `doc` or `xls` files) while preserving the original formatting. - ✅ **Asynchronous Support**: Designed for high-performance scenarios, it offers complete asynchronous support, providing service interfaces for parallel multitasking.
- ✅ **Multi-AI Platform Support**: Compatible with most AI platforms, enabling high-performance concurrent AI translation with customizable prompts. - ✅ **LAN and Multi-user Support**: Supports simultaneous use by multiple users on a local area network.
- ✅ **Asynchronous Support**: Designed for high-performance scenarios, offering full asynchronous support and service interfaces for parallel task execution.
- ✅ **Interactive Web Interface**: Provides an out-of-the-box Web UI and RESTful API for easy integration and use. - ✅ **Interactive Web Interface**: Provides an out-of-the-box Web UI and RESTful API for easy integration and use.
- ✅ **Small-Footprint, Multi-Platform "Lazy" Packages**: Windows and Mac "lazy" packages under 40MB (for versions not using `docling` for local PDF parsing).
> When translating `pdf` files, they are first converted to markdown, so the original typesetting will be **lost**. Users with typesetting requirements should note this. > When translating `pdf` files, they are first converted to Markdown, which will **lose** the original layout. Users with layout requirements should take note.
> QQ Discussion Group: 1047781902 > QQ Discussion Group: 1047781902
**UI Interface**: **UI Interface**:
![翻译效果](/images/UI界面.png) ![Translation Effect](/images/UI界面.png)
**Paper Translation**: **Thesis Translation**:
![翻译效果](/images/论文翻译.png) ![Translation Effect](/images/论文翻译.png)
**Novel Translation**: **Novel Translation**:![Translation Effect](/images/小说翻译.png)
![翻译效果](/images/小说翻译.png)
## Integrated Packages ## All-in-One Packages
For users who want to get started quickly, we provide integrated packages on [GitHub Releases](https://github.com/xunbu/docutranslate/releases). Simply download, unzip, and enter your AI platform's API key to start using. For users who want to get started quickly, we provide all-in-one packages on [GitHub Releases](https://github.com/xunbu/docutranslate/releases). Simply download, unzip, and enter your AI platform API-Key to start using.
- **DocuTranslate**: The standard version, which uses the online `minerU` engine to parse documents. Recommended for most users. - **DocuTranslate**: Standard version, uses the online `minerU` engine to parse PDF documents. Choose this version if you don't need local PDF parsing (recommended).
- **DocuTranslate_full**: The full version, which includes the `docling` local parsing engine. Suitable for offline scenarios or those with higher data privacy requirements. - **DocuTranslate_full**: Full version, includes the built-in `docling` local PDF parsing engine. Choose this version if you need local PDF parsing.
## Installation ## Installation
@@ -53,14 +58,14 @@ For users who want to get started quickly, we provide integrated packages on [Gi
# Basic installation # Basic installation
pip install docutranslate pip install docutranslate
# If using the docling local parsing engine # To use docling for local PDF parsing
pip install docutranslate[docling] pip install docutranslate[docling]
``` ```
### Using uv ### Using uv
```bash ```bash
# Initialize the environment # Initialize environment
uv init uv init
# Basic installation # Basic installation
@@ -73,72 +78,70 @@ uv add docutranslate[docling]
### Using git ### Using git
```bash ```bash
# Initialize the environment # Initialize environment
git clone https://github.com/xunbu/docutranslate.git git clone https://github.com/xunbu/docutranslate.git
cd docutranslate cd docutranslate
uv sync uv sync
``` ```
## Core Concept: Workflow ## Core Concept: Workflow
The core of the new version of DocuTranslate is the **Workflow**. Each workflow is a complete end-to-end translation pipeline designed for a specific file type. Instead of interacting with large classes as before, you will select and configure the appropriate workflow according to the file type. The core of the new DocuTranslate is the **Workflow**. Each workflow is a complete, end-to-end translation pipeline designed specifically for a particular file type. You no longer interact with a monolithic class; instead, you select and configure a suitable workflow based on your file type.
**The basic usage steps are as follows:** **The basic usage process is as follows:**
1. **Select a Workflow**: Choose a workflow based on the input file type (e.g., PDF/Word or TXT). For example, `MarkdownBasedWorkflow` or `TXTWorkflow`. 1. **Select a Workflow**: Choose a workflow based on your input file type (e.g., PDF/Word or TXT), such as `MarkdownBasedWorkflow` or `TXTWorkflow`.
2. **Build Configuration**: Create a configuration object corresponding to the selected workflow (such as `MarkdownBasedWorkflowConfig`). This configuration object contains all the necessary sub-configurations, such as: 2. **Build the Configuration**: Create the corresponding configuration object for the selected workflow (e.g., `MarkdownBasedWorkflowConfig`). This configuration object contains all the necessary sub-configurations, such as:
* **Converter Config**: Defines how to convert the original file (e.g., PDF) to Markdown. * **Converter Config**: Defines how to convert the original file (e.g., PDF) to Markdown.
* **Translator Config**: Defines the LLM to use, API-Key, target language, etc. * **Translator Config**: Defines which LLM, API-Key, target language, etc., to use.
* **Exporter Config**: Defines specific options for the output format (e.g., HTML). * **Exporter Config**: Defines specific options for the output format (e.g., HTML).
3. **Instantiate the Workflow**: Create an instance of the workflow using the configuration object. 3. **Instantiate the Workflow**: Create a workflow instance using the configuration object.
4. **Execute Translation**: Call the workflow's `.read_*()` method and `.translate()` / `.translate_async()` method. 4. **Execute the Translation**: Call the workflow's `.read_*()` and `.translate()` / `.translate_async()` methods.
5. **Export/Save Results**: Call the `.export_to_*()` method or `.save_as_*()` method to retrieve or save the translation results. 5. **Export/Save the Result**: Call the `.export_to_*()` or `.save_as_*()` methods to get or save the translation result.
## Available Workflows ## Available Workflows
| Workflow | Application Scenario | Input Format | Output Format | Core Configuration Class | | Workflow | Use Case | Input Formats | Output Formats | Core Config Class |
|:---------------------------|:-------------------------------------------------------------------------------------|:-------------------------------------------|:-----------------------|:----------------------------------| |:---|:---|:---|:---|:---|
| **`MarkdownBasedWorkflow`** | Process rich text documents such as PDF, Word, and images. Flow: `File -> Markdown -> Translation -> Export`. | `.pdf`, `.docx`, `.md`, `.png`, `.jpg`, etc. | `.md`, `.zip`, `.html` | `MarkdownBasedWorkflowConfig` | | **`MarkdownBasedWorkflow`** | Processes rich text documents like PDF, Word, images, etc. The process is: `File -> Markdown -> Translate -> Export`. | `.pdf`, `.docx`, `.md`, `.png`, `.jpg`, etc. | `.md`, `.zip`, `.html` | `MarkdownBasedWorkflowConfig` |
| **`TXTWorkflow`** | Process plain text documents. Flow: `txt -> Translation -> Export`. | `.txt` and other plain text formats | `.txt`, `.html` | `TXTWorkflowConfig` | | **`TXTWorkflow`** | Processes plain text documents. The process is: `txt -> Translate -> Export`. | `.txt` and other plain text formats | `.txt`, `.html` | `TXTWorkflowConfig` |
| **`JsonWorkflow`** | Process json files. Flow: `json -> Translation -> Export`. | `.json` | `.json`, `.html` | `JsonWorkflowConfig` | | **`JsonWorkflow`** | Processes JSON files. The process is: `json -> Translate -> Export`. | `.json` | `.json`, `.html` | `JsonWorkflowConfig` |
| **`DocxWorkflow`** | Process docx files. Flow: `docx -> Translation -> Export`. | `.docx` | `.docx`, `.html` | `docxWorkflowConfig` | | **`DocxWorkflow`** | Processes docx files. The process is: `docx -> Translate -> Export`. | `.docx` | `.docx`, `.html` | `docxWorkflowConfig` |
| **`XlsxWorkflow`** | Process xlsx files. Flow: `xlsx -> Translation -> Export`. | `.xlsx` | `.xlsx`, `.html` | `XlsxWorkflowConfig` | | **`XlsxWorkflow`** | Processes xlsx files. The process is: `xlsx -> Translate -> Export`. | `.xlsx`, `.csv` | `.xlsx`, `.html` | `XlsxWorkflowConfig` |
| **`SrtWorkflow`** | Process srt files. Flow: `srt -> Translation -> Export`. | `.srt` | `.srt`, `.html` | `SrtWorkflowConfig` | | **`SrtWorkflow`** | Processes srt files. The process is: `srt -> Translate -> Export`. | `.srt` | `.srt`, `.html` | `SrtWorkflowConfig` |
| **`EpubWorkflow`** | Process epub files. Flow: `epub -> Translation -> Export`. | `.epub` | `.epub`, `.html` | `EpubWorkflowConfig` | | **`EpubWorkflow`** | Processes epub files. The process is: `epub -> Translate -> Export`. | `.epub` | `.epub`, `.html` | `EpubWorkflowConfig` |
| **`HtmlWorkflow`** | Process html files. Flow: `html -> Translation -> Export`. | `.html`, `.htm` | `.html` | `HtmlWorkflowConfig` | | **`HtmlWorkflow`** | Processes html files. The process is: `html -> Translate -> Export`. | `.html`, `.htm` | `.html` | `HtmlWorkflowConfig` |
> The interactive interface allows export in pdf format. > In the interactive interface, you can export to PDF format.
## Starting the Web UI and API Service ## Starting the Web UI and API Service
For ease of use, DocuTranslate provides a feature-rich web interface and RESTful API. For ease of use, DocuTranslate provides a full-featured Web interface and RESTful API.
**Starting the Service:** **Starting the Service:**
```bash ```bash
# Start the service, which monitors port 8010 by default # Start the service, listening on port 8010 by default
docutranslate -i docutranslate -i
# Start with a specified port # Start on a specific port
docutranslate -i -p 8011 docutranslate -i -p 8011
# You can also specify the port using an environment variable # You can also specify the port via an environment variable
export DOCUTRANSLATE_PORT=8011 export DOCUTRANSLATE_PORT=8011
docutranslate -i docutranslate -i
``` ```
- **Interactive Interface**: After starting the service, please visit `http://127.0.0.1:8010` (or your specified port) in your browser.
- **Interactive Interface**: After starting the service, access `http://127.0.0.1:8010` (or the specified port) in your browser.
- **API Documentation**: The complete API documentation (Swagger UI) is available at `http://127.0.0.1:8010/docs`. - **API Documentation**: The complete API documentation (Swagger UI) is available at `http://127.0.0.1:8010/docs`.
## Usage ## Usage
### Example 1: Translating a PDF File (Using `MarkdownBasedWorkflow`) ### Example 1: Translating a PDF File (using `MarkdownBasedWorkflow`)
This is the most common use case. Convert the PDF to Markdown using the `minerU` engine and translate it with an LLM. Here, we use the asynchronous method as an example. This is the most common use case. We will use the `minerU` engine to convert the PDF to Markdown, and then use an LLM for translation. Here is an example using the asynchronous approach.
```python ```python
import asyncio import asyncio
@@ -149,52 +152,52 @@ from docutranslate.exporter.md.md2html_exporter import MD2HTMLExporterConfig
async def main(): async def main():
# 1. Build translator configuration # 1. Build the translator configuration
translator_config = MDTranslatorConfig( translator_config = MDTranslatorConfig(
base_url="https://open.bigmodel.cn/api/paas/v4", # Base URL of the AI platform base_url="https://open.bigmodel.cn/api/paas/v4", # AI platform Base URL
api_key="YOUR_ZHIPU_API_KEY", # API Key of the AI platform api_key="YOUR_ZHIPU_API_KEY", # AI platform API Key
model_id="glm-4-air", # Model ID model_id="glm-4-air", # Model ID
to_lang="English", # Target language to_lang="English", # Target language
chunk_size=3000, # Text chunk size chunk_size=3000, # Text chunk size
concurrent=10 # Number of concurrent executions concurrent=10, # Concurrency
# glossary_generate_enable=True, # Enable automatic glossary generation # glossary_generate_enable=True, # Enable automatic glossary generation
# glossary_dict={"Jobs":"乔布斯"} # Pass in the glossary # glossary_dict={"Jobs":"乔布斯"} # Pass in a glossary
) )
# 2. Build converter configuration (using minerU) # 2. Build the converter configuration (using minerU)
converter_config = ConverterMineruConfig( converter_config = ConverterMineruConfig(
mineru_token="YOUR_MINERU_TOKEN", # Your minerU Token mineru_token="YOUR_MINERU_TOKEN", # Your minerU Token
formula_ocr=True # Enable formula recognition formula_ocr=True # Enable formula recognition
) )
# 3. Build main workflow configuration # 3. Build the main workflow configuration
workflow_config = MarkdownBasedWorkflowConfig( workflow_config = MarkdownBasedWorkflowConfig(
convert_engine="mineru", # Specify the parsing engine convert_engine="mineru", # Specify the parsing engine
converter_config=converter_config, # Pass the converter configuration converter_config=converter_config, # Pass in the converter configuration
translator_config=translator_config, # Pass the translator configuration translator_config=translator_config, # Pass in the translator configuration
html_exporter_config=MD2HTMLExporterConfig(cdn=True) # HTML export configuration html_exporter_config=MD2HTMLExporterConfig(cdn=True) # HTML export configuration
) )
# 4. Instantiate the workflow # 4. Instantiate the workflow
workflow = MarkdownBasedWorkflow(config=workflow_config) workflow = MarkdownBasedWorkflow(config=workflow_config)
# 5. Load the file and execute translation # 5. Read the file and execute the translation
print("Starting file loading and translation...") print("Starting to read and translate the file...")
workflow.read_path("path/to/your/document.pdf") workflow.read_path("path/to/your/document.pdf")
await workflow.translate_async() await workflow.translate_async()
# Or use the synchronous method # Or use the synchronous method
# workflow.translate() # workflow.translate()
print("Translation completed!") print("Translation complete!")
# 6. Save the results # 6. Save the results
workflow.save_as_html(name="translated_document.html") workflow.save_as_html(name="translated_document.html")
workflow.save_as_markdown_zip(name="translated_document.zip") workflow.save_as_markdown_zip(name="translated_document.zip")
workflow.save_as_markdown(name="translated_document.md") # Markdown with embedded images workflow.save_as_markdown(name="translated_document.md") # Markdown with embedded images
print("Files saved to the ./output folder.") print("Files have been saved to the ./output folder.")
# Or directly get the content string # Or get the content strings directly
html_content = workflow.export_to_html() html_content = workflow.export_to_html()
html_content = workflow.export_to_markdown() markdown_content = workflow.export_to_markdown()
# print(html_content) # print(html_content)
@@ -202,9 +205,9 @@ if __name__ == "__main__":
asyncio.run(main()) asyncio.run(main())
``` ```
### Example 2: Translating TXT Files (Using `TXTWorkflow`) ### Example 2: Translating a TXT File (using `TXTWorkflow`)
For pure text files, the process is simpler as there is no need for document parsing (conversion). Here is an example using the asynchronous method. For plain text files, the process is simpler as it doesn't require a document parsing (conversion) step. Here is an example using the asynchronous approach.
```python ```python
import asyncio import asyncio
@@ -219,7 +222,7 @@ async def main():
base_url="https://api.openai.com/v1/", base_url="https://api.openai.com/v1/",
api_key="YOUR_OPENAI_API_KEY", api_key="YOUR_OPENAI_API_KEY",
model_id="gpt-4o", model_id="gpt-4o",
to_lang="中文", to_lang="Chinese",
) )
# 2. Build the main workflow configuration # 2. Build the main workflow configuration
@@ -231,7 +234,7 @@ async def main():
# 3. Instantiate the workflow # 3. Instantiate the workflow
workflow = TXTWorkflow(config=workflow_config) workflow = TXTWorkflow(config=workflow_config)
# 4. Read the file and execute translation # 4. Read the file and execute the translation
workflow.read_path("path/to/your/notes.txt") workflow.read_path("path/to/your/notes.txt")
await workflow.translate_async() await workflow.translate_async()
# Or use the synchronous method # Or use the synchronous method
@@ -239,7 +242,7 @@ async def main():
# 5. Save the result # 5. Save the result
workflow.save_as_txt(name="translated_notes.txt") workflow.save_as_txt(name="translated_notes.txt")
print("TXT file saved.") print("TXT file has been saved.")
# You can also export the translated plain text # You can also export the translated plain text
text = workflow.export_to_txt() text = workflow.export_to_txt()
@@ -249,12 +252,9 @@ if __name__ == "__main__":
asyncio.run(main()) asyncio.run(main())
``` ```
### Example 3: Translating a JSON File (using `JsonWorkflow`)
Here is an example using the asynchronous approach. The `json_paths` item in `JsonTranslatorConfig` needs to specify the JSON paths to be translated (satisfying the `jsonpath-ng` syntax). Only values matching the JSON paths will be translated.
### Example 3: Translating a JSON file (using `JsonWorkflow`)
Here, we show an example using the asynchronous method. In the `json_paths` item of `JsonTranslatorConfig`, you need to specify the JSON paths to be translated (following the jsonpath-ng syntax rules).
Only the values matching the JSON paths will be translated.
```python ```python
import asyncio import asyncio
@@ -271,7 +271,7 @@ async def main():
api_key="YOUR_OPENAI_API_KEY", api_key="YOUR_OPENAI_API_KEY",
model_id="gpt-4o", model_id="gpt-4o",
to_lang="Chinese", to_lang="Chinese",
json_paths=["$.*", "$.name"] # Compliant with the jsonpath-ng path syntax; all values matching the path will be translated json_paths=["$.*", "$.name"] # Satisfies jsonpath-ng syntax, values at matching paths will be translated
) )
# 2. Build the main workflow configuration # 2. Build the main workflow configuration
@@ -283,17 +283,17 @@ async def main():
# 3. Instantiate the workflow # 3. Instantiate the workflow
workflow = JsonWorkflow(config=workflow_config) workflow = JsonWorkflow(config=workflow_config)
# 4. Read the file and execute translation # 4. Read the file and execute the translation
workflow.read_path("path/to/your/notes.json") workflow.read_path("path/to/your/notes.json")
await workflow.translate_async() await workflow.translate_async()
# Or use the synchronous method # Or use the synchronous method
# workflow.translate() # workflow.translate()
# 5. Save the results # 5. Save the result
workflow.save_as_json(name="translated_notes.json") workflow.save_as_json(name="translated_notes.json")
print("The JSON file has been saved.") print("JSON file has been saved.")
# You can also export the translated json text # You can also export the translated JSON text
text = workflow.export_to_json() text = workflow.export_to_json()
@@ -301,11 +301,9 @@ if __name__ == "__main__":
asyncio.run(main()) asyncio.run(main())
``` ```
### Example 4: Translating a docx File (using `DocxWorkflow`)
Here is an example using the asynchronous approach.
### Example 4: Translating a docx File (Using `DocxWorkflow`)
Here, the asynchronous method is shown as an example.
```python ```python
import asyncio import asyncio
@@ -321,8 +319,8 @@ async def main():
base_url="https://api.openai.com/v1/", base_url="https://api.openai.com/v1/",
api_key="YOUR_OPENAI_API_KEY", api_key="YOUR_OPENAI_API_KEY",
model_id="gpt-4o", model_id="gpt-4o",
to_lang="日本語", to_lang="Chinese",
insert_mode="replace", # Optional: "replace", "append", "prepend" insert_mode="replace", # Options: "replace", "append", "prepend"
separator="\n", # Separator used in "append" and "prepend" modes separator="\n", # Separator used in "append" and "prepend" modes
) )
@@ -335,7 +333,7 @@ async def main():
# 3. Instantiate the workflow # 3. Instantiate the workflow
workflow = DocxWorkflow(config=workflow_config) workflow = DocxWorkflow(config=workflow_config)
# 4. Load the file and execute translation # 4. Read the file and execute the translation
workflow.read_path("path/to/your/notes.docx") workflow.read_path("path/to/your/notes.docx")
await workflow.translate_async() await workflow.translate_async()
# Or use the synchronous method # Or use the synchronous method
@@ -343,7 +341,7 @@ async def main():
# 5. Save the result # 5. Save the result
workflow.save_as_docx(name="translated_notes.docx") workflow.save_as_docx(name="translated_notes.docx")
print("The docx file has been saved.") print("docx file has been saved.")
# You can also export the translated docx as binary # You can also export the translated docx as binary
text_bytes = workflow.export_to_docx() text_bytes = workflow.export_to_docx()
@@ -353,11 +351,9 @@ if __name__ == "__main__":
asyncio.run(main()) asyncio.run(main())
``` ```
### Example 5: Translating a xlsx File (using `XlsxWorkflow`)
Here is an example using the asynchronous approach.
### Example 5: Translating an xlsx file (using `XlsxWorkflow`)
Here, we will use the asynchronous method as an example.
```python ```python
import asyncio import asyncio
@@ -373,8 +369,8 @@ async def main():
base_url="https://api.openai.com/v1/", base_url="https://api.openai.com/v1/",
api_key="YOUR_OPENAI_API_KEY", api_key="YOUR_OPENAI_API_KEY",
model_id="gpt-4o", model_id="gpt-4o",
to_lang="日本語", to_lang="Chinese",
insert_mode="replace", # Optional: "replace", "append", "prepend" insert_mode="replace", # Options: "replace", "append", "prepend"
separator="\n", # Separator used in "append" and "prepend" modes separator="\n", # Separator used in "append" and "prepend" modes
) )
@@ -387,7 +383,7 @@ async def main():
# 3. Instantiate the workflow # 3. Instantiate the workflow
workflow = XlsxWorkflow(config=workflow_config) workflow = XlsxWorkflow(config=workflow_config)
# 4. Load the file and execute translation # 4. Read the file and execute the translation
workflow.read_path("path/to/your/notes.xlsx") workflow.read_path("path/to/your/notes.xlsx")
await workflow.translate_async() await workflow.translate_async()
# Or use the synchronous method # Or use the synchronous method
@@ -395,9 +391,9 @@ async def main():
# 5. Save the result # 5. Save the result
workflow.save_as_xlsx(name="translated_notes.xlsx") workflow.save_as_xlsx(name="translated_notes.xlsx")
print("The XLSX file has been saved.") print("xlsx file has been saved.")
# You can also export the binary data of the translated XLSX # You can also export the translated xlsx as binary
text_bytes = workflow.export_to_xlsx() text_bytes = workflow.export_to_xlsx()
@@ -405,81 +401,69 @@ if __name__ == "__main__":
asyncio.run(main()) asyncio.run(main())
``` ```
## Prerequisites and Configuration Details
### 1. Get a Large Language Model API Key
## Detailed Explanation of Prerequisites and Settings The translation functionality relies on large language models. You need to obtain a `base_url`, `api_key`, and `model_id` from the respective AI platform.
### 1. Obtaining a Large Language Model API Key > Recommended models: Volcengine's `doubao-seed-1-6-250615`, `doubao-seed-1-6-flash-250715`, Zhipu's `glm-4-flash`, Alibaba Cloud's `qwen-plus`, `qwen-turbo`, Deepseek's `deepseek-chat`, etc.
The translation function relies on a large language model, and you need to obtain the `base_url`, `api_key`, and `model_id` from the corresponding AI platform. | Platform Name | Get API Key | baseurl |
|---|---|---|
| ollama | | http://127.0.0.1:11434/v1 |
| lm studio | | http://127.0.0.1:1234/v1 |
| openrouter | [Click to get](https://openrouter.ai/settings/keys) | https://openrouter.ai/api/v1 |
| openai | [Click to get](https://platform.openai.com/api-keys) | https://api.openai.com/v1/ |
| gemini | [Click to get](https://aistudio.google.com/u/0/apikey) | https://generativelanguage.googleapis.com/v1beta/openai/ |
| deepseek | [Click to get](https://platform.deepseek.com/api_keys) | https://api.deepseek.com/v1 |
| Zhipu AI | [Click to get](https://open.bigmodel.cn/usercenter/apikeys) | https://open.bigmodel.cn/api/paas/v4 |
| Tencent Hunyuan | [Click to get](https://console.cloud.tencent.com/hunyuan/api-key) | https://api.hunyuan.cloud.tencent.com/v1 |
| Alibaba Cloud Bailian | [Click to get](https://bailian.console.aliyun.com/?tab=model#/api-key) | https://dashscope.aliyuncs.com/compatible-mode/v1 |
| Volcengine | [Click to get](https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey?apikey=%7B%7D) | https://ark.cn-beijing.volces.com/api/v3 |
| SiliconFlow | [Click to get](https://cloud.siliconflow.cn/account/ak) | https://api.siliconflow.cn/v1 |
| DMXAPI | [Click to get](https://www.dmxapi.cn/token) | https://www.dmxapi.cn/v1 |
> Recommended models: Volcano Engine's `doubao-seed-1-6-250615`, `doubao-seed-1-6-flash-250715`, Zhipu's `glm-4-flash`, Alibaba Cloud's `qwen-plus`, `qwen-turbo`, DeepSeek's `deepseek-chat`, etc. ### 2. PDF Parsing Engine (ignore if not translating PDFs)
| Platform Name | Method to Obtain API Key | baseurl | ### 2.1 Get a minerU Token (online PDF parsing, free, recommended)
|------------|-----------------------------------------------------------------------------------|----------------------------------------------------------|
| ollama | | http://127.0.0.1:11434/v1 |
| lm studio | | http://127.0.0.1:1234/v1 |
| openrouter | [Click to Obtain](https://openrouter.ai/settings/keys) | https://openrouter.ai/api/v1 |
| openai | [Click to Obtain](https://platform.openai.com/api-keys) | https://api.openai.com/v1/ |
| gemini | [Click to Obtain](https://aistudio.google.com/u/0/apikey) | https://generativelanguage.googleapis.com/v1beta/openai/ |
| deepseek | [Click to Obtain](https://platform.deepseek.com/api_keys) | https://api.deepseek.com/v1 |
| 智譜ai | [Click to Obtain](https://open.bigmodel.cn/usercenter/apikeys) | https://open.bigmodel.cn/api/paas/v4 |
| 騰訊混元 | [Click to Obtain](https://console.cloud.tencent.com/hunyuan/api-key) | https://api.hunyuan.cloud.tencent.com/v1 |
| 阿里云百煉 | [Click to Obtain](https://bailian.console.aliyun.com/?tab=model#/api-key) | https://dashscope.aliyuncs.com/compatible-mode/v1 |
| 火山引擎 | [Click to Obtain](https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey?apikey=%7B%7D) | https://ark.cn-beijing.volces.com/api/v3 |
| 硅基流動 | [Click to Obtain](https://cloud.siliconflow.cn/account/ak) | https://api.siliconflow.cn/v1 |
| DMXAPI | [Click to Obtain](https://www.dmxapi.cn/token) | https://www.dmxapi.cn/v1 |
### 2. Obtaining minerU Token (Online Parsing) If you choose `mineru` as the document parsing engine (`convert_engine="mineru"`), you need to apply for a free token.
If you select `mineru` as the document parsing engine (`convert_engine="mineru"`), you need to apply for a free Token. 1. Visit the [minerU official website](https://mineru.net/apiManage/docs) to register and apply for an API.
2. Create a new API Token in the [API Token management interface](https://mineru.net/apiManage/token).
1. Visit the [minerU official website](https://mineru.net/apiManage/docs), register, and apply for the API. > **Note**: minerU tokens have a 14-day validity period. Please re-create them after they expire.
2. Create a new API Token on the [API Token management page](https://mineru.net/apiManage/token).
> **Note**: The minerU Token is valid for 14 days. If it expires, please recreate it. ### 2.2. docling Engine Configuration (local PDF parsing)
### 3. Configuring the docling Engine (Local Parsing) If you choose `docling` as the document parsing engine (`convert_engine="docling"`), it will download the required models from Hugging Face on first use.
If you select `docling` as the document parsing engine (`convert_engine="docling"`), the required models will be downloaded from Hugging Face during the first use. > A better option is to download `docling_artifact.zip` from [GitHub releases](https://github.com/xunbu/docutranslate/releases) and unzip it to your working directory.
**Solutions for Network Issues:** **Solution for network issues when downloading `docling` models:**
1. **Setting up a Hugging Face Mirror (Recommended)**: 1. **Set a Hugging Face mirror (recommended)**:
* **Method A (environment variable)**: Set the system environment variable `HF_ENDPOINT` and restart your IDE or terminal.
* **Method A (Environment Variable)**: Set the system environment variable `HF_ENDPOINT` and restart your IDE or terminal. ```
```
HF_ENDPOINT=https://hf-mirror.com HF_ENDPOINT=https://hf-mirror.com
``` ```
* **Method B (set in code)**: Add the following code at the beginning of your Python script.
* **Method B (Setting in Code)**: Add the following code at the beginning of your Python script.
```python ```python
import os import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com' os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
``` ```
2. **Offline use (download the model package in advance)**:
2. **Offline Use (Download Model Packages in Advance)**:
* Download `docling_artifact.zip` from [GitHub Releases](https://github.com/xunbu/docutranslate/releases). * Download `docling_artifact.zip` from [GitHub Releases](https://github.com/xunbu/docutranslate/releases).
* Extract it to your project directory. * Unzip it to your project directory.
* Specify the model path in the configuration: * Specify the model path in the configuration (if the model is not in the same directory as the script):
```python ```python
from docutranslate.converter.x2md.converter_docling import ConverterDoclingConfig from docutranslate.converter.x2md.converter_docling import ConverterDoclingConfig
converter_config = ConverterDoclingConfig( converter_config = ConverterDoclingConfig(
artifact="./docling_artifact", # Specify the extracted folder artifact="./docling_artifact", # Point to the unzipped folder
code_ocr=True, code_ocr=True,
formula_ocr=True formula_ocr=True
) )
@@ -487,26 +471,26 @@ converter_config = ConverterDoclingConfig(
## FAQ ## FAQ
**Q: What should I do if port 8010 is occupied?** **Q: What if port 8010 is occupied?**
A: Specify a new port using the `-p` parameter or set the `DOCUTRANSLATE_PORT` environment variable. A: Use the `-p` parameter to specify a new port, or set the `DOCUTRANSLATE_PORT` environment variable.
**Q: Is translation of scanned documents supported?** **Q: Does it support translation of scanned PDFs?**
A: Yes, it is supported. Please use the `mineru` parsing engine, which is equipped with powerful OCR capabilities. A: Yes. Please use the `mineru` parsing engine, which has powerful OCR capabilities.
**Q: Why is it slow on first use?** **Q: Why is the first PDF translation so slow?**
A: When using the `docling` engine, the model needs to be downloaded from Hugging Face during the first run. To speed up this process, refer to the "Solutions for Network Issues" section above. A: If you are using the `docling` engine, it needs to download models from Hugging Face on its first run. Please refer to the "Network Issues Solution" above to speed up this process.
**Q: How can it be used in an intranet (offline) environment?** **Q: How to use it in an intranet (offline) environment?**
A: It is completely possible. The following two conditions need to be met: A: It is entirely possible. You need to meet the following conditions:
1. **Local Parsing Engine**: Use the `docling` engine and download the model package in advance according to the "Offline Use" guide above. 1. **Local LLM**: Use tools like [Ollama](https://ollama.com/) or [LM Studio](https://lmstudio.ai/) to deploy a language model locally, and fill in the `base_url` of the local model in `TranslatorConfig`.
2. **Local LLM**: Deploy a language model locally using tools such as [Ollama](https://ollama.com/) or [LM Studio](https://lmstudio.ai/), and enter the `base_url` of the local model in `TranslatorConfig`. 2. **Local PDF parsing engine** (only needed for parsing PDFs): Use the `docling` engine and follow the "Offline use" instructions above to download the model package in advance.
**Q: How does the caching mechanism work?** **Q: How does the PDF parsing cache mechanism work?**
A: `MarkdownBasedWorkflow` automatically caches the results of document parsing (conversion from files to Markdown) to avoid wasting time and resources on repeated parsing. The cache is stored in memory by default and records the most recent 10 parsing operations. The number of cached items can be changed via the `DOCUTRANSLATE_CACHE_NUM` environment variable. A: `MarkdownBasedWorkflow` automatically caches the results of document parsing (file to Markdown conversion) to avoid repeated parsing that consumes time and resources. The cache is stored in memory by default and records the last 10 parses. You can modify the cache size using the `DOCUTRANSLATE_CACHE_NUM` environment variable.
**Q: How can I use the software via a proxy?** **Q: How to make the software go through a proxy?**
A: The software does not use a proxy by default. Set the `DOCUTRANSLATE_PROXY_ENABLED` environment variable to `true` to enable communication via a proxy. A: The software does not use a proxy by default. You can enable it by setting the environment variable `DOCUTRANSLATE_PROXY_ENABLED` to `true`.
## Star History ## Star History

350
README_JP.md
View File

@@ -1,79 +1,85 @@
<center> <p align="center">
<img src="./DocuTranslate.png" alt="プロジェクトロゴ" style="width: 150px"> <img src="./DocuTranslate.png" alt="プロジェクトロゴ" style="width: 150px">
</center> </p>
# DocuTranslate <h1 align="center">DocuTranslate</h1>
[![GitHub stars](https://img.shields.io/github/stars/xunbu/docutranslate?style=flats&logo=github&color=blue)](https://github.com/xunbu/docutranslate) <p align="center">
[![github下载数](https://img.shields.io/github/downloads/xunbu/docutranslate/total?logo=github)](https://github.com/xunbu/docutranslate/releases) <a href="https://github.com/xunbu/docutranslate/stargazers"><img src="https://img.shields.io/github/stars/xunbu/docutranslate?style=flat-square&logo=github&color=blue" alt="GitHubスター"></a>
[![PyPI version](https://img.shields.io/pypi/v/docutranslate)](https://pypi.org/project/docutranslate/) <a href="https://github.com/xunbu/docutranslate/releases"><img src="https://img.shields.io/github/downloads/xunbu/docutranslate/total?logo=github&style=flat-square" alt="GitHubダウンロード数"></a>
[![python版本](https://img.shields.io/badge/Python-3.11+-3776AB?logo=python&logoColor=white)](https://www.python.org/) <a href="https://pypi.org/project/docutranslate/"><img src="https://img.shields.io/pypi/v/docutranslate?style=flat-square" alt="PyPIバージョン"></a>
[![开源协议](https://img.shields.io/github/license/xunbu/docutranslate)](./LICENSE) <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.11+-3776AB?logo=python&logoColor=white&style=flat-square" alt="Pythonバージョン"></a>
<a href="./LICENSE"><img src="https://img.shields.io/github/license/xunbu/docutranslate?style=flat-square" alt="ライセンス"></a>
</p>
[**简体中文**](/README_ZH.md) / [**English**](/README.md) / [**日本語**](/README_JP.md) <p align="center">
<a href="/README_ZH.md"><strong>简体中文</strong></a> / <a href="/README.md"><strong>English</strong></a> / <a href="/README_JP.md"><strong>日本語</strong></a>
</p>
**DocuTranslate** はファイル翻訳ツールで、[docling](https://github.com/docling-project/docling)や[minerU](https://mineru.net/)などの最先端の文書解析エンジンと大型言語モデル(LLM)を組み合わせ、さまざまな形式の文書を正確に翻訳します。 <p align="center">
大規模言語モデル（LLM）をベースにした、超軽量なローカルファイル翻訳ツール。正確、高速、かつ拡張可能な翻訳体験を提供することを目指しています。
</p>
新しいバージョンのアーキテクチャは **ワークフロー(Workflow)** をコアとし、さまざまな種類の翻訳タスクに高いカスタマイズ性と拡張性を提供するソリューションを実現しています。 - ✅ **多様なフォーマットをサポート**：`pdf`、`docx`、`xlsx`、`md`、`txt`、`json`、`epub`、`srt` など、さまざまなファイルを翻訳できます。
- ✅ **用語集の自動生成**：用語集を自動生成し、専門用語の統一を実現します。
- ✅ **PDFの表、数式、コード認識**：`docling`、`mineru` PDF解析エンジンにより、学術論文によく見られる表、数式、コードを認識し、翻訳します。
- ✅ **JSON翻訳**：JSON Path (`jsonpath-ng`構文仕様) を用いて、翻訳対象の値を指定できます。
- ✅ **Word/Excelのフォーマットを維持した翻訳**：`docx`、`xlsx`ファイルの元のフォーマットを維持したまま翻訳をサポートします（現在`doc`、`xls`ファイルは未対応）。
- ✅ **マルチAIプラットフォーム対応**：ほとんどのAIプラットフォームをサポートし、カスタムプロンプトによる並列・高性能なAI翻訳を実現します。
- ✅ **非同期サポート**：高性能なシーン向けに設計され、完全な非同期サポートを提供し、マルチタスク並列処理が可能なサービスインターフェースを実現しています。
- ✅ **LAN、複数人利用をサポート**：LAN内での複数人による同時利用をサポートします。
- ✅ **インタラクティブなWeb UI**：すぐに使えるWeb UIとRESTful APIを提供し、統合や利用が容易です。
- ✅ **小容量・マルチプラットフォーム対応の簡単パッケージ**：40MB未満のWindows、Mac用簡単パッケージ（`docling`によるローカルPDF解析を使用しないバージョン）。
- ✅ **多形式ファイル対応**: `pdf`、`docx`、`xlsx`、`md`、`txt`、`json`、`epub`、`srt`など様々なファイル形式の翻訳が可能です。 > `pdf`を翻訳する際、一度Markdownに変換されるため、元のレイアウトが**失われます**。レイアウトを重視するユーザーはご注意ください。
- ✅ **表・数式・コード認識**: `docling`および`mineru`を活用し、学術論文で頻出する表、数式、コードの認識と翻訳を実現。
- ✅ **用語集の自動作成**: 用語の統一を実現するための用語集自動作成機能をサポート。
- ✅ **JSON翻訳**: JSONPath（`jsonpath-ng`構文規格）を用いて翻訳対象の値を指定可能。
- ✅ **Word/Excel高精度翻訳**: `docx`、`xlsx`ファイル（現在`doc`、`xls`ファイルは非対応）の元の書式を保持した翻訳をサポート。
- ✅ **複数AIプラットフォーム対応**: 主要なAIプラットフォームのほとんどに対応し、カスタムプロンプトを用いた高並列パフォーマンスAI翻訳を実現。
- ✅ **非同期処理対応**: 高性能シナリオ向けに設計された非同期処理を完全サポート。並列処理可能なサービスインターフェースを実装。
- ✅ **対話型Webインターフェース**: すぐに利用可能なWeb UIとRESTful APIを提供し、容易な統合と使用を実現。
> `pdf`や`html`などのファイルを翻訳する場合、まずmarkdownに変換されます。このため、元のレイアウトが**失われる可能性があります**。レイアウトに厳しい要件があるユーザーはご注意ください。
> QQ交流グループ：1047781902 > QQ交流グループ：1047781902
**UIインターフェース**： **UI画面**：
![翻译效果](/images/UI界面.png) ![翻訳効果](/images/UI界面.png)
**論文翻訳**： **論文翻訳**：
![翻译效果](/images/论文翻译.png) ![翻訳効果](/images/論文翻訳.png)
**小説翻訳**： **小説翻訳**：
![翻译效果](/images/小说翻译.png) ![翻訳効果](/images/小説翻訳.png)
## 統合パッケージ ## 統合パッケージ
早速使い始めたいユーザーのために、GitHub Releases(https://github.com/xunbu/docutranslate/releases)に統合パッケージを提供しています。ダウンロードして解凍し、AIプラットフォームのAPI-Keyを入力するだけで使用を開始できます。 すぐに使い始めたいユーザーのために、[GitHub Releases](https://github.com/xunbu/docutranslate/releases) で統合パッケージを提供しています。ダウンロードして解凍し、お使いのAIプラットフォームのAPIキーを入力するだけで使用を開始できます。
- **DocuTranslate**：標準版で、オンラインの`minerU`エンジンを使用して文書を解析し、ほとんどのユーザーにおすすめします。 - **DocuTranslate**: 標準版。オンラインの`minerU`エンジンを使用してPDFドキュメントを解析します。ローカルでのPDF解析が不要な場合はこちらを選択してください（推奨）。
- **DocuTranslate_full**：完全版で、ローカルの`docling`解析エンジンを組み込み、オフライン使用やデータプライバシーに高い要件があるシーンをサポートします。 - **DocuTranslate_full**: 完全版。`docling`ローカルPDF解析エンジンを内蔵しています。ローカルでのPDF解析が必要な場合はこちらを選択してください。
## インストール ## インストール
### pipを使う ### pipを使用
```bash ```bash
# ベースインストール # 基本インストール
pip install docutranslate pip install docutranslate
# doclingローカル解析エンジンを使用する場合 # doclingでローカルPDF解析を使用する場合
pip install docutranslate[docling] pip install docutranslate[docling]
``` ```
### uvを使う ### uvを使用
```bash ```bash
# 環境を初期化 # 環境の初期化
uv init uv init
# ベースインストール # 基本インストール
uv add docutranslate uv add docutranslate
# docling拡張をインストール # docling拡張機能のインストール
uv add docutranslate[docling] uv add docutranslate[docling]
``` ```
### gitを使う ### gitを使用
```bash ```bash
# 環境を初期化 # 環境の初期化
git clone https://github.com/xunbu/docutranslate.git git clone https://github.com/xunbu/docutranslate.git
cd docutranslate cd docutranslate
@@ -82,61 +88,62 @@ uv sync
``` ```
## コアコンセプト：ワークフロー (Workflow) ## 中心的な概念：ワークフロー (Workflow)
新しいDocuTranslateのコアは**ワークフロー (Workflow)** です。各ワークフローは、特定のファイルタイプ向けに設計された完全なエンドツーエンド翻訳パイプラインです。あなたはもはや巨大なクラスと対話するのではなく、ファイルタイプに基づいて適切なワークフローを選択して設定します。 新バージョンのDocuTranslateの核心は**ワークフロー (Workflow)**です。各ワークフローは、特定のファイルタイプ専用に設計された、完全なエンドツーエンドの翻訳パイプラインです。もはや巨大なクラスと対話するのではなく、ファイルタイプに応じて適切なワークフローを選択し、設定します。
**基本的な使用フローは以下の通りです：** **基本的な使用手順は以下の通りです：**
1. **ワークフローを選択**：入力ファイルタイプ（例：PDF/Word または TXT）に基づいて、`MarkdownBasedWorkflow` や `TXTWorkflow` などのワークフローを選択します。 1. **ワークフローの選択**：入力ファイルの種類（例：PDF/WordまたはTXT）に応じて、`MarkdownBasedWorkflow`や`TXTWorkflow`などのワークフローを選択します。
2. **設定を構築**：選択したワークフローに対応する設定オブジェクト（例：`MarkdownBasedWorkflowConfig`）を作成します。この設定オブジェクトには、すべての必要なサブ設定が含まれています。例えば： 2. **設定の構築**：選択したワークフローに対応する設定オブジェクト（例：`MarkdownBasedWorkflowConfig`）を作成します。この設定オブジェクトには、必要なすべてのサブ設定が含まれています。
* **コンバーター設定 (Converter Config)**：元のファイル（例：PDF）を Markdown に変換する方法を定義します。 * **コンバータ設定 (Converter Config)**: 元のファイル（例：PDF）をMarkdownに変換する方法を定義します。
* **翻訳機設定 (Translator Config)**：使用する LLM、API-Key、ターゲット言語などを定義します。 * **翻訳機設定 (Translator Config)**: 使用するLLM、APIキー、ターゲット言語などを定義します。
* **エクスポーター設定 (Exporter Config)**：出力フォーマット（例：HTML）の特定のオプションを定義します。 * **エクスポータ設定 (Exporter Config)**: 出力フォーマット（例：HTML）の特定のオプションを定義します。
3. **ワークフローのインスタンス化**：設定オブジェクトを使用してワークフローのインスタンスを作成します。 3. **ワークフローのインスタンス化**：設定オブジェクトを使用してワークフローのインスタンスを作成します。
4. **翻訳を実行**：ワークフローの `.read_*()` および `.translate()` / `.translate_async()` メソッドを呼び出します。 4. **翻訳の実行**：ワークフローの`.read_*()`および`.translate()` / `.translate_async()`メソッドを呼び出します。
5. **結果のエクスポート/保存**：`.export_to_*()` または `.save_as_*()` メソッドを呼び出して、翻訳結果を取得または保存します。 5. **結果のエクスポート/保存**：`.export_to_*()`または`.save_as_*()`メソッドを呼び出して、翻訳結果を取得または保存します。
## 利用可能なワークフロー ## 利用可能なワークフロー
| ワークフロー | 適用シーン | 入力フォーマット | 出力フォーマット | コア設定クラス | | ワークフロー | 適用シーン | 入力フォーマット | 出力フォーマット | 主要設定クラス |
|:------------------------------|:-------------------------------------------------------|:--------------------------------------------|:--------------------------|:----------------------------| | :--- | :--- | :--- | :--- | :--- |
| **`MarkdownBasedWorkflow`** | リッチドキュメントを処理します。例えば、PDF、Word、画像など。フローは次の通り：`ファイル -> Markdown -> 翻訳 -> エクスポート`。 | `.pdf`, `.docx`, `.md`, `.png`, `.jpg` など | `.md`, `.zip`, `.html` | `MarkdownBasedWorkflowConfig` | | **`MarkdownBasedWorkflow`** | PDF、Word、画像などのリッチテキストドキュメントを処理。フロー：`ファイル -> Markdown -> 翻訳 -> エクスポート`。 | `.pdf`, `.docx`, `.md`, `.png`, `.jpg` など | `.md`, `.zip`, `.html` | `MarkdownBasedWorkflowConfig` |
| **`TXTWorkflow`** | テキストファイルを処理します。フローは次の通り：`txt -> 翻訳 -> エクスポート`。 | `.txt` 及びその他のテキスト形式 | `.txt`, `.html` | `TXTWorkflowConfig` | | **`TXTWorkflow`** | プレーンテキストドキュメントを処理。フロー：`txt -> 翻訳 -> エクスポート`。 | `.txt` およびその他のプレーンテキスト形式 | `.txt`, `.html` | `TXTWorkflowConfig` |
| **`JsonWorkflow`** | JSONファイルを処理します。フローは次の通り：`json -> 翻訳 -> エクスポート`。 | `.json` | `.json`, `.html` | `JsonWorkflowConfig` | | **`JsonWorkflow`** | JSONファイルを処理。フロー：`json -> 翻訳 -> エクスポート`。 | `.json` | `.json`, `.html` | `JsonWorkflowConfig` |
| **`DocxWorkflow`** | DOCXファイルを処理します。フローは次の通り：`docx -> 翻訳 -> エクスポート`。 | `.docx` | `.docx`, `.html` | `docxWorkflowConfig` | | **`DocxWorkflow`** | DOCXファイルを処理。フロー：`docx -> 翻訳 -> エクスポート`。 | `.docx` | `.docx`, `.html` | `docxWorkflowConfig` |
| **`XlsxWorkflow`** | XLSXファイルを処理します。フローは次の通り：`xlsx -> 翻訳 -> エクスポート`。 | `.xlsx` | `.xlsx`, `.html` | `XlsxWorkflowConfig` | | **`XlsxWorkflow`** | XLSXファイルを処理。フロー：`xlsx -> 翻訳 -> エクスポート`。 | `.xlsx`、`.csv` | `.xlsx`, `.html` | `XlsxWorkflowConfig` |
| **`SrtWorkflow`** | SRTファイルを処理します。フローは次の通り：`srt -> 翻訳 -> エクスポート`。 | `.srt` | `.srt`, `.html` | `SrtWorkflowConfig` | | **`SrtWorkflow`** | SRTファイルを処理。フロー：`srt -> 翻訳 -> エクスポート`。 | `.srt` | `.srt`, `.html` | `SrtWorkflowConfig` |
| **`EpubWorkflow`** | EPUBファイルを処理します。フローは次の通り：`epub -> 翻訳 -> エクスポート`。 | `.epub` | `.epub`, `.html` | `EpubWorkflowConfig` | | **`EpubWorkflow`** | EPUBファイルを処理。フロー：`epub -> 翻訳 -> エクスポート`。 | `.epub` | `.epub`, `.html` | `EpubWorkflowConfig` |
| **`HtmlWorkflow`** | HTMLファイルを処理。フロー：`html -> 翻訳 -> エクスポート`。 | `.html`, `.htm` | `.html` | `HtmlWorkflowConfig` |
> インタラクティブなインターフェースではPDF形式にエクスポートできます > インタラクティブUIではPDF形式でのエクスポートが可能です
## Web UI と API サービスの起動 ## Web UIとAPIサービスの起動
使いやすさのために、DocuTranslateには機能豊富なWebインターフェースとRESTful APIが用意されています。 DocuTranslateは、使いやすさを考慮して、フル機能のWebインターフェースとRESTful APIを提供しています。
**サービスの起動:** **サービスの起動:**
```bash ```bash
# サービスを起動します。デフォルトでポート8010をリッスンします # サービスを起動、デフォルトはポート8010でリッスンします
docutranslate -i docutranslate -i
# ポートを指定して起動 # ポートを指定して起動
docutranslate -i -p 8011 docutranslate -i -p 8011
# 環境変数でポートを指定することもできます # 環境変数でポートを指定することも可能です
export DOCUTRANSLATE_PORT=8011 export DOCUTRANSLATE_PORT=8011
docutranslate -i docutranslate -i
``` ```
- **対話型インターフェース**: サービスを起動後、ブラウザで `http://127.0.0.1:8010` (または指定したポート) にアクセスしてください。 - **インタラクティブUI**: サービス起動後、ブラウザで `http://127.0.0.1:8010` (または指定したポート) にアクセスしてください。
- **APIドキュメント**: 完全なAPIドキュメント（Swagger UI）は `http://127.0.0.1:8010/docs` にあります。 - **APIドキュメント**: 完全なAPIドキュメント (Swagger UI) は `http://127.0.0.1:8010/docs` にあります。
## 使用方法 ## 使用方法
### 例 1: PDFファイルを翻訳する ( `MarkdownBasedWorkflow` を使用) ### 例1: PDFファイルの翻訳 (`MarkdownBasedWorkflow`を使用)
最も一般的なユースケースです。`minerU` エンジンを使用してPDFをMarkdownに変換し、次にLLMを使用して翻訳します。ここでは非同期を例にとります。 これは最も一般的な使用例です。`minerU`エンジンを使用してPDFをMarkdownに変換し、LLMで翻訳します。ここでは非同期方式を例にとります。
```python ```python
import asyncio import asyncio
@@ -147,48 +154,48 @@ from docutranslate.exporter.md.md2html_exporter import MD2HTMLExporterConfig
async def main(): async def main():
# 1. 翻訳設定を構築 # 1. 翻訳機の設定を構築
translator_config = MDTranslatorConfig( translator_config = MDTranslatorConfig(
base_url="https://open.bigmodel.cn/api/paas/v4", # AI プラットフォームのベース URL base_url="https://open.bigmodel.cn/api/paas/v4", # AIプラットフォームのBase URL
api_key="YOUR_ZHIPU_API_KEY", # AI プラットフォームの API キー api_key="YOUR_ZHIPU_API_KEY", # AIプラットフォームのAPIキー
model_id="glm-4-air", # モデル ID model_id="glm-4-air", # モデルID
to_lang="English", # 対象言語 to_lang="English", # ターゲット言語
chunk_size=3000, # テキストのチャンクサイズ chunk_size=3000, # テキストのチャンクサイズ
concurrent=10, # 同時実行数 concurrent=10, # 並列処理数
# glossary_generate_enable=True, # 自動用語集生成を有効にする # glossary_generate_enable=True, # 用語集の自動生成を有効化
# glossary_dict={"Jobs":"乔布斯"} # 用語表を渡す # glossary_dict={"Jobs":"ジョブズ"} # 用語集を渡す
) )
# 2. コンバーター設定を構築 (minerU を使用) # 2. コンバータの設定を構築 (minerUを使用)
converter_config = ConverterMineruConfig( converter_config = ConverterMineruConfig(
mineru_token="YOUR_MINERU_TOKEN", # あなたの minerU トークン mineru_token="YOUR_MINERU_TOKEN", # あなたのminerUトークン
formula_ocr=True # 数式認識を有効化 formula_ocr=True # 数式認識を有効化
) )
# 3. メインワークフロー設定を構築 # 3. メインワークフローの設定を構築
workflow_config = MarkdownBasedWorkflowConfig( workflow_config = MarkdownBasedWorkflowConfig(
convert_engine="mineru", # 解析エンジンを指定 convert_engine="mineru", # 解析エンジンを指定
converter_config=converter_config, # コンバーター設定を渡す converter_config=converter_config, # コンバータ設定を渡す
translator_config=translator_config, # 翻訳設定を渡す translator_config=translator_config, # 翻訳機設定を渡す
html_exporter_config=MD2HTMLExporterConfig(cdn=True) # HTML エクスポート設定 html_exporter_config=MD2HTMLExporterConfig(cdn=True) # HTMLエクスポート設定
) )
# 4. ワークフローをインスタンス化 # 4. ワークフローをインスタンス化
workflow = MarkdownBasedWorkflow(config=workflow_config) workflow = MarkdownBasedWorkflow(config=workflow_config)
# 5. ファイルを読み込み翻訳を実行 # 5. ファイルを読み込み、翻訳を実行
print("ファイルの読み込みと翻訳を開始します...") print("ファイルの読み込みと翻訳を開始...")
workflow.read_path("path/to/your/document.pdf") workflow.read_path("path/to/your/document.pdf")
await workflow.translate_async() await workflow.translate_async()
# または同期方式を使用 # または同期的な方法を使用
# workflow.translate() # workflow.translate()
print("翻訳が完了しました！") print("翻訳完了！")
# 6. 結果を保存 # 6. 結果を保存
workflow.save_as_html(name="translated_document.html") workflow.save_as_html(name="translated_document.html")
workflow.save_as_markdown_zip(name="translated_document.zip") workflow.save_as_markdown_zip(name="translated_document.zip")
workflow.save_as_markdown(name="translated_document.md") # 画像埋め込みのマークダウン workflow.save_as_markdown(name="translated_document.md") # 画像が埋め込まれたMarkdown
print("ファイルが ./output フォルダに保存されました。") print("ファイルは ./output フォルダに保存されました。")
# または直接コンテンツ文字列を取得 # または直接コンテンツ文字列を取得
html_content = workflow.export_to_html() html_content = workflow.export_to_html()
@@ -200,9 +207,9 @@ if __name__ == "__main__":
asyncio.run(main()) asyncio.run(main())
``` ```
### 例 2: TXT ファイルの翻訳（`TXTWorkflow` を使用） ### 例2: TXTファイルの翻訳 (`TXTWorkflow`を使用)
プレーンテキストファイルのフローはよりシンプルです。ドキュメント解析（変換）ステップが不要だからです。以下は非同期方式の例です。 プレーンテキストファイルの場合、ドキュメント解析（変換）ステップが不要なため、プロセスはよりシンプルになります。ここでは非同期方式を例にとります。
```python ```python
import asyncio import asyncio
@@ -212,7 +219,7 @@ from docutranslate.exporter.txt.txt2html_exporter import TXT2HTMLExporterConfig
async def main(): async def main():
# 1. 翻訳者設定を構築 # 1. 翻訳機の設定を構築
translator_config = TXTTranslatorConfig( translator_config = TXTTranslatorConfig(
base_url="https://api.openai.com/v1/", base_url="https://api.openai.com/v1/",
api_key="YOUR_OPENAI_API_KEY", api_key="YOUR_OPENAI_API_KEY",
@@ -220,7 +227,7 @@ async def main():
to_lang="日本語", to_lang="日本語",
) )
# 2. メインワークフロー設定を構築 # 2. メインワークフローの設定を構築
workflow_config = TXTWorkflowConfig( workflow_config = TXTWorkflowConfig(
translator_config=translator_config, translator_config=translator_config,
html_exporter_config=TXT2HTMLExporterConfig(cdn=True) html_exporter_config=TXT2HTMLExporterConfig(cdn=True)
@@ -229,17 +236,17 @@ async def main():
# 3. ワークフローをインスタンス化 # 3. ワークフローをインスタンス化
workflow = TXTWorkflow(config=workflow_config) workflow = TXTWorkflow(config=workflow_config)
# 4. ファイルを読み込み翻訳を実行 # 4. ファイルを読み込み、翻訳を実行
workflow.read_path("path/to/your/notes.txt") workflow.read_path("path/to/your/notes.txt")
await workflow.translate_async() await workflow.translate_async()
# または同期メソッドを使用 # または同期的な方法を使用
# workflow.translate() # workflow.translate()
# 5. 結果を保存 # 5. 結果を保存
workflow.save_as_txt(name="translated_notes.txt") workflow.save_as_txt(name="translated_notes.txt")
print("TXTファイルが保存されました。") print("TXTファイルが保存されました。")
# 翻訳されたプレーンテキストをエクスポートすることも可能 # 翻訳後のプレーンテキストをエクスポートすることも可能
text = workflow.export_to_txt() text = workflow.export_to_txt()
@@ -247,9 +254,9 @@ if __name__ == "__main__":
asyncio.run(main()) asyncio.run(main())
``` ```
### 例3：JSONファイルを翻訳する（`JsonWorkflow`を使用） ### 例3: JSONファイルの翻訳 (`JsonWorkflow`を使用)
ここでは非同期方式を例に示します。JsonTranslatorConfigのjson_paths項目には、翻訳するJSONパス（jsonpath-ng構文規準に準拠）を指定する必要があり、JSONパスに一致する値のみが翻訳されます。 ここでは非同期方式を例にとります。`JsonTranslatorConfig`の`json_paths`項目で翻訳対象のJSONパスを指定する必要があります（`jsonpath-ng`構文仕様に準拠）。JSONパスにマッチした値のみが翻訳されます。
```python ```python
import asyncio import asyncio
@@ -260,16 +267,16 @@ from docutranslate.workflow.json_workflow import JsonWorkflowConfig, JsonWorkflo
async def main(): async def main():
# 1. 翻訳者設定を構築 # 1. 翻訳機の設定を構築
translator_config = JsonTranslatorConfig( translator_config = JsonTranslatorConfig(
base_url="https://api.openai.com/v1/", base_url="https://api.openai.com/v1/",
api_key="YOUR_OPENAI_API_KEY", api_key="YOUR_OPENAI_API_KEY",
model_id="gpt-4o", model_id="gpt-4o",
to_lang="日本語", to_lang="日本語",
json_paths=["$.*", "$.name"] # jsonpath-ngパス構文に準拠、一致するパスの値がすべて翻訳される json_paths=["$.*", "$.name"] # `jsonpath-ng`のパス構文に準拠し、マッチしたパスの値がすべて翻訳されます
) )
# 2. メインワークフロー設定を構築 # 2. メインワークフローの設定を構築
workflow_config = JsonWorkflowConfig( workflow_config = JsonWorkflowConfig(
translator_config=translator_config, translator_config=translator_config,
html_exporter_config=Json2HTMLExporterConfig(cdn=True) html_exporter_config=Json2HTMLExporterConfig(cdn=True)
@@ -278,17 +285,17 @@ async def main():
# 3. ワークフローをインスタンス化 # 3. ワークフローをインスタンス化
workflow = JsonWorkflow(config=workflow_config) workflow = JsonWorkflow(config=workflow_config)
# 4. ファイルを読み込み翻訳を実行 # 4. ファイルを読み込み、翻訳を実行
workflow.read_path("path/to/your/notes.json") workflow.read_path("path/to/your/notes.json")
await workflow.translate_async() await workflow.translate_async()
# または同期メソッドを使用 # または同期的な方法を使用
# workflow.translate() # workflow.translate()
# 5. 結果を保存 # 5. 結果を保存
workflow.save_as_json(name="translated_notes.json") workflow.save_as_json(name="translated_notes.json")
print("jsonファイルが保存されました。") print("JSONファイルが保存されました。")
# 翻訳されたJSONテキストをエクスポートすることも可能 # 翻訳後のJSONテキストをエクスポートすることも可能
text = workflow.export_to_json() text = workflow.export_to_json()
@@ -296,9 +303,9 @@ if __name__ == "__main__":
asyncio.run(main()) asyncio.run(main())
``` ```
### 例4：DOCXファイルを翻訳する（`DocxWorkflow`を使用） ### 例4: DOCXファイルの翻訳 (`DocxWorkflow`を使用)
ここでは非同期方式を例に説明します。 ここでは非同期方式を例にとります。
```python ```python
import asyncio import asyncio
@@ -309,14 +316,14 @@ from docutranslate.workflow.docx_workflow import DocxWorkflowConfig, DocxWorkflo
async def main(): async def main():
# 1. 翻訳器の設定を構築 # 1. 翻訳機の設定を構築
translator_config = DocxTranslatorConfig( translator_config = DocxTranslatorConfig(
base_url="https://api.openai.com/v1/", base_url="https://api.openai.com/v1/",
api_key="YOUR_OPENAI_API_KEY", api_key="YOUR_OPENAI_API_KEY",
model_id="gpt-4o", model_id="gpt-4o",
to_lang="日本語", to_lang="日本語",
insert_mode="replace", # 代替オプション "replace", "append", "prepend" insert_mode="replace", # 選択肢: "replace", "append", "prepend"
separator="\n", # "append", "prepend"モードで使用される区切り文字 separator="\n", # "append", "prepend"モードで使用する区切り文字
) )
# 2. メインワークフローの設定を構築 # 2. メインワークフローの設定を構築
@@ -331,14 +338,14 @@ async def main():
# 4. ファイルを読み込み、翻訳を実行 # 4. ファイルを読み込み、翻訳を実行
workflow.read_path("path/to/your/notes.docx") workflow.read_path("path/to/your/notes.docx")
await workflow.translate_async() await workflow.translate_async()
# または同期メソッドを使用 # または同期的な方法を使用
# workflow.translate() # workflow.translate()
# 5. 結果を保存 # 5. 結果を保存
workflow.save_as_docx(name="translated_notes.docx") workflow.save_as_docx(name="translated_notes.docx")
print("docxファイルが保存されました。") print("DOCXファイルが保存されました。")
# 翻訳後のdocxのバイナリをエクスポートすることも可能 # 翻訳後のDOCXのバイナリをエクスポートすることも可能
text_bytes = workflow.export_to_docx() text_bytes = workflow.export_to_docx()
@@ -346,9 +353,9 @@ if __name__ == "__main__":
asyncio.run(main()) asyncio.run(main())
``` ```
### 例 5: xlsxファイルの翻訳（`XlsxWorkflow`を使用） ### 例5: XLSXファイルの翻訳 (`XlsxWorkflow`を使用)
ここでは非同期方式を例に説明します。 ここでは非同期方式を例にとります。
```python ```python
import asyncio import asyncio
@@ -359,14 +366,14 @@ from docutranslate.workflow.xlsx_workflow import XlsxWorkflowConfig, XlsxWorkflo
async def main(): async def main():
# 1. 翻訳器の設定を構築 # 1. 翻訳機の設定を構築
translator_config = XlsxTranslatorConfig( translator_config = XlsxTranslatorConfig(
base_url="https://api.openai.com/v1/", base_url="https://api.openai.com/v1/",
api_key="YOUR_OPENAI_API_KEY", api_key="YOUR_OPENAI_API_KEY",
model_id="gpt-4o", model_id="gpt-4o",
to_lang="日本語", to_lang="日本語",
insert_mode="replace", # 代替オプション "replace", "append", "prepend" insert_mode="replace", # 選択肢: "replace", "append", "prepend"
separator="\n", # "append", "prepend"モードで使用される区切り文字 separator="\n", # "append", "prepend"モードで使用する区切り文字
) )
# 2. メインワークフローの設定を構築 # 2. メインワークフローの設定を構築
@@ -381,14 +388,14 @@ async def main():
# 4. ファイルを読み込み、翻訳を実行 # 4. ファイルを読み込み、翻訳を実行
workflow.read_path("path/to/your/notes.xlsx") workflow.read_path("path/to/your/notes.xlsx")
await workflow.translate_async() await workflow.translate_async()
# または同期メソッドを使用 # または同期的な方法を使用
# workflow.translate() # workflow.translate()
# 5. 結果を保存 # 5. 結果を保存
workflow.save_as_xlsx(name="translated_notes.xlsx") workflow.save_as_xlsx(name="translated_notes.xlsx")
print("xlsxファイルが保存されました。") print("XLSXファイルが保存されました。")
# 翻訳後のxlsxのバイナリをエクスポートすることも可能 # 翻訳後のXLSXのバイナリをエクスポートすることも可能
text_bytes = workflow.export_to_xlsx() text_bytes = workflow.export_to_xlsx()
@@ -396,51 +403,57 @@ if __name__ == "__main__":
asyncio.run(main()) asyncio.run(main())
``` ```
## 前提条件と設定の詳細 ## 前提条件と設定詳細
### 1. 大規模言語モデルのAPIキーの取得 ### 1. 大規模言語モデルのAPIキーを取得
翻訳機能は大型言語モデルに依存しており、`base_url`、`api_key`、`model_id`を取得するためには、対応するAIプラットフォームから必要な情報を入手する必要があります。 翻訳機能は大規模言語モデルに依存しているため、対応するAIプラットフォームから`base_url`、`api_key`、`model_id`を取得する必要があります。
> 推奨モデル：火山エンジンの`doubao-seed-1-6-flash-250715`、智譜の`glm-4-flash`、阿里雲の `qwen-plus`,``qwen-turbo`、deepseekの`deepseek-chat`など。 > 推奨モデル：火山引擎の`doubao-seed-1-6-250615`、`doubao-seed-1-6-flash-250715`、智谱の`glm-4-flash`、阿里云の`qwen-plus`、
`qwen-turbo`、deepseekの`
> deepseek-chat`など。
| プラットフォーム名 | APIkeyを取得 | baseurl | | プラットフォーム名 | APIキーの取得 | baseurl |
|------------|---------------------------------------------------------------------------------------|----------------------------------------------------------| | :--- | :--- | :--- |
| ollama | | http://127.0.0.1:11434/v1 | | ollama | | http://127.0.0.1:11434/v1 |
| lm studio | | http://127.0.0.1:1234/v1 | | lm studio | | http://127.0.0.1:1234/v1 |
| openrouter | [取得](https://openrouter.ai/settings/keys) | https://openrouter.ai/api/v1 | | openrouter | [クリックして取得](https://openrouter.ai/settings/keys) | https://openrouter.ai/api/v1 |
| openai | [取得](https://platform.openai.com/api-keys) | https://api.openai.com/v1/ | | openai | [クリックして取得](https://platform.openai.com/api-keys) | https://api.openai.com/v1/ |
| gemini | [取得](https://aistudio.google.com/u/0/apikey) | https://generativelanguage.googleapis.com/v1beta/openai/ | | gemini | [クリックして取得](https://aistudio.google.com/u/0/apikey) | https://generativelanguage.googleapis.com/v1beta/openai/ |
| deepseek | [取得](https://platform.deepseek.com/api_keys) | https://api.deepseek.com/v1 | | deepseek | [クリックして取得](https://platform.deepseek.com/api_keys) | https://api.deepseek.com/v1 |
| 智譜ai | [取得](https://open.bigmodel.cn/usercenter/apikeys) | https://open.bigmodel.cn/api/paas/v4 | | 智谱ai | [クリックして取得](https://open.bigmodel.cn/usercenter/apikeys) | https://open.bigmodel.cn/api/paas/v4 |
| 騰訊混元 | [取得](https://console.cloud.tencent.com/hunyuan/api-key) | https://api.hunyuan.cloud.tencent.com/v1 | | 腾讯混元 | [クリックして取得](https://console.cloud.tencent.com/hunyuan/api-key) | https://api.hunyuan.cloud.tencent.com/v1 |
| 阿里雲百錬 | [取得](https://bailian.console.aliyun.com/?tab=model#/api-key) | https://dashscope.aliyuncs.com/compatible-mode/v1 | | 阿里云百炼 | [クリックして取得](https://bailian.console.aliyun.com/?tab=model#/api-key) | https://dashscope.aliyuncs.com/compatible-mode/v1 |
| 火山エンジン | [取得](https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey?apikey=%7B%7D) | https://ark.cn-beijing.volces.com/api/v3 | | 火山引擎 | [クリックして取得](https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey?apikey=%7B%7D) | https://ark.cn-beijing.volces.com/api/v3 |
| 硅基流動 | [取得](https://cloud.siliconflow.cn/account/ak) | https://api.siliconflow.cn/v1 | | 硅基流动 | [クリックして取得](https://cloud.siliconflow.cn/account/ak) | https://api.siliconflow.cn/v1 |
| DMXAPI | [取得](https://www.dmxapi.cn/token) | https://www.dmxapi.cn/v1 | | DMXAPI | [クリックして取得](https://www.dmxapi.cn/token) | https://www.dmxapi.cn/v1 |
### 2. minerU Tokenを取得（オンライン解析） ### 2. PDF解析エンジン（PDF翻訳が不要な場合は気にする必要はありません）
`mineru`を文書解析エンジンとして選択した場合（`convert_engine="mineru"`）、無料のTokenを申請する必要があります。 ### 2.1 minerUトークンの取得 (オンラインPDF解析、無料、推奨)
1. [minerUの公式ウェブサイト](https://mineru.net/apiManage/docs)にアクセスして登録し、APIを申請します。 ドキュメント解析エンジンとして`mineru`を選択した場合（`convert_engine="mineru"`）、無料のトークンを申請する必要があります。
2. [API Token管理インターフェース](https://mineru.net/apiManage/token)で新しいAPI Tokenを作成します。
> **注意**: minerU Tokenは14日間有効期限があり、期限が切れた場合は再度作成してください。 1. [minerU公式サイト](https://mineru.net/apiManage/docs) にアクセスして登録し、APIを申請します。
2. [APIトークン管理画面](https://mineru.net/apiManage/token) で新しいAPIトークンを作成します。
### 3. doclingエンジンの設定（ローカル解析） > **注意**: minerUトークンには14日間の有効期限があります。期限が切れた場合は再作成してください。
`docling`を文書解析エンジンとして選択した場合（`convert_engine="docling"`）、初回使用時にHugging Faceから必要なモデルがダウンロードされます。 ### 2.2. doclingエンジンの設定 (ローカルPDF解析)
**ネットワークの問題解決策:** ドキュメント解析エンジンとして`docling`を選択した場合（`convert_engine="docling"`）、初回使用時にHugging Faceから必要なモデルがダウンロードされます。
1. **Hugging Faceミラーの設定（推奨）:** > より良い選択肢は、[github releases](https://github.com/xunbu/docutranslate/releases)から`docling_artifact.zip`をダウンロードし、作業ディレクトリに展開することです。
* **方法A（環境変数）:** システム環境変数`HF_ENDPOINT`を設定し、IDEまたはターミナルを再起動します。 **`docling`モデルのダウンロードに関するネットワーク問題の解決策:**
```
HF_ENDPOINT=https://hf-mirror.com 1. **Hugging Faceミラーの設定 (推奨)**:
```
* **方法B（コード内で設定）:** Pythonスクリプトの先頭に以下のコードを追加します。 * **方法 A (環境変数)**: システム環境変数 `HF_ENDPOINT` を設定し、IDEまたはターミナルを再起動します。
```
HF_ENDPOINT=https://hf-mirror.com
```
* **方法 B (コード内での設定)**: Pythonスクリプトの先頭に以下のコードを追加します。
```python ```python
import os import os
@@ -448,17 +461,17 @@ import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com' os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
``` ```
2. **オフライン使用（事前にモデルパッケージをダウンロード）:** 2. **オフラインでの使用 (事前にモデルパッケージをダウンロード)**:
* [GitHub Releases](https://github.com/xunbu/docutranslate/releases)から`docling_artifact.zip`をダウンロードします。 * [GitHub Releases](https://github.com/xunbu/docutranslate/releases) から `docling_artifact.zip` をダウンロードします。
* プロジェクトディレクトリに解凍します。 * プロジェクトディレクトリに展開します。
* 設定でモデルパスを指定します： * 設定でモデルのパスを指定します（モデルがスクリプトと同じディレクトリにない場合）：
```python ```python
from docutranslate.converter.x2md.converter_docling import ConverterDoclingConfig from docutranslate.converter.x2md.converter_docling import ConverterDoclingConfig
converter_config = ConverterDoclingConfig( converter_config = ConverterDoclingConfig(
artifact="./docling_artifact", # 解凍したフォルダーを指定 artifact="./docling_artifact", # 展開後のフォルダを指す
code_ocr=True, code_ocr=True,
formula_ocr=True formula_ocr=True
) )
@@ -466,23 +479,26 @@ converter_config = ConverterDoclingConfig(
## FAQ ## FAQ
**Q: 8010ポートが使用中の場合はどうすればよいですか？** **Q: ポート8010が使用中の場合はどうすればよいですか？**
A: `-p`パラメータを使用して新しいポートを指定するか、`DOCUTRANSLATE_PORT`環境変数を設定します。 A: `-p` パラメータを使用して新しいポートを指定するか、`DOCUTRANSLATE_PORT` 環境変数を設定してください。
**Q: スキャンした文書の翻訳をサポートしていますか？** **Q: スキャンされたPDFの翻訳はサポートしていますか？**
A: サポートしています。`mineru`解析エンジンを使用してください。強力なOCR機能を持っています。 A: はい、サポートしています。強力なOCR機能を持つ`mineru`解析エンジンを使用してください。
**Q: 初めて使用するとなぜ遅いですか？** **Q: 初回のPDF翻訳が非常に遅いのはなぜですか？**
A: `docling`エンジンを使用している場合は、初回実行時にHugging Faceからモデルをダウンロードする必要があります。上記の「ネットワークの問題解決策」を参照して、プロセスを高速化してください。 A: `docling`エンジンを使用している場合、初回実行時にHugging Faceからモデルをダウンロードする必要があります。このプロセスを高速化するには、上記の「ネットワーク問題の解決策」を参照してください。
**Q: 内部ネットワーク（オフライン）環境で使用する方法は？** **Q: LAN（オフライン）環境で使用するにはどうすればよいですか？**
A: 完全に可能です。2つの条件を満たす必要があります： A: 完全に可能です。以下の条件を満たす必要があります：
1. **ローカル解析エンジン:** `docling` エンジンを使用し、上記の「オフライン使用」の手順に従って事前にモデルパッケージをダウンロードします。 1. **ローカルLLM**: [Ollama](https://ollama.com/) や [LM Studio](https://lmstudio.ai/) などのツールを使用して言語モデルをローカルにデプロイし、`TranslatorConfig`にローカルモデルの`base_url`を記入します。
2. **ローカル LLM:** [Ollama](https://ollama.com/) または [LM Studio](https://lmstudio.ai/) などのツールを使用して言語モデルをローカルにデプロイし、`TranslatorConfig` でローカルモデルの `base_url` を入力します。 2. **ローカルPDF解析エンジン**（PDF解析が必要な場合のみ）: `docling`エンジンを使用し、上記の「オフラインでの使用」の指示に従って事前にモデルパッケージをダウンロードします。
**Q: キャッシュメカニズムはどのように動作しますか？** **Q: PDF解析のキャッシュメカニズムはどのように機能しますか？**
A: `MarkdownBasedWorkflow` は、文書解析（ファイルから Markdown への変換）の結果を自動的にキャッシュし、重複する解析による時間とリソースの消費を防ぎます。キャッシュはデフォルトでメモリに保存され、最近の10回の解析が記録されます。キャッシュ数を変更するには `DOCUTRANSLATE_CACHE_NUM` 環境変数を使用できます。 A: `MarkdownBasedWorkflow`は、ドキュメント解析（ファイルからMarkdownへの変換）の結果を自動的にキャッシュし、時間とリソースの重複消費を防ぎます。キャッシュはデフォルトでメモリに保存され、直近10回の解析結果が記録されます。キャッシュ数は`DOCUTRANSLATE_CACHE_NUM`環境変数で変更できます。
**Q: ソフトウェアがプロキシ経由で通信するようにするにはどうすればよいですか？**
A: デフォルトではプロキシを使用しません。環境変数`DOCUTRANSLATE_PROXY_ENABLED`を`true`に設定することで、プロキシ経由での通信が可能になります。
## Star History ## Star History

63
README_ZH.md
View File

@@ -2,29 +2,34 @@
<img src="./DocuTranslate.png" alt="项目Logo" style="width: 150px"> <img src="./DocuTranslate.png" alt="项目Logo" style="width: 150px">
</p> </p>
# DocuTranslate <h1 align="center">DocuTranslate</h1>
[![GitHub stars](https://img.shields.io/github/stars/xunbu/docutranslate?style=flats&logo=github&color=blue)](https://github.com/xunbu/docutranslate) <p align="center">
[![github下载数](https://img.shields.io/github/downloads/xunbu/docutranslate/total?logo=github)](https://github.com/xunbu/docutranslate/releases) <a href="https://github.com/xunbu/docutranslate/stargazers"><img src="https://img.shields.io/github/stars/xunbu/docutranslate?style=flat-square&logo=github&color=blue" alt="GitHub stars"></a>
[![PyPI version](https://img.shields.io/pypi/v/docutranslate)](https://pypi.org/project/docutranslate/) <a href="https://github.com/xunbu/docutranslate/releases"><img src="https://img.shields.io/github/downloads/xunbu/docutranslate/total?logo=github&style=flat-square" alt="GitHub Downloads"></a>
[![python版本](https://img.shields.io/badge/Python-3.11+-3776AB?logo=python&logoColor=white)](https://www.python.org/) <a href="https://pypi.org/project/docutranslate/"><img src="https://img.shields.io/pypi/v/docutranslate?style=flat-square" alt="PyPI version"></a>
[![开源协议](https://img.shields.io/github/license/xunbu/docutranslate)](./LICENSE) <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.11+-3776AB?logo=python&logoColor=white&style=flat-square" alt="Python Version"></a>
<a href="./LICENSE"><img src="https://img.shields.io/github/license/xunbu/docutranslate?style=flat-square" alt="License"></a>
</p>
[**简体中文**](/README_ZH.md) / [**English**](/README.md) / [**日本語**](/README_JP.md) <p align="center">
<a href="/README_ZH.md"><strong>简体中文</strong></a> / <a href="/README.md"><strong>English</strong></a> / <a href="/README_JP.md"><strong>日本語</strong></a>
</p>
**DocuTranslate** 是一个文件翻译工具，利用先进的文档解析引擎（如 [docling](https://github.com/docling-project/docling) <p align="center">
和 [minerU](https://mineru.net/)）与大型语言模型（LLM）相结合，实现对多种格式文档的精准翻译。 一个基于大语言模型（LLM）的、超轻量级的本地文件翻译工具，致力于提供精准、快速、可扩展的翻译体验。
</p>
新版架构采用 **工作流(Workflow)** 为核心，为不同类型的翻译任务提供了高度可配置和可扩展的解决方案。
- ✅ **支持多种格式**：能翻译 `pdf`、`docx`、`xlsx`、`md`、`txt`、`json`、`epub`、`srt` 等多种文件。 - ✅ **支持多种格式**：能翻译 `pdf`、`docx`、`xlsx`、`md`、`txt`、`json`、`epub`、`srt` 等多种文件。
- ✅ **表格、公式、代码识别**：凭借`docling`、`mineru`实现对学术论文中经常出现的表格、公式、代码的识别与翻译
- ✅ **自动生成术语表**：支持自动生成术语表实现术语的对齐。 - ✅ **自动生成术语表**：支持自动生成术语表实现术语的对齐。
- ✅ **PDF表格、公式、代码识别**：凭借`docling`、`mineru`pdf解析引擎实现对学术论文中经常出现的表格、公式、代码的识别与翻译
- ✅ **json翻译**：支持通过json路径(`jsonpath-ng`语法规范)指定json中需要被翻译的值。 - ✅ **json翻译**：支持通过json路径(`jsonpath-ng`语法规范)指定json中需要被翻译的值。
- ✅ **Word/Excel高保真翻译**：支持`docx`、`xlsx`文件（暂不支持`doc`、`xls`文件）的翻译，保持原格式进行翻译。 - ✅ **Word/Excel保持格式翻译**：支持`docx`、`xlsx`文件（暂不支持`doc`、`xls`文件）保持原格式进行翻译。
- ✅ **多ai平台支持**：支持绝大部分的ai平台，可以实现自定义提示词的并发高性能ai翻译。 - ✅ **多ai平台支持**：支持绝大部分的ai平台，可以实现自定义提示词的并发高性能ai翻译。
- ✅ **异步支持**：专为高性能场景设计，提供完整的异步支持，实现了可以多任务并行的服务接口。 - ✅ **异步支持**：专为高性能场景设计，提供完整的异步支持，实现了可以多任务并行的服务接口。
- ✅ **局域网、多人使用支持**：支持在局域网中多人同时使用。
- ✅ **交互式Web界面**：提供开箱即用的 Web UI 和 RESTful API，方便集成与使用。 - ✅ **交互式Web界面**：提供开箱即用的 Web UI 和 RESTful API，方便集成与使用。
- ✅ **小体积、多平台懒人包支持**：不到40M的windows、mac懒人包（不使用`docling`本地解析pdf的版本）。
> 在翻译`pdf`时会先转换为markdown，这会**丢失**原先的排版，对排版有要求的用户请注意 > 在翻译`pdf`时会先转换为markdown，这会**丢失**原先的排版，对排版有要求的用户请注意
@@ -44,8 +49,8 @@
对于希望快速上手的用户，我们在 [GitHub Releases](https://github.com/xunbu/docutranslate/releases) 上提供整合包。您只需下载、解压，并填入您的 对于希望快速上手的用户，我们在 [GitHub Releases](https://github.com/xunbu/docutranslate/releases) 上提供整合包。您只需下载、解压，并填入您的
AI 平台 API-Key 即可开始使用。 AI 平台 API-Key 即可开始使用。
- **DocuTranslate**: 标准版，使用在线的 `minerU` 引擎解析文档，推荐大多数用户使用。 - **DocuTranslate**: 标准版，使用在线的 `minerU` 引擎解析PDF文档，如果不需要本地解析pdf选这个版本（推荐）。
- **DocuTranslate_full**: 完整版，内置 `docling` 本地解析引擎，支持离线或对数据隐私有更高要求的场景。 - **DocuTranslate_full**: 完整版，内置 `docling` 本地PDF解析引擎，需要本地解析pdf选这个版本。
## 安装 ## 安装
@@ -55,7 +60,7 @@ AI 平台 API-Key 即可开始使用。
# 基础安装 # 基础安装
pip install docutranslate pip install docutranslate
# 如需使用 docling 本地解析引擎 # 如需使用 docling 本地解析PDF
pip install docutranslate[docling] pip install docutranslate[docling]
``` ```
@@ -107,7 +112,7 @@ uv sync
| **`TXTWorkflow`** | 处理纯文本文档。流程为：`txt -> 翻译 -> 导出`。 | `.txt` 及其他纯文本格式 | `.txt`, `.html` | `TXTWorkflowConfig` | | **`TXTWorkflow`** | 处理纯文本文档。流程为：`txt -> 翻译 -> 导出`。 | `.txt` 及其他纯文本格式 | `.txt`, `.html` | `TXTWorkflowConfig` |
| **`JsonWorkflow`** | 处理json文件。流程为：`json -> 翻译 -> 导出`。 | `.json` | `.json`, `.html` | `JsonWorkflowConfig` | | **`JsonWorkflow`** | 处理json文件。流程为：`json -> 翻译 -> 导出`。 | `.json` | `.json`, `.html` | `JsonWorkflowConfig` |
| **`DocxWorkflow`** | 处理docx文件。流程为：`docx -> 翻译 -> 导出`。 | `.docx` | `.docx`, `.html` | `docxWorkflowConfig` | | **`DocxWorkflow`** | 处理docx文件。流程为：`docx -> 翻译 -> 导出`。 | `.docx` | `.docx`, `.html` | `docxWorkflowConfig` |
| **`XlsxWorkflow`** | 处理xlsx文件。流程为：`xlsx -> 翻译 -> 导出`。 | `.xlsx` | `.xlsx`, `.html` | `XlsxWorkflowConfig` | | **`XlsxWorkflow`** | 处理xlsx文件。流程为：`xlsx -> 翻译 -> 导出`。 | `.xlsx`、`.csv` | `.xlsx`, `.html` | `XlsxWorkflowConfig` |
| **`SrtWorkflow`** | 处理srt文件。流程为：`srt -> 翻译 -> 导出`。 | `.srt` | `.srt`, `.html` | `SrtWorkflowConfig` | | **`SrtWorkflow`** | 处理srt文件。流程为：`srt -> 翻译 -> 导出`。 | `.srt` | `.srt`, `.html` | `SrtWorkflowConfig` |
| **`EpubWorkflow`** | 处理epub文件。流程为：`epub -> 翻译 -> 导出`。 | `.epub` | `.epub`, `.html` | `EpubWorkflowConfig` | | **`EpubWorkflow`** | 处理epub文件。流程为：`epub -> 翻译 -> 导出`。 | `.epub` | `.epub`, `.html` | `EpubWorkflowConfig` |
| **`HtmlWorkflow`** | 处理html文件。流程为：`html -> 翻译 -> 导出`。 | `.html`, `.htm` | `.html` | `HtmlWorkflowConfig` | | **`HtmlWorkflow`** | 处理html文件。流程为：`html -> 翻译 -> 导出`。 | `.html`, `.htm` | `.html` | `HtmlWorkflowConfig` |
@@ -425,7 +430,9 @@ if __name__ == "__main__":
| 硅基流动 | [点击获取](https://cloud.siliconflow.cn/account/ak) | https://api.siliconflow.cn/v1 | | 硅基流动 | [点击获取](https://cloud.siliconflow.cn/account/ak) | https://api.siliconflow.cn/v1 |
| DMXAPI | [点击获取](https://www.dmxapi.cn/token) | https://www.dmxapi.cn/v1 | | DMXAPI | [点击获取](https://www.dmxapi.cn/token) | https://www.dmxapi.cn/v1 |
### 2. 获取 minerU Token (在线解析) ### 2. PDF解析引擎（不需要翻译PDF的无需关心此处）
### 2.1 获取 minerU Token (在线解析PDF，免费，推荐)
如果您选择 `mineru`作为文档解析引擎（`convert_engine="mineru"`），则需要申请一个免费的 Token。 如果您选择 `mineru`作为文档解析引擎（`convert_engine="mineru"`），则需要申请一个免费的 Token。
@@ -434,11 +441,13 @@ if __name__ == "__main__":
> **注意**: minerU Token 有 14 天有效期，过期后请重新创建。 > **注意**: minerU Token 有 14 天有效期，过期后请重新创建。
### 3. docling 引擎配置 (本地解析) ### 2.2. docling 引擎配置 (本地解析PDF)
如果您选择 `docling` 作为文档解析引擎（`convert_engine="docling"`），它会在首次使用时从 Hugging Face 下载所需的模型。 如果您选择 `docling` 作为文档解析引擎（`convert_engine="docling"`），它会在首次使用时从 Hugging Face 下载所需的模型。
**网络问题解决方案:** > 更好的选择是在[github releases](https://github.com/xunbu/docutranslate/releases)下载`docling_artifact.zip`解压到工作目录下。
**下载`docling`模型网络问题解决方案:**
1. **设置 Hugging Face 镜像 (推荐)**: 1. **设置 Hugging Face 镜像 (推荐)**:
@@ -458,7 +467,7 @@ os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
* 从 [GitHub Releases](https://github.com/xunbu/docutranslate/releases) 下载 `docling_artifact.zip`。 * 从 [GitHub Releases](https://github.com/xunbu/docutranslate/releases) 下载 `docling_artifact.zip`。
* 将其解压到您的项目目录中。 * 将其解压到您的项目目录中。
* 在配置中指定模型路径： * 在配置中指定模型路径（若模型不在脚本同级目录里）：
```python ```python
from docutranslate.converter.x2md.converter_docling import ConverterDoclingConfig from docutranslate.converter.x2md.converter_docling import ConverterDoclingConfig
@@ -475,20 +484,20 @@ converter_config = ConverterDoclingConfig(
**Q: 8010 端口被占用了怎么办？** **Q: 8010 端口被占用了怎么办？**
A: 使用 `-p` 参数指定一个新端口，或设置 `DOCUTRANSLATE_PORT` 环境变量。 A: 使用 `-p` 参数指定一个新端口，或设置 `DOCUTRANSLATE_PORT` 环境变量。
**Q: 支持扫描件的翻译吗？** **Q: 支持PDF扫描件的翻译吗？**
A: 支持。请使用 `mineru` 解析引擎，它具备强大的 OCR 能力。 A: 支持。请使用 `mineru` 解析引擎，它具备强大的 OCR 能力。
**Q: 第一次使用为什么很慢？** **Q: 第一次翻译PDF为什么很慢？**
A: 如果您使用 `docling` 引擎，它首次运行时需要从 Hugging Face 下载模型。请参考上文的“网络问题解决方案”来加速此过程。 A: 如果您使用 `docling` 引擎，它首次运行时需要从 Hugging Face 下载模型。请参考上文的“网络问题解决方案”来加速此过程。
**Q: 如何在内网（离线）环境使用？** **Q: 如何在内网（离线）环境使用？**
A: 完全可以。您需要满足两个条件： A: 完全可以。您需要满足以下条件：
1. **本地解析引擎**: 使用 `docling` 引擎，并按照上文“离线使用”的指引提前下载模型包。 1. **本地 LLM**: 使用 [Ollama](https://ollama.com/) 或 [LM Studio](https://lmstudio.ai/) 等工具在本地部署语言模型，并在
2. **本地 LLM**: 使用 [Ollama](https://ollama.com/) 或 [LM Studio](https://lmstudio.ai/) 等工具在本地部署语言模型，并在
`TranslatorConfig` 中填入本地模型的 `base_url`。 `TranslatorConfig` 中填入本地模型的 `base_url`。
2. **本地PDF解析引擎**（仅解析pdf需要）: 使用 `docling` 引擎，并按照上文“离线使用”的指引提前下载模型包。
**Q: 缓存机制是如何工作的？** **Q: PDF解析缓存机制是如何工作的？**
A: `MarkdownBasedWorkflow` 会自动缓存文档解析（文件到Markdown的转换）的结果，以避免重复解析消耗时间和资源。缓存默认保存在内存中，并会记录最近的10次解析。您可以通过 A: `MarkdownBasedWorkflow` 会自动缓存文档解析（文件到Markdown的转换）的结果，以避免重复解析消耗时间和资源。缓存默认保存在内存中，并会记录最近的10次解析。您可以通过
`DOCUTRANSLATE_CACHE_NUM` 环境变量来修改缓存数量。 `DOCUTRANSLATE_CACHE_NUM` 环境变量来修改缓存数量。

2
docutranslate/__init__.py
View File

@@ -1,3 +1,3 @@
# SPDX-FileCopyrightText: 2025 QinHan # SPDX-FileCopyrightText: 2025 QinHan
# SPDX-License-Identifier: MPL-2.0 # SPDX-License-Identifier: MPL-2.0
__version__="1.4.1" __version__="1.4.1.post1"