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-08-18 20:11:31 +08:00
parent f41ca33535
commit befbca41c8
4 changed files with 322 additions and 313 deletions
Download Patch File Download Diff File Expand all files Collapse all files

293
README.md
View File

@@ -12,19 +12,28 @@
[**简体中文**](/README_ZH.md) / [**English**](/README.md) / [**日本語**](/README_JP.md)
**DocuTranslate** is a document translation tool that leverages advanced document parsing engines (such as [docling](https://github.com/docling-project/docling) and [minerU](https://mineru.net/)) combined with large language models (LLMs) to achieve precise translations for various document formats.
**DocuTranslate** is a file translation tool that combines advanced document parsing engines (such
as [docling](https://github.com/docling-project/docling) and [minerU](https://mineru.net/)) with large language models (
LLMs) to accurately translate documents in various formats.
The new architecture adopts **Workflow** as its core, providing a highly configurable and extensible solution for different types of translation tasks.
The new version adopts a **Workflow-centric** architecture, providing highly configurable and scalable solutions for
various types of translation tasks.
- ✅ **Supports Multiple Formats**: Capable of translating `pdf`, `docx`, `xlsx`, `md`, `txt`, `json`, `epub`, `srt`, and more.
- ✅ **Table, Formula, and Code Recognition**: Utilizes `docling` and `mineru` to identify and translate tables, formulas, and code frequently found in academic papers.
- ✅ **JSON Translation**: Supports specifying values to be translated in JSON using `jsonpath-ng` syntax.
- ✅ **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.
- ✅ **Multi-AI Platform Support**: Compatible with most AI platforms, enabling high-performance concurrent AI translation with customizable prompts.
- ✅ **Asynchronous Support**: Designed for high-performance scenarios, offering full asynchronous support and a service interface for parallel task execution.
- ✅ **Interactive Web Interface**: Provides an out-of-the-box Web UI and RESTful API for easy integration and usage.
- ✅ **Support for Diverse Formats**: Capable of translating various file formats such as `pdf`, `docx`, `xlsx`, `md`,
`txt`, `json`, `epub`, `srt`, etc.
- ✅ **Table, Formula, and Code Recognition**: Utilizes `docling` and `minerU` to recognize and translate tables,
formulas, and code frequently found in academic papers.
- ✅ **JSON Translation**: Allows specifying translatable values within JSON using jsonpath-ng syntax.
- ✅ **High-Fidelity Word/Excel Translation**: Preserves the formatting of `docx` and `xlsx` files (note: `doc` and `xls`
are not supported).
- ✅ **Multiple AI Platform Support**: Covers major AI platforms and enables high-parallel AI translation with custom
prompts.
- ✅ **Asynchronous Support**: Designed for high-performance scenarios, offering full asynchronous support and multi-task
parallel processing APIs.
- ✅ **Interactive Web Interface**: Equipped with a ready-to-use Web UI and RESTful API.
> When translating `pdf`, `html`, and other files, they are first converted to markdown, which **may lose** the original formatting. Users with strict formatting requirements should take note.
> When translating `pdf` files, they are converted to markdown, **resulting in loss of the original layout**. Please be
> cautious if layout preservation is a priority.
> QQ Discussion Group: 1047781902
@@ -37,12 +46,15 @@ The new architecture adopts **Workflow** as its core, providing a highly configu
**Novel Translation**:
![翻译效果](/images/小说翻译.png)
## Bundled Packages
## Bundled Version
For users who wish to get started quickly, we provide bundled packages on [GitHub Releases](https://github.com/xunbu/docutranslate/releases). Simply download, extract, and fill in your AI platform API-Key to begin.
For users who want to get started quickly, we provide a bundled version
on [GitHub Releases](https://github.com/xunbu/docutranslate/releases). Simply download, extract, and input the API key
of your preferred AI platform to start using it.
- **DocuTranslate**: Standard edition, uses the online `minerU` engine for document parsing, recommended for most users.
- **DocuTranslate_full**: Full edition, includes the `docling` local parsing engine, suitable for offline use or scenarios with higher data privacy requirements.
- **DocuTranslate**: Standard version, uses the online `minerU` engine.
- **DocuTranslate_full**: Full version, includes the local `docling` parsing engine, ideal for offline environments or
scenarios prioritizing data privacy.
## Installation
@@ -52,27 +64,27 @@ For users who wish to get started quickly, we provide bundled packages on [GitHu
# Basic installation
pip install docutranslate
# To use the docling local parsing engine
# When using the docling local analysis engine
pip install docutranslate[docling]
```
### Using uv
```bash
# Initialize environment
# Environment initialization
uv init
# Basic installation
uv add docutranslate
# Install docling extension
# Extended installation with docling
uv add docutranslate[docling]
```
### Using git
```bash
# Initialize environment
# Environment initialization
git clone https://github.com/xunbu/docutranslate.git
cd docutranslate
@@ -82,41 +94,47 @@ uv sync
## Core Concept: Workflow
The heart of the new DocuTranslate is the **Workflow**. Each workflow is a complete end-to-end translation pipeline specifically designed for a particular type of file. Instead of interacting with a monolithic class, you now select and configure a suitable workflow based on your file type.
The heart 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, you select and configure the
appropriate workflow based on the file type.
**Basic Usage Process:**
**The basic usage steps are as follows:**
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 corresponding configuration object for the selected workflow (e.g., `MarkdownBasedWorkflowConfig`). This configuration object includes all necessary sub-configurations, such as:
1. **Select a Workflow**: Choose a workflow such as `MarkdownBasedWorkflow` or `TXTWorkflow` based on the input file
type (e.g., PDF/Word or TXT).
2. **Build the Configuration**: Create a configuration object (e.g., `MarkdownBasedWorkflowConfig`) corresponding to the
selected workflow. This configuration object includes all necessary sub-configurations, such as:
* **Converter Config**: Defines how to convert the original file (e.g., PDF) into Markdown.
* **Translator Config**: Specifies which LLM to use, API-Key, target language, etc.
* **Translator Config**: Defines the LLM to use, API keys, target language, etc.
* **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.
4. **Execute Translation**: Call the workflow's `.read_*()` and `.translate()` / `.translate_async()` methods.
5. **Export/Save Results**: Invoke `.export_to_*()` or `.save_as_*()` methods to retrieve or save the translated results.
3. **Instantiate the Workflow**: Use the configuration object to create an instance of the workflow.
4. **Execute the Translation**: Call the workflow's `.read_*()` and `.translate()` / `.translate_async()` methods.
5. **Export/Save the Results**: Call the `.export_to_*()` or `.save_as_*()` methods to retrieve or save the translated
results.
## Available Workflows
| Workflow | Applicable Scenarios | Input Formats | Output Formats | Core Configuration Class |
|:----------------------------|:--------------------------------------------------------|:-----------------------------------------|:-----------------------|:--------------------------------------|
| **`MarkdownBasedWorkflow`** | Processing rich-text documents such as PDFs, Word files, images, etc. Process: `File -> Markdown -> Translation -> Export`. | `.pdf`, `.docx`, `.md`, `.png`, `.jpg`, etc. | `.md`, `.zip`, `.html` | `MarkdownBasedWorkflowConfig` |
| **`TXTWorkflow`** | Processing plain text documents. Process: `txt -> Translation -> Export`. | `.txt` and other plain text formats | `.txt`, `.html` | `TXTWorkflowConfig` |
| **`JsonWorkflow`** | Processing JSON files. Process: `json -> Translation -> Export`. | `.json` | `.json`, `.html` | `JsonWorkflowConfig` |
| **`DocxWorkflow`** | Processing DOCX files. Process: `docx -> Translation -> Export`. | `.docx` | `.docx`, `.html` | `DocxWorkflowConfig` |
| **`XlsxWorkflow`** | Processing XLSX files. Process: `xlsx -> Translation -> Export`. | `.xlsx` | `.xlsx`, `.html` | `XlsxWorkflowConfig` |
| **`SrtWorkflow`** | Processing SRT files. Process: `srt -> Translation -> Export`. | `.srt` | `.srt`, `.html` | `SrtWorkflowConfig` |
| **`EpubWorkflow`** | Processing EPUB files. Process: `epub -> Translation -> Export`. | `.epub` | `.epub`, `.html` | `EpubWorkflowConfig` |
| Workflow | Applicable Scenarios | Input Formats | Output Formats | Core Configuration Class |
|:----------------------------|:----------------------------------------------------------------------------------------------------------------------|:---------------------------------------------|:-----------------------|:------------------------------|
| **`MarkdownBasedWorkflow`** | Processes rich-text documents like PDF, Word, and images. Follows the flow: "File → Markdown → Translation → Export". | `.pdf`, `.docx`, `.md`, `.png`, `.jpg`, etc. | `.md`, `.zip`, `.html` | `MarkdownBasedWorkflowConfig` |
| **`TXTWorkflow`** | Processes plain text documents. Follows the flow: "txt → Translation → Export". | `.txt` and other plain text formats | `.txt`, `.html` | `TXTWorkflowConfig` |
| **`JsonWorkflow`** | Processes JSON files. Follows the flow: "json → Translation → Export". | `.json` | `.json`, `.html` | `JsonWorkflowConfig` |
| **`DocxWorkflow`** | Processes DOCX files. Follows the flow: "docx → Translation → Export". | `.docx` | `.docx`, `.html` | `docxWorkflowConfig` |
| **`XlsxWorkflow`** | Processes XLSX files. Follows the flow: "xlsx → Translation → Export". | `.xlsx` | `.xlsx`, `.html` | `XlsxWorkflowConfig` |
| **`SrtWorkflow`** | Processes SRT files. Follows the flow: "srt → Translation → Export". | `.srt` | `.srt`, `.html` | `SrtWorkflowConfig` |
| **`EpubWorkflow`** | Processes EPUB files. Follows the flow: "epub → Translation → Export". | `.epub` | `.epub`, `.html` | `EpubWorkflowConfig` |
| **`HtmlWorkflow`** | Processes HTML files. Follows the flow: "html → Translation → Export". | `.html`, `.htm` | `.html` | `HtmlWorkflowConfig` |
> PDF format can be exported in the interactive interface.
> The interactive interface supports exporting in PDF format.
## Launching Web UI and API Services
For ease of use, DocuTranslate provides a fully functional web interface and RESTful API.
For convenience, DocuTranslate provides a feature-rich web interface and RESTful API.
**Starting the Service:**
```bash
# Start the service, default listening on port 8010
# Start the service (default port: 8010)
docutranslate -i
# Start with a specified port
@@ -127,14 +145,16 @@ export DOCUTRANSLATE_PORT=8011
docutranslate -i
```
- **Interactive Interface**: After starting the service, access `http://127.0.0.1:8010` (or your specified port) in a browser.
- **Interactive Interface**: After starting the service, access `http://127.0.0.1:8010` (or the specified port) in your
browser.
- **API Documentation**: Complete API documentation (Swagger UI) is available at `http://127.0.0.1:8010/docs`.
## Usage Examples
## Usage
### Example 1: Translating a PDF File (Using `MarkdownBasedWorkflow`)
### Example 1: Translating PDF Files (Using `MarkdownBasedWorkflow`)
This is the most common use case. We will use the `minerU` engine to convert the PDF to Markdown, then use LLM for translation. Here's an example in asynchronous mode.
This is the most common use case. The `minerU` engine is used to convert PDFs to Markdown, followed by translation via
LLM. Here, an asynchronous approach is demonstrated.
```python
import asyncio
@@ -147,33 +167,33 @@ from docutranslate.exporter.md.md2html_exporter import MD2HTMLExporterConfig
async def main():
# 1. Build translator configuration
translator_config = MDTranslatorConfig(
base_url="https://open.bigmodel.cn/api/paas/v4", # AI platform Base URL
api_key="YOUR_ZHIPU_API_KEY", # AI platform API Key
base_url="https://open.bigmodel.cn/api/paas/v4", # Base URL of the AI platform
api_key="YOUR_ZHIPU_API_KEY", # API Key for the AI platform
model_id="glm-4-air", # Model ID
to_lang="English", # Target language
chunk_size=3000, # Text chunk size
concurrent=10 # Concurrency count
concurrent=10 # Number of concurrent processes
)
# 2. Build converter configuration (using minerU)
converter_config = ConverterMineruConfig(
mineru_token="YOUR_MINERU_TOKEN", # Your minerU Token
mineru_token="YOUR_MINERU_TOKEN", # minerU token
formula_ocr=True # Enable formula recognition
)
# 3. Build main workflow configuration
workflow_config = MarkdownBasedWorkflowConfig(
convert_engine="mineru", # Specify parsing engine
converter_config=converter_config, # Pass converter configuration
translator_config=translator_config, # Pass translator configuration
convert_engine="mineru", # Specify the parsing engine
converter_config=converter_config, # Apply converter configuration
translator_config=translator_config, # Apply translator configuration
html_exporter_config=MD2HTMLExporterConfig(cdn=True) # HTML export configuration
)
# 4. Instantiate the workflow
workflow = MarkdownBasedWorkflow(config=workflow_config)
# 5. Read file and execute translation
print("Starting file reading and translation...")
# 5. Load file and execute translation
print("Starting file loading and translation...")
workflow.read_path("path/to/your/document.pdf")
await workflow.translate_async()
# Or use synchronous method
@@ -183,10 +203,10 @@ async def main():
# 6. Save results
workflow.save_as_html(name="translated_document.html")
workflow.save_as_markdown_zip(name="translated_document.zip")
workflow.save_as_markdown(name="translated_document.md") # Markdown with embedded images
print("Files saved to ./output folder.")
workflow.save_as_markdown(name="translated_document.md") # Image-embedded Markdown
print("Files have been saved in the ./output folder.")
# Or directly get content strings
# Or directly retrieve content strings
html_content = workflow.export_to_html()
html_content = workflow.export_to_markdown()
# print(html_content)
@@ -196,11 +216,6 @@ if __name__ == "__main__":
asyncio.run(main())
```
### Example 2: Translating a TXT File (Using `TXTWorkflow`)
For plain text files, the process is simpler as it doesn't require document parsing (conversion) steps. Here's an example using asynchronous method.
```python
import asyncio
from docutranslate.workflow.txt_workflow import TXTWorkflow, TXTWorkflowConfig
@@ -209,15 +224,15 @@ from docutranslate.exporter.txt.txt2html_exporter import TXT2HTMLExporterConfig
async def main():
# 1. Configure the translator
# 1. Build translator configuration
translator_config = TXTTranslatorConfig(
base_url="https://api.openai.com/v1/",
api_key="YOUR_OPENAI_API_KEY",
model_id="gpt-4o",
to_lang="Chinese",
to_lang="Japanese",
)
# 2. Configure the main workflow
# 2. Build main workflow configuration
workflow_config = TXTWorkflowConfig(
translator_config=translator_config,
html_exporter_config=TXT2HTMLExporterConfig(cdn=True)
@@ -226,7 +241,7 @@ async def main():
# 3. Instantiate the workflow
workflow = TXTWorkflow(config=workflow_config)
# 4. Read the file and perform translation
# 4. Load the file and execute translation
workflow.read_path("path/to/your/notes.txt")
await workflow.translate_async()
# Alternatively, use the synchronous method
@@ -234,9 +249,9 @@ async def main():
# 5. Save the results
workflow.save_as_txt(name="translated_notes.txt")
print("TXT file saved.")
print("TXT file has been saved.")
# Optionally, export the translated plain text
# It's also possible to export the translated plain text
text = workflow.export_to_txt()
@@ -244,12 +259,6 @@ if __name__ == "__main__":
asyncio.run(main())
```
### Example 3: Translating a JSON File (Using `JsonWorkflow`)
This example demonstrates the asynchronous approach. The `json_paths` item in `JsonTranslatorConfig` specifies the JSON paths to be translated (following `jsonpath-ng` syntax), where only values matching these paths will be translated.
```python
import asyncio
@@ -264,8 +273,8 @@ async def main():
base_url="https://api.openai.com/v1/",
api_key="YOUR_OPENAI_API_KEY",
model_id="gpt-4o",
to_lang="Chinese",
json_paths=["$.*", "$.name"] # Follows jsonpath-ng syntax; values matching these paths will be translated
to_lang="Japanese",
json_paths=["$.*", "$.name"] # Complies with jsonpath-ng syntax; values matching these paths will be translated
)
# 2. Configure the main workflow
@@ -277,7 +286,7 @@ async def main():
# 3. Instantiate the workflow
workflow = JsonWorkflow(config=workflow_config)
# 4. Read the file and perform translation
# 4. Load the file and execute the translation
workflow.read_path("path/to/your/notes.json")
await workflow.translate_async()
# Alternatively, use the synchronous method
@@ -285,9 +294,9 @@ async def main():
# 5. Save the results
workflow.save_as_json(name="translated_notes.json")
print("JSON file saved.")
print("JSON file has been saved.")
# Optionally, export the translated JSON text
# The translated JSON text can also be exported
text = workflow.export_to_json()
@@ -295,11 +304,6 @@ if __name__ == "__main__":
asyncio.run(main())
```
### Example 4: Translating a DOCX File (Using `DocxWorkflow`)
This example demonstrates the asynchronous approach.
```python
import asyncio
@@ -309,17 +313,17 @@ from docutranslate.workflow.docx_workflow import DocxWorkflowConfig, DocxWorkflo
async def main():
# 1. Build translator configuration
# 1. Configure the translator
translator_config = DocxTranslatorConfig(
base_url="https://api.openai.com/v1/",
api_key="YOUR_OPENAI_API_KEY",
model_id="gpt-4o",
to_lang="Chinese",
to_lang="Japanese",
insert_mode="replace", # Options: "replace", "append", "prepend"
separator="\n", # Separator used in "append" or "prepend" mode
)
# 2. Build main workflow configuration
# 2. Configure the main workflow
workflow_config = DocxWorkflowConfig(
translator_config=translator_config,
html_exporter_config=Docx2HTMLExporterConfig(cdn=True)
@@ -328,17 +332,17 @@ async def main():
# 3. Instantiate the workflow
workflow = DocxWorkflow(config=workflow_config)
# 4. Read the file and perform translation
# 4. Load the file and execute translation
workflow.read_path("path/to/your/notes.docx")
await workflow.translate_async()
# Or use the synchronous method
# Alternatively, use the synchronous method
# workflow.translate()
# 5. Save the results
workflow.save_as_docx(name="translated_notes.docx")
print("The docx file has been saved.")
# Alternatively, export the translated docx as binary
# The translated docx can also be exported as binary
text_bytes = workflow.export_to_docx()
@@ -346,12 +350,6 @@ if __name__ == "__main__":
asyncio.run(main())
```
### Example 5: Translating an XLSX File (Using `XlsxWorkflow`)
Here, an asynchronous approach is demonstrated.
```python
import asyncio
@@ -366,7 +364,7 @@ async def main():
base_url="https://api.openai.com/v1/",
api_key="YOUR_OPENAI_API_KEY",
model_id="gpt-4o",
to_lang="Chinese",
to_lang="Japanese",
insert_mode="replace", # Options: "replace", "append", "prepend"
separator="\n", # Separator used in "append" or "prepend" mode
)
@@ -380,17 +378,17 @@ async def main():
# 3. Instantiate the workflow
workflow = XlsxWorkflow(config=workflow_config)
# 4. Read the file and perform translation
# 4. Load the file and execute translation
workflow.read_path("path/to/your/notes.xlsx")
await workflow.translate_async()
# Or use the synchronous method
# Alternatively, use the synchronous method
# workflow.translate()
# 5. Save the results
workflow.save_as_xlsx(name="translated_notes.xlsx")
print("The xlsx file has been saved.")
# Alternatively, export the translated xlsx as binary
# It's also possible to export the translated xlsx as binary
text_bytes = workflow.export_to_xlsx()
@@ -398,55 +396,56 @@ if __name__ == "__main__":
asyncio.run(main())
```
### 1. Obtaining API Keys for Large-Scale Language Models
## Prerequisites and Configuration Details
The translation functionality relies on large-scale language models, requiring the retrieval of `base_url`, `api_key`,
and `model_id` from the corresponding AI platform.
### 1. Obtaining Large Model API Keys
> 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.
The translation functionality relies on large language models. You need to obtain `base_url`, `api_key`, and `model_id` from the respective AI platforms.
| Platform Name | API Key Retrieval Method | Base URL |
|-----------------------|----------------------------------------------------------------------------------------------------|----------------------------------------------------------|
| ollama | | http://127.0.0.1:11434/v1 |
| lm studio | | http://127.0.0.1:1234/v1 |
| openrouter | [Click to retrieve](https://openrouter.ai/settings/keys) | https://openrouter.ai/api/v1 |
| openai | [Click to retrieve](https://platform.openai.com/api-keys) | https://api.openai.com/v1/ |
| gemini | [Click to retrieve](https://aistudio.google.com/u/0/apikey) | https://generativelanguage.googleapis.com/v1beta/openai/ |
| deepseek | [Click to retrieve](https://platform.deepseek.com/api_keys) | https://api.deepseek.com/v1 |
| Zhipu AI | [Click to retrieve](https://open.bigmodel.cn/usercenter/apikeys) | https://open.bigmodel.cn/api/paas/v4 |
| Tencent Hunyuan | [Click to retrieve](https://console.cloud.tencent.com/hunyuan/api-key) | https://api.hunyuan.cloud.tencent.com/v1 |
| Alibaba Cloud Bailian | [Click to retrieve](https://bailian.console.aliyun.com/?tab=model#/api-key) | https://dashscope.aliyuncs.com/compatible-mode/v1 |
| Volcano Engine | [Click to retrieve](https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey?apikey=%7B%7D) | https://ark.cn-beijing.volces.com/api/v3 |
| Silicon Flow | [Click to retrieve](https://cloud.siliconflow.cn/account/ak) | https://api.siliconflow.cn/v1 |
| DMXAPI | [Click to retrieve](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. Obtaining minerU Tokens (Online Parsing)
| Platform Name | API Key Acquisition | Base URL |
|---------------|------------------------------------------------------------------------------------|-----------------------------------------------------------|
| 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 |
| Volcano Engine | [Click to Get](https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey?apikey=%7B%7D) | https://ark.cn-beijing.volces.com/api/v3 |
| Silicon Flow | [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 |
When selecting `mineru` as the document parsing engine (`convert_engine="mineru"`), you need to apply for a free token.
### 2. Obtain minerU Token (Online Parsing)
1. Visit the [minerU official website](https://mineru.net/apiManage/docs), register, and apply for the API.
2. Create a new API token in the [API Token Management page](https://mineru.net/apiManage/token).
If you choose `mineru` as the document parsing engine (`convert_engine="mineru"`), you will need to apply for a free Token.
> **Note**: minerU tokens are valid for 14 days. If expired, recreate them.
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).
### 3. Configuring the docling Engine (Local Parsing)
> **Note**: The minerU Token is valid for 14 days. Please recreate it after expiration.
### 3. docling Engine Configuration (Local Parsing)
If you choose `docling` as the document parsing engine (`convert_engine="docling"`), it will download the required models from Hugging Face upon first use.
When selecting `docling` as the document parsing engine (`convert_engine="docling"`), the required models will be
downloaded from Hugging Face upon first use.
**Solutions for Network Issues:**
1. **Set Up Hugging Face Mirror (Recommended)**:
1. **Setting Up 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 the IDE or
terminal.
```
HF_ENDPOINT=https://hf-mirror.com
```
* **Method B (Code Configuration)**: Add the following code at the beginning of your Python script.
* **Method B (In-Code Configuration)**: Add the following code at the beginning of your Python script.
```python
import os
@@ -454,44 +453,50 @@ import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
```
2. **Offline Usage (Pre-download Model Package)**:
2. **Offline Usage (Pre-Downloading Model Packages)**:
* Download `docling_artifact.zip` from [GitHub Releases](https://github.com/xunbu/docutranslate/releases).
* Extract it to your project directory.
* Extract and place it in the project directory.
* Specify the model path in the configuration:
```python
from docutranslate.converter.x2md.converter_docling import ConverterDoclingConfig
converter_config = ConverterDoclingConfig(
artifact="./docling_artifact", # Point to the extracted folder
artifact="./docling_artifact", # Specify the extracted folder
code_ocr=True,
formula_ocr=True
)
```
## FAQ
**Q: What if port 8010 is occupied?**
A: Use the `-p` parameter to specify a new port or set the `DOCUTRANSLATE_PORT` environment variable.
**Q: What should I do if port 8010 is already in use?**
A: Specify a new port using the `-p` parameter or set the `DOCUTRANSLATE_PORT` environment variable.
**Q: Does it support scanned document translation?**
A: Yes. Use the `mineru` parsing engine, which has powerful OCR capabilities.
**Q: Is scanned document translation supported?**
A: Yes, it is supported. Use the `mineru` parsing engine, which features powerful OCR capabilities.
**Q: Why is it slow the first time I use it?**
A: If you are using the `docling` engine, it needs to download models from Hugging Face during the first run. Refer to the "Solutions for Network Issues" above to speed up this process.
**Q: Why is it slow during the first use?**
A: When using the `docling` engine, the model needs to be downloaded from Hugging Face during the first run. Refer to
the "Network Issue Solutions" section above to speed up this process.
**Q: How can I use it in an intranet (offline) environment?**
A: It is entirely possible. You need to meet two conditions:
A: It is entirely possible. You need to meet the following two conditions:
1. **Local Parsing Engine**: Use the `docling` engine and follow the "Offline Usage" instructions above to pre-download the model package.
2. **Local LLM**: Deploy a language model locally using tools like [Ollama](https://ollama.com/) or [LM Studio](https://lmstudio.ai/), and fill in the `base_url` of the local model in `TranslatorConfig`.
1. **Local Parsing Engine**: Use the `docling` engine and follow the "Offline Usage" steps above to download the model
package in advance.
2. **Local LLM**: Deploy a local language model using tools like [Ollama](https://ollama.com/)
or [LM Studio](https://lmstudio.ai/), then input the local model's `base_url` in `TranslatorConfig`.
**Q: How does the caching mechanism work?**
A: `MarkdownBasedWorkflow` automatically caches the results of document parsing (conversion from file to Markdown) to avoid repetitive parsing that consumes time and resources. By default, the cache is stored in memory and records the most recent 10 parses. You can modify the cache size via the `DOCUTRANSLATE_CACHE_NUM` environment variable.
A: `MarkdownBasedWorkflow` automatically caches the results of document parsing (conversion from files to Markdown),
saving time and resources. By default, the cache is stored in memory, recording the last 10 parsing operations. You can
adjust the cache size using the `DOCUTRANSLATE_CACHE_NUM` environment variable.
**Q: How can I use the software via a proxy?**
A: The software does not use a proxy by default. You can enable proxy usage by setting the `DOCUTRANSLATE_USE_PROXY`
environment variable to `true`.
## Star History

309
README_JP.md
View File

@@ -12,42 +12,43 @@
[**简体中文**](/README_ZH.md) / [**English**](/README.md) / [**日本語**](/README_JP.md)
**DocuTranslate**は、高度なドキュメント解析エンジン（[docling](https://github.com/docling-project/docling)や[minerU](https://mineru.net/)など）と大規模言語モデル（LLM）を組み合わせたファイル翻訳ツールです。多種多様なフォーマットのドキュメントを高精度に翻訳することができます。
**DocuTranslate** は、先進的なドキュメント解析エンジン（[docling](https://github.com/docling-project/docling)
や[minerU](https://mineru.net/)など）と大規模言語モデル（LLM）を組み合わせたファイル翻訳ツールで、多様なフォーマットのドキュメントを高精度に翻訳します。
新しいアーキテクチャでは**ワークフロー（Workflow）**を中核として採用し、さまざまなタイプの翻訳タスクに対して高度に設定可能で拡張性の高いソリューションを提供しています。
新バージョンでは、**ワークフロー(Workflow)**を中核としたアーキテクチャを採用し、様々なタイプの翻訳タスクに対して高度に設定可能で拡張性の高いソリューションを提供します。
- ✅ **多種フォーマット対応**：`pdf`、`docx`、`xlsx`、`md`、`txt`、`json`、`epub`、`srt`など多くのファイルを翻訳可能です。
- ✅ **表、数式、コードの認識**：`docling`や`mineru`を搭載することで、学術論文によく出現する表、数式、コードの認識と翻訳を実現しています。
- ✅ **json翻訳**：jsonパス（`jsonpath-ng`構文仕様）を通じて、json内で翻訳が必要な値を指定することをサポートしています。
- ✅ **Word/Excel高忠実度翻訳**：`docx`、`xlsx`ファイル（`doc`、`xls`ファイルは暫定的にサポートしていません）の翻訳をサポートし、元のフォーマットを保持したまま翻訳を行います。
- ✅ **複数AIプラットフォーム対応**：ほとんどのAIプラットフォームに対応しており、カスタムプロンプトによる並行高性能AI翻訳を実現できます。
- ✅ **非同期対応**：高性能なシーンを念頭に設計されており、完全な非同期サポートを提供し、マルチタスク並行処理が可能なサービスインターフェースを実装しています。
- ✅ **インタラクティブWebインターフェース**：すぐに使えるWeb UIとRESTful APIを提供し、統合と使用が容易です。
- ✅ **多様なフォーマット対応**: `pdf`, `docx`, `xlsx`, `md`, `txt`, `json`, `epub`, `srt` など様々なファイル形式の翻訳が可能
- ✅ **表・数式・コード認識**: `docling` と `mineru` を活用し、学術論文で頻出する表、数式、コードの認識と翻訳を実現
- ✅ **json翻訳**: json内の翻訳対象値をjsonpath-ng構文で指定可能
- ✅ **Word/Excel高忠実度翻訳**: `docx`、`xlsx`ファイル（`doc`、`xls`は非対応）のフォーマットを保持した翻訳
- ✅ **複数AIプラットフォーム対応**: 主要なAIプラットフォームを網羅し、カスタムプロンプトを用いた高並列AI翻訳を実現
- ✅ **非同期サポート**: 高性能シナリオ向けに設計され、完全な非同期サポートとマルチタスク並列処理APIを提供
- ✅ **対話型Webインターフェース**: すぐに使えるWeb UIとRESTful APIを装備
> `pdf`、`html`などのファイルを翻訳する場合、まずmarkdownに変換されます。これにより元の排版が**失われる**可能性があるため、排版に関する要求があるユーザーはご注意ください。
> `pdf`翻訳時はmarkdownに変換されるため、**元のレイアウトが失われます**。レイアウト保持を重視される方はご注意ください
> QQ交流グループ：1047781902
> QQ交流グループ: 1047781902
**UIインターフェース**：
**UIインターフェース**:
![翻译效果](/images/UI界面.png)
**論文翻訳**：
**論文翻訳**:
![翻译效果](/images/论文翻译.png)
**小説翻訳**：
**小説翻訳**:
![翻译效果](/images/小说翻译.png)
## 統合パッケージ
## バンドル版
すぐに始めたいユーザーのために、[GitHub Releases](https://github.com/xunbu/docutranslate/releases)で統合パッケージを提供しています。ダウンロードして解凍し、AIプラットフォームのAPIキーを入力するだけで使用を開始できます。
すぐに使い始めたい方向けに、[GitHub Releases](https://github.com/xunbu/docutranslate/releases)
でバンドル版を提供しています。ダウンロードして解凍し、AIプラットフォームのAPIキーを入力するだけで利用可能です。
- **DocuTranslate**：標準版で、オンラインの`minerU`エンジンを使用してドキュメントを解析します。ほとんどのユーザーに推奨します。
- **DocuTranslate_full**：フル版で、`docling`ローカル解析エンジンを内蔵しています。オフライン環境またはデータプライバシーにより高い要求があるシーンに適しています。
- **DocuTranslate**: 標準版、オンラインの`minerU`エンジンを使用
- **DocuTranslate_full**: 完全版、ローカル`docling`解析エンジンを内蔵、オフライン環境やデータプライバシー重視の場面に最適
## インストール
### pipを使用する場合
### pipを使用
```bash
# 基本インストール
@@ -57,27 +58,23 @@ pip install docutranslate
pip install docutranslate[docling]
```
### uvを使用する場合
### uvを使用
```bash
# 環境の初期化
# 環境初期化
uv init
# 基本インストール
uv add docutranslate
# docling拡張機能のインストール
# docling拡張インストール
uv add docutranslate[docling]
```
### gitを使用する場合
### gitを使用
```bash
# 環境の初期化
# 環境初期化
git clone https://github.com/xunbu/docutranslate.git
cd docutranslate
@@ -88,59 +85,63 @@ uv sync
## コアコンセプト：ワークフロー (Workflow)
新版DocuTranslateのコアは**ワークフロー (Workflow)** です。各ワークフローは、特定のファイルタイプ向けに設計された完全なエンドツーエンドの翻訳パイプラインです。これまでのように大きなクラスとやり取りするのではなく、ファイルタイプに応じて適切なワークフローを選択して設定することになります。
新バージョンのDocuTranslateの中核は**ワークフロー (Workflow)**
です。各ワークフローは、特定のファイルタイプ向けに設計された完全なエンドツーエンドの翻訳パイプラインです。巨大なクラスとやり取りする代わりに、ファイルタイプに応じて適切なワークフローを選択・設定します。
**基本的な使用手順は以下の通りです：**
1. **ワークフローの選択**：入力ファイルタイプ（例：PDF/Word または TXT）に基づいて、`MarkdownBasedWorkflow` や `TXTWorkflow` などのワークフローを選択します。
2. **設定の構築**：選択したワークフローに対応する設定オブジェクト（例：`MarkdownBasedWorkflowConfig`）を作成します。この設定オブジェクトには、以下のような必要なサブ設定がすべて含まれています：
* **コンバーター設定 (Converter Config)**：PDFなどの元ファイルをMarkdownに変換する方法を定義します。
* **翻訳者設定 (Translator Config)**：使用するLLM、APIキー、目標言語などを定義します。
* **エクスポーター設定 (Exporter Config)**：HTMLなどの出力形式の特定オプションを定義します。
1. **ワークフローの選択**：入力ファイルのタイプ（例：PDF/WordまたはTXT）に基づき、`MarkdownBasedWorkflow`や`TXTWorkflow`
などのワークフローを選択します。
2. **設定の構築**：選択したワークフローに対応する設定オブジェクト（例：`MarkdownBasedWorkflowConfig`
）を作成します。この設定オブジェクトには、以下のようなすべての必要なサブ設定が含まれます：
* **コンバーター設定 (Converter Config)**: 元のファイル（PDFなど）をMarkdownに変換する方法を定義します。
* **トランスレーター設定 (Translator Config)**: 使用するLLM、APIキー、ターゲット言語などを定義します。
* **エクスポーター設定 (Exporter Config)**: 出力形式（HTMLなど）の特定のオプションを定義します。
3. **ワークフローのインスタンス化**：設定オブジェクトを使用してワークフローのインスタンスを作成します。
4. **翻訳の実行**：ワークフローの `.read_*()` メソッドと `.translate()` / `.translate_async()` メソッドを呼び出します。
5. **結果のエクスポート/保存**：`.export_to_*()` メソッドまたは `.save_as_*()` メソッドを呼び出して、翻訳結果を取得または保存します。
4. **翻訳の実行**：ワークフローの`.read_*()`および`.translate()` / `.translate_async()`メソッドを呼び出します。
5. **結果のエクスポート/保存**：`.export_to_*()`または`.save_as_*()`メソッドを呼び出して翻訳結果を取得または保存します。
## 使用可能なワークフロー
## 利用可能なワークフロー
| ワークフロー | 適用シーン | 入力フォーマット | 出力フォーマット | コア設定クラス |
|:--------------------------|:------------------------------------------------------------|:------------------------------------------|:-----------------------|:--------------------------------|
| **`MarkdownBasedWorkflow`** | PDF、Word、画像などのリッチテキスト文書を処理します。フロー：`ファイル -> Markdown -> 翻訳 -> エクスポート`。 | `.pdf`, `.docx`, `.md`, `.png`, `.jpg` など | `.md`, `.zip`, `.html` | `MarkdownBasedWorkflowConfig` |
| **`TXTWorkflow`** | プレーンテキスト文書を処理します。フロー：`txt -> 翻訳 -> エクスポート`。 | `.txt` 及びその他のプレーンテキストフォーマット | `.txt`, `.html` | `TXTWorkflowConfig` |
| **`JsonWorkflow`** | jsonファイルを処理します。フロー：`json -> 翻訳 -> エクスポート`。 | `.json` | `.json`, `.html` | `JsonWorkflowConfig` |
| **`DocxWorkflow`** | docxファイルを処理します。フロー：`docx -> 翻訳 -> エクスポート`。 | `.docx` | `.docx`, `.html` | `docxWorkflowConfig` |
| **`XlsxWorkflow`** | xlsxファイルを処理します。フロー：`xlsx -> 翻訳 -> エクスポート`。 | `.xlsx` | `.xlsx`, `.html` | `XlsxWorkflowConfig` |
| **`SrtWorkflow`** | srtファイルを処理します。フロー：`srt -> 翻訳 -> エクスポート`。 | `.srt` | `.srt`, `.html` | `SrtWorkflowConfig` |
| **`EpubWorkflow`** | epubファイルを処理します。フロー：`epub -> 翻訳 -> エクスポート`。 | `.epub` | `.epub`, `.html` | `EpubWorkflowConfig` |
| ワークフロー | 適用シナリオ | 入力形式 | 出力形式 | コア設定クラス |
|:----------------------------|:-------------------------------------------------------------------|:-----------------------------------------|:-----------------------|:------------------------------|
| **`MarkdownBasedWorkflow`** | PDF、Word、画像などのリッチテキストドキュメントを処理。「ファイル → Markdown → 翻訳 → エクスポート」の流れ。 | `.pdf`, `.docx`, `.md`, `.png`, `.jpg` 等 | `.md`, `.zip`, `.html` | `MarkdownBasedWorkflowConfig` |
| **`TXTWorkflow`** | プレーンテキストドキュメントを処理。「txt → 翻訳 → エクスポート」の流れ。 | `.txt` およびその他のプレーンテキスト形式 | `.txt`, `.html` | `TXTWorkflowConfig` |
| **`JsonWorkflow`** | jsonファイルを処理。「json → 翻訳 → エクスポート」の流れ。 | `.json` | `.json`, `.html` | `JsonWorkflowConfig` |
| **`DocxWorkflow`** | docxファイルを処理。「docx → 翻訳 → エクスポート」の流れ。 | `.docx` | `.docx`, `.html` | `docxWorkflowConfig` |
| **`XlsxWorkflow`** | xlsxファイルを処理。「xlsx → 翻訳 → エクスポート」の流れ。 | `.xlsx` | `.xlsx`, `.html` | `XlsxWorkflowConfig` |
| **`SrtWorkflow`** | srtファイルを処理。「srt → 翻訳 → エクスポート」の流れ。 | `.srt` | `.srt`, `.html` | `SrtWorkflowConfig` |
| **`EpubWorkflow`** | epubファイルを処理。「epub → 翻訳 → エクスポート」の流れ。 | `.epub` | `.epub`, `.html` | `EpubWorkflowConfig` |
| **`HtmlWorkflow`** | htmlファイルを処理。「html → 翻訳 → エクスポート」の流れ。 | `.html`, `.htm` | `.html` | `HtmlWorkflowConfig` |
> インタラクティブインターフェースではpdf形式でエクスポートできます
> インタラクティブインターフェースではPDF形式でエクスポート可能
## Web UI と API サービスの起動
## Web UIとAPIサービスの起動
使いやすさを向上させるため、DocuTranslateは機能豊富なWebインターフェースとRESTful APIを提供しています。
利便性のため、DocuTranslateは機能豊富なWebインターフェースとRESTful APIを提供しています。
**サービスの起動:**
```bash
# サービスを起動し、デフォルトで8010ポートを監視します
# サービスを起動（デフォルトポート: 8010）
docutranslate -i
# ポートを指定して起動します
# ポートを指定して起動
docutranslate -i -p 8011
# 環境変数でポートを指定することもできます
# 環境変数でポートを指定することも可能
export DOCUTRANSLATE_PORT=8011
docutranslate -i
```
- **インタラクティブインターフェース**: サービスを起動した後、ブラウザで `http://127.0.0.1:8010`（または指定したポート）にアクセスしてください。
- **APIドキュメント**: 完全なAPIドキュメント（Swagger UI）は `http://127.0.0.1:8010/docs` にあります。
- **インタラクティブインターフェース**: サービス起動後、ブラウザで `http://127.0.0.1:8010`（または指定したポート）にアクセスしてください。
- **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
import asyncio
@@ -151,46 +152,46 @@ from docutranslate.exporter.md.md2html_exporter import MD2HTMLExporterConfig
async def main():
# 1. 翻訳者設定の構築
# 1. 翻訳機設定の構築
translator_config = MDTranslatorConfig(
base_url="https://open.bigmodel.cn/api/paas/v4", # AIプラットフォームのBase URL
api_key="YOUR_ZHIPU_API_KEY", # AIプラットフォームのAPI Key
model_id="glm-4-air", # モデルID
to_lang="English", # 目標言語
chunk_size=3000, # テキストのチャンクサイズ
concurrent=10 # 並行数
to_lang="English", # ターゲット言語
chunk_size=3000, # テキストチャンクサイズ
concurrent=10 # 並列処理数
)
# 2. コンバーター設定の構築（minerUを使用）
converter_config = ConverterMineruConfig(
mineru_token="YOUR_MINERU_TOKEN", # あなたのminerU Token
formula_ocr=True # 数式認識を有効にする
mineru_token="YOUR_MINERU_TOKEN", # minerUトークン
formula_ocr=True # 数式認識を有効化
)
# 3. メインワークフロー設定の構築
workflow_config = MarkdownBasedWorkflowConfig(
convert_engine="mineru", # 解析エンジンを指定
converter_config=converter_config, # コンバーター設定を渡す
translator_config=translator_config, # 翻訳者設定を渡す
convert_engine="mineru", # 解析エンジンの指定
converter_config=converter_config, # コンバーター設定の適用
translator_config=translator_config, # 翻訳機設定の適用
html_exporter_config=MD2HTMLExporterConfig(cdn=True) # HTMLエクスポート設定
)
# 4. ワークフローのインスタンス化
workflow = MarkdownBasedWorkflow(config=workflow_config)
# 5. ファイルを読み取り翻訳を実行
print("ファイルの読み取りと翻訳を開始します...")
# 5. ファイルの読み込みと翻訳の実行
print("ファイルの読み込みと翻訳を開始します...")
workflow.read_path("path/to/your/document.pdf")
await workflow.translate_async()
# または同期方式を使用
# workflow.translate()
print("翻訳が完了しました！")
# 6. 結果を保存
# 6. 結果の保存
workflow.save_as_html(name="translated_document.html")
workflow.save_as_markdown_zip(name="translated_document.zip")
workflow.save_as_markdown(name="translated_document.md") # 画像を埋め込んだmarkdown
print("ファイルが ./output フォルダーに保存されました。")
workflow.save_as_markdown(name="translated_document.md") # 画像埋め込みMarkdown
print("ファイルは ./output フォルダに保存されました。")
# または直接コンテンツ文字列を取得
html_content = workflow.export_to_html()
@@ -202,10 +203,9 @@ if __name__ == "__main__":
asyncio.run(main())
```
### 例2: TXTファイルの翻訳（`TXTWorkflow`を使用）
### 例 2: TXTファイルの翻訳（`TXTWorkflow`を使用）
純粋なテキストファイルの場合、ドキュメント解析（変換）ステップが不要なため、フローはより簡単です。ここでは非同期方式を例に挙げます。
プレーンテキストファイルの場合、ドキュメント解析（変換）ステップが不要なため、プロセスがよりシンプルになります。ここでは非同期方式を例示します。
```python
import asyncio
@@ -215,7 +215,7 @@ from docutranslate.exporter.txt.txt2html_exporter import TXT2HTMLExporterConfig
async def main():
# 1. 翻訳者設定を構築
# 1. 翻訳機の設定を構築
translator_config = TXTTranslatorConfig(
base_url="https://api.openai.com/v1/",
api_key="YOUR_OPENAI_API_KEY",
@@ -223,7 +223,7 @@ async def main():
to_lang="日本語",
)
# 2. メインワークフロー設定を構築
# 2. メインワークフローの設定を構築
workflow_config = TXTWorkflowConfig(
translator_config=translator_config,
html_exporter_config=TXT2HTMLExporterConfig(cdn=True)
@@ -235,14 +235,14 @@ async def main():
# 4. ファイルを読み込み、翻訳を実行
workflow.read_path("path/to/your/notes.txt")
await workflow.translate_async()
# または同期的な方法を使用
# または同期メソッドを使用
# workflow.translate()
# 5. 結果を保存
workflow.save_as_txt(name="translated_notes.txt")
print("TXT ファイルが保存されました。")
print("TXTファイルが保存されました。")
# 翻訳後のプレーンテキストをエクスポートすることもできます
# 翻訳後のプレーンテキストをエクスポートすることも可能
text = workflow.export_to_txt()
@@ -250,11 +250,10 @@ if __name__ == "__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
import asyncio
@@ -265,16 +264,16 @@ from docutranslate.workflow.json_workflow import JsonWorkflowConfig, JsonWorkflo
async def main():
# 1. 翻訳者設定を構築
# 1. 翻訳機の設定を構築
translator_config = JsonTranslatorConfig(
base_url="https://api.openai.com/v1/",
api_key="YOUR_OPENAI_API_KEY",
model_id="gpt-4o",
to_lang="日本語",
json_paths=["$.*", "$.name"] # jsonpath-ngパス構文に準拠、パスに一致する値が翻訳されます
json_paths=["$.*", "$.name"] # jsonpath-ngパス構文を満たし、一致するパスの値が翻訳されます
)
# 2. メインワークフロー設定を構築
# 2. メインワークフローの設定を構築
workflow_config = JsonWorkflowConfig(
translator_config=translator_config,
html_exporter_config=Json2HTMLExporterConfig(cdn=True)
@@ -286,14 +285,14 @@ async def main():
# 4. ファイルを読み込み、翻訳を実行
workflow.read_path("path/to/your/notes.json")
await workflow.translate_async()
# または同期的な方法を使用
# または同期メソッドを使用
# workflow.translate()
# 5. 結果を保存
workflow.save_as_json(name="translated_notes.json")
print("jsonファイルが保存されました。")
# 翻訳後のjsonテキストをエクスポートすることもできます
# 翻訳後のjsonテキストをエクスポートすることも可能
text = workflow.export_to_json()
@@ -301,10 +300,9 @@ if __name__ == "__main__":
asyncio.run(main())
```
### 例4: docxファイルを翻訳する（`DocxWorkflow`を使用）
### 例 4: docx ファイルを翻訳する (`DocxWorkflow` を使用)
ここでは非同期方式を例に挙げます。
ここでは非同期方式を例とします。
```python
import asyncio
@@ -315,7 +313,7 @@ from docutranslate.workflow.docx_workflow import DocxWorkflowConfig, DocxWorkflo
async def main():
# 1. 翻訳者設定を構築する
# 1. 翻訳機の設定を構築
translator_config = DocxTranslatorConfig(
base_url="https://api.openai.com/v1/",
api_key="YOUR_OPENAI_API_KEY",
@@ -325,26 +323,26 @@ async def main():
separator="\n", # "append", "prepend"モードで使用するセパレータ
)
# 2. メインワークフロー設定を構築する
# 2. メインワークフローの設定を構築
workflow_config = DocxWorkflowConfig(
translator_config=translator_config,
html_exporter_config=Docx2HTMLExporterConfig(cdn=True)
)
# 3. ワークフローをインスタンス化する
# 3. ワークフローをインスタンス化
workflow = DocxWorkflow(config=workflow_config)
# 4. ファイルを読み込み、翻訳を実行する
# 4. ファイルを読み込み、翻訳を実行
workflow.read_path("path/to/your/notes.docx")
await workflow.translate_async()
# または同期メソッドを使用する
# または同期メソッドを使用
# workflow.translate()
# 5. 結果を保存する
# 5. 結果を保存
workflow.save_as_docx(name="translated_notes.docx")
print("docxファイルが保存されました。")
# 翻訳されたdocxのバイナリをエクスポートすることもできます
# 翻訳後のdocxをバイナリでエクスポートすることも可能
text_bytes = workflow.export_to_docx()
@@ -352,11 +350,9 @@ if __name__ == "__main__":
asyncio.run(main())
```
### 例5: xlsxファイルを翻訳する（`XlsxWorkflow`を使用）
### 例 5: xlsxファイルを翻訳する (`XlsxWorkflow` を使用)
ここでは非同期方式を例に挙げます。
ここでは非同期方式を例とします。
```python
import asyncio
@@ -367,7 +363,7 @@ from docutranslate.workflow.xlsx_workflow import XlsxWorkflowConfig, XlsxWorkflo
async def main():
# 1. 翻訳者設定を構築する
# 1. 翻訳機の設定を構築
translator_config = XlsxTranslatorConfig(
base_url="https://api.openai.com/v1/",
api_key="YOUR_OPENAI_API_KEY",
@@ -377,26 +373,26 @@ async def main():
separator="\n", # "append", "prepend"モードで使用するセパレータ
)
# 2. メインワークフロー設定を構築する
# 2. メインワークフローの設定を構築
workflow_config = XlsxWorkflowConfig(
translator_config=translator_config,
html_exporter_config=Xlsx2HTMLExporterConfig(cdn=True)
)
# 3. ワークフローをインスタンス化する
# 3. ワークフローをインスタンス化
workflow = XlsxWorkflow(config=workflow_config)
# 4. ファイルを読み込み、翻訳を実行する
# 4. ファイルを読み込み、翻訳を実行
workflow.read_path("path/to/your/notes.xlsx")
await workflow.translate_async()
# または同期メソッドを使用する
# または同期メソッドを使用
# workflow.translate()
# 5. 結果を保存する
# 5. 結果を保存
workflow.save_as_xlsx(name="translated_notes.xlsx")
print("xlsxファイルが保存されました。")
# 翻訳されたxlsxのバイナリをエクスポートすることもできます
# 翻訳後のxlsxをバイナリでエクスポートすることも可能
text_bytes = workflow.export_to_xlsx()
@@ -404,55 +400,55 @@ if __name__ == "__main__":
asyncio.run(main())
```
## 前提条件と設定の詳細説明
### 1. 大規模言語モデルAPIキーの取得
翻訳機能は大規模言語モデルに依存しているため、対応するAIプラットフォームから`base_url`、`api_key`、`model_id`を取得する必要があります。
翻訳機能は大規模言語モデルに依存しており、対応するAIプラットフォームから`base_url`、`api_key`、`model_id`を取得する必要があります。
> 推奨モデル：火山エンジンの`doubao-seed-1-6-250615`、`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`など。
| プラットフォーム名 | APIキーの取得 | baseurl |
|------------|-------------------------------------------------------------------------------------|----------------------------------------------------------|
| ollama | | http://127.0.0.1:11434/v1 |
| lm studio | | http://127.0.0.1:1234/v1 |
| openrouter | [クリックして取得](https://openrouter.ai/settings/keys) | https://openrouter.ai/api/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/ |
| 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 |
| 騰訊混元 | [クリックして取得](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://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 |
| DMXAPI | [クリックして取得](https://www.dmxapi.cn/token) | https://www.dmxapi.cn/v1 |
| プラットフォーム名 | APIキー取得方法 | baseurl |
|------------|-------------------------------------------------------------------------------------------|----------------------------------------------------------|
| ollama | | http://127.0.0.1:11434/v1 |
| lm studio | | http://127.0.0.1:1234/v1 |
| openrouter | [クリックして取得](https://openrouter.ai/settings/keys) | https://openrouter.ai/api/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/ |
| 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 |
| テンセント混元 | [クリックして取得](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://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 |
| DMXAPI | [クリックして取得](https://www.dmxapi.cn/token) | https://www.dmxapi.cn/v1 |
### 2. minerU Token の取得（オンライン解析）
### 2. minerUトークンの取得（オンライン解析）
ドキュメント解析エンジンとして `mineru` を選択した場合（`convert_engine="mineru"`）、無料の Token を申請する必要があります。
`mineru`をドキュメント解析エンジンとして選択する場合（`convert_engine="mineru"`）、無料のトークンを申請する必要があります。
1. [minerU 公式サイト](https://mineru.net/apiManage/docs) にアクセスし、登録して API を申請します。
2. [API Token 管理画面](https://mineru.net/apiManage/token) で新しい API Token を作成します。
1. [minerU公式サイト](https://mineru.net/apiManage/docs)にアクセスし、登録してAPIを申請します。
2. [APIトークン管理画面](https://mineru.net/apiManage/token)で新しいAPIトークンを作成します。
> **注意**: minerU Token の有効期限は14日です。期限切れの場合は再作成してください。
> **注意**: minerUトークンは14日間有効で、期限切れの場合は再作成してください。
### 3. docling エンジン設定（ローカル解析）
### 3. doclingエンジンの設定（ローカル解析）
ドキュメント解析エンジンとして `docling` を選択した場合（`convert_engine="docling"`）、初回使用時に必要なモデルが Hugging Face からダウンロードされます。
`docling`をドキュメント解析エンジンとして選択する場合（`convert_engine="docling"`）、初回使用時にHugging
Faceから必要なモデルがダウンロードされます。
**ネットワーク問題の解決策:**
1. **Hugging Face ミラーの設定（推奨）**:
1. **Hugging Faceミラーの設定（推奨）**:
* **方法 A（環境変数）**: システム環境変数 `HF_ENDPOINT` を設定し、IDE またはターミナルを再起動します。
* **方法A（環境変数）**: システム環境変数`HF_ENDPOINT`を設定し、IDEまたはターミナルを再起動します。
```
HF_ENDPOINT=https://hf-mirror.com
```
* **方法 B（コード内設定）**: Python スクリプトの先頭に以下のコードを追加します。
* **方法B（コード内設定）**: Pythonスクリプトの先頭に以下のコードを追加します。
```python
import os
@@ -460,44 +456,47 @@ import os
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
from docutranslate.converter.x2md.converter_docling import ConverterDoclingConfig
converter_config = ConverterDoclingConfig(
artifact="./docling_artifact", # 解凍後のフォルダを指定
artifact="./docling_artifact", # 解凍したフォルダを指定
code_ocr=True,
formula_ocr=True
)
```
## FAQ
**Q: 8010 ポートが占有されている場合はどうしますか？**
A: `-p` パラメータを使用して新しいポートを指定するか、`DOCUTRANSLATE_PORT` 環境変数を設定します。
**Q: 8010ポートが使用中の場合どうすればよいですか？**
A: `-p`パラメータで新しいポートを指定するか、`DOCUTRANSLATE_PORT`環境変数を設定してください。
**Q: スキャン文書の翻訳に対応していますか？**
A: 対応しています。強力な OCR 機能を備えた `mineru` 解析エンジンを使用してください。
**Q: スキャンした文書の翻訳はサポートされていますか？**
A: サポートされています。強力なOCR機能を備えた`mineru`解析エンジンを使用してください。
**Q: 初回使用時に遅いのはなぜですか？**
A: `docling` エンジンを使用している場合、初回実行時に Hugging Face からモデルをダウンロードする必要があります。このプロセスを加速するには、上記の「ネットワーク問題の解決策」を参照してください。
**Q: 初回使用時になぜ遅いのですか？**
A: `docling`エンジンを使用する場合、初回実行時にHugging Faceからモデルをダウンロードする必要があります。上記の「ネットワーク問題の解決策」を参照してこのプロセスを高速化してください。
**Q: イントラネット（オフライン）環境でどのように使用しますか？**
**Q: イントラネット（オフライン）環境で使用するにはどうすればよいですか？**
A: 完全に可能です。以下の2つの条件を満たす必要があります：
1. **ローカル解析エンジン**: `docling` エンジンを使用し、上記の「オフライン使用」のガイドに従って事前にモデルパッケージをダウンロードします。
2. **ローカル LLM**: [Ollama](https://ollama.com/) や [LM Studio](https://lmstudio.ai/) などのツールを使用してローカルに言語モデルをデプロイし、`TranslatorConfig` でローカルモデルの `base_url` を入力します。
1. **ローカル解析エンジン**: `docling`エンジンを使用し、上記の「オフライン使用」の手順に従ってモデルパッケージを事前にダウンロードします。
2. **ローカルLLM**: [Ollama](https://ollama.com/)や[LM Studio](https://lmstudio.ai/)などのツールを使用してローカルに言語モデルをデプロイし、
`TranslatorConfig`にローカルモデルの`base_url`を入力します。
**Q: キャッシュメカニズムはどのように機能しますか？**
A: `MarkdownBasedWorkflow` はドキュメント解析（ファイルからMarkdownへの変換）の結果を自動的にキャッシュし、繰り返し解析による時間とリソースの消費を回避します。キャッシュはデフォルトでメモリに保存され、直近の10回の解析が記録されます。`DOCUTRANSLATE_CACHE_NUM` 環境変数を通じてキャッシュ数を変更することができます。
A: `MarkdownBasedWorkflow`
は、ドキュメント解析（ファイルからMarkdownへの変換）の結果を自動的にキャッシュし、時間とリソースを節約します。キャッシュはデフォルトでメモリに保存され、直近の10回の解析が記録されます。
`DOCUTRANSLATE_CACHE_NUM`環境変数でキャッシュ数を変更できます。
**Q: ソフトウェアをプロキシ経由で使用するにはどうすればよいですか？**
A: ソフトウェアはデフォルトでプロキシを使用しません。環境変数`DOCUTRANSLATE_USE_PROXY`を`true`に設定することでプロキシ経由で使用できます。
## スター履歴
@@ -505,6 +504,6 @@ A: `MarkdownBasedWorkflow` はドキュメント解析（ファイルからMarkd
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=xunbu/docutranslate&type=Date&theme=dark" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=xunbu/docutranslate&type=Date" />
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=xunbu/docutranslate&type=Date" />
<img alt="スター履歴チャート" src="https://api.star-history.com/svg?repos=xunbu/docutranslate&type=Date" />
</picture>
</a>

11
README_ZH.md
View File

@@ -25,7 +25,7 @@
- ✅ **异步支持**：专为高性能场景设计，提供完整的异步支持，实现了可以多任务并行的服务接口。
- ✅ **交互式Web界面**：提供开箱即用的 Web UI 和 RESTful API，方便集成与使用。
> 在翻译`pdf`、`html`等文件时会先转换为markdown，这会**丢失**原先的排版，对排版有要求的用户请注意
> 在翻译`pdf`时会先转换为markdown，这会**丢失**原先的排版，对排版有要求的用户请注意
> QQ交流群：1047781902
@@ -108,7 +108,8 @@ uv sync
| **`DocxWorkflow`** | 处理docx文件。流程为：`docx -> 翻译 -> 导出`。 | `.docx` | `.docx`, `.html` | `docxWorkflowConfig` |
| **`XlsxWorkflow`** | 处理xlsx文件。流程为：`xlsx -> 翻译 -> 导出`。 | `.xlsx` | `.xlsx`, `.html` | `XlsxWorkflowConfig` |
| **`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格式
@@ -402,7 +403,8 @@ if __name__ == "__main__":
翻译功能依赖于大型语言模型，您需要从相应的 AI 平台获取 `base_url`, `api_key` 和 `model_id`。
> 推荐模型：火山引擎的`doubao-seed-1-6-250615`、`doubao-seed-1-6-flash-250715`、智谱的`glm-4-flash`，阿里云的 `qwen-plus`、`qwen-turbo`，deepseek的`
> 推荐模型：火山引擎的`doubao-seed-1-6-250615`、`doubao-seed-1-6-flash-250715`、智谱的`glm-4-flash`，阿里云的 `qwen-plus`、
`qwen-turbo`，deepseek的`
> deepseek-chat`等。
| 平台名称 | 获取APIkey | baseurl |
@@ -487,6 +489,9 @@ A: 完全可以。您需要满足两个条件：
A: `MarkdownBasedWorkflow` 会自动缓存文档解析（文件到Markdown的转换）的结果，以避免重复解析消耗时间和资源。缓存默认保存在内存中，并会记录最近的10次解析。您可以通过
`DOCUTRANSLATE_CACHE_NUM` 环境变量来修改缓存数量。
**Q: 如何让软件可以经过代理**
A: 软件默认不使用代理，可以通过设置环境变量`DOCUTRANSLATE_USE_PROXY`为`true`让软件通过代理。
## Star History
<a href="https://www.star-history.com/#xunbu/docutranslate&Date">