PDF scientific paper translation and bilingual comparison library.
PDF 科學論文翻譯與雙語對照庫。

• Online Service: Beta version launched Immersive Translate - BabelDOC 1000 free pages per month.
  線上服務：Beta 版本已推出 Immersive Translate - BabelDOC，每月 1000 頁免費。
• Self-deployment: PDFMathTranslate 1.9.3+ Experimental support for BabelDOC, available for self-deployment + WebUI with more translation services.
  自行部署：PDFMathTranslate 1.9.3+ 實驗性支援 BabelDOC，可自行部署 + 帶有更多翻譯服務的 WebUI。
• Provides a simple command line interface.
  提供一個簡單的命令列介面。
• Provides a Python API.
• Mainly designed to be embedded into other programs, but can also be used directly for simple translation tasks.
  主要設計用於嵌入其他程式，但也可直接用於簡單的翻譯任務。

Supported Language

See details: EN | ZH

We recommend using the Tool feature of uv to install yadt.
我們推薦使用 uv 的 Tool 功能來安裝 yadt。

1. First, you need to refer to uv installation to install uv and set up the PATH environment variable as prompted.
   首先，您需要參考 uv 安裝說明來安裝 uv，並依照提示設定 PATH 環境變數。

2. Use the following command to install yadt:
   使用以下命令安裝 yadt：

uv tool install --python 3.12 BabelDOC

babeldoc --help

3. Use the babeldoc command. For example:
   使用 babeldoc 命令。例如：

babeldoc --bing  --files example.pdf

# multiple files
babeldoc --bing  --files example1.pdf --files example2.pdf

We still recommend using uv to manage virtual environments.
我們仍然推薦使用 uv 來管理虛擬環境。

1. First, you need to refer to uv installation to install uv and set up the PATH environment variable as prompted.
   首先，您需要參考 uv 安裝說明來安裝 uv，並依照提示設定 PATH 環境變數。

2. Use the following command to install yadt:
   使用以下命令安裝 yadt：

# clone the project
git clone https://github.com/funstory-ai/BabelDOC

# enter the project directory
cd BabelDOC

# install dependencies and run babeldoc
uv run babeldoc --help

3. Use the uv run babeldoc command. For example:
   使用 uv run babeldoc 命令。例如：

uv run babeldoc --files example.pdf --openai --openai-model "gpt-4o-mini" --openai-base-url "https://api.openai.com/v1" --openai-api-key "your-api-key-here"

# multiple files
uv run babeldoc --files example.pdf --files example2.pdf --openai --openai-model "gpt-4o-mini" --openai-base-url "https://api.openai.com/v1" --openai-api-key "your-api-key-here"

• --lang-in, -li: Source language code (default: en)
  --lang-in , -li ：原始語言碼（預設：en）
• --lang-out, -lo: Target language code (default: zh)
  --lang-out , -lo ：目標語言碼（預設：zh）

• --files: One or more file paths to input PDF documents.
  --files ：一個或多個指向輸入 PDF 文件的檔案路徑。
• --pages, -p: Specify pages to translate (e.g., "1,2,1-,-3,3-5"). If not set, translate all pages
  --pages , -p ：指定要翻譯的頁面 (例如："1,2,1-,-3,3-5")。如果未設定，則翻譯所有頁面
• --split-short-lines: Force split short lines into different paragraphs (may cause poor typesetting & bugs)
  --split-short-lines ：強制將短行分割到不同段落 (可能導致排版不良及錯誤)
• --short-line-split-factor: Split threshold factor (default: 0.8). The actual threshold is the median length of all lines on the current page * this factor
  --short-line-split-factor ：分割閾值係數 (預設值: 0.8)。實際閾值是當前頁面上所有行的中位數長度 * 此係數
• --skip-clean: Skip PDF cleaning step
  --skip-clean : 跳過 PDF 清理步驟
• --dual-translate-first: Put translated pages first in dual PDF mode (default: original pages first)
  --dual-translate-first : 在雙頁 PDF 模式中將翻譯頁面放在前面 (預設：原文頁面在前面)
• --disable-rich-text-translate: Disable rich text translation (may help improve compatibility with some PDFs)
  --disable-rich-text-translate : 停用 RTF 翻譯 (可能幫助改善與某些 PDF 的相容性)
• --enhance-compatibility: Enable all compatibility enhancement options (equivalent to --skip-clean --dual-translate-first --disable-rich-text-translate)
  --enhance-compatibility : 啟用所有相容性強化選項 (等同於 --skip-clean --dual-translate-first --disable-rich-text-translate)
• --use-alternating-pages-dual: Use alternating pages mode for dual PDF. When enabled, original and translated pages are arranged in alternate order. When disabled (default), original and translated pages are shown side by side on the same page.
  --use-alternating-pages-dual : 在雙頁 PDF 中使用交替頁面模式。啟用時，原文頁面和翻譯頁面會交替排列。停用時 (預設)，原文頁面和翻譯頁面會並排顯示在同一頁上。
• --watermark-output-mode: Control watermark output mode: 'watermarked' (default) adds watermark to translated PDF, 'no_watermark' doesn't add watermark, 'both' outputs both versions.
  --watermark-output-mode : 控制浮水印輸出模式：'watermarked' (預設) 會將浮水印加入翻譯後的 PDF 中，'no_watermark' 不加入浮水印，'both' 會輸出兩個版本。
• --max-pages-per-part: Maximum number of pages per part for split translation. If not set, no splitting will be performed.
  --max-pages-per-part : 分割翻譯時每個部分的頁面上限。如果未設定，將不進行分割。
• --no-watermark: [DEPRECATED] Use --watermark-output-mode=no_watermark instead.
  --no-watermark : [已棄用] 請改用 --watermark-output-mode=no_watermark。
• --translate-table-text: Translate table text (experimental, default: False)
  --translate-table-text : 翻譯表格文字 (實驗性，預設：False)
• --skip-scanned-detection: Skip scanned document detection (default: False). When using split translation, only the first part performs detection if not skipped.
  --skip-scanned-detection : 跳過掃描文件偵測 (預設：False)。使用分割翻譯時，如果未跳過，則只有第一個部分會執行偵測。
• --ocr-workaround: Use OCR workaround (default: False). When enabled, the tool will use OCR to detect text and fill background for scanned PDF.
  --ocr-workaround : 使用 OCR 替代方案 (預設值：False)。啟用時，此工具將使用 OCR 偵測掃描 PDF 中的文字並填滿背景。

• --qps: QPS (Queries Per Second) limit for translation service (default: 4)
  --qps : 翻譯服務的 QPS (Queries Per Second) 限制 (預設值: 4)
• --ignore-cache: Ignore translation cache and force retranslation
  --ignore-cache : 忽略翻譯快取並強制重新翻譯
• --no-dual: Do not output bilingual PDF files
  --no-dual : 不要輸出雙語 PDF 檔案
• --no-mono: Do not output monolingual PDF files
  --no-mono : 不要輸出單語 PDF 檔案
• --min-text-length: Minimum text length to translate (default: 5)
  --min-text-length : 要翻譯的最小文字長度 (預設: 5)
• --openai: Use OpenAI for translation (default: False)
  --openai : 使用 OpenAI 進行翻譯 (預設：False)
• --custom-system-prompt: Custom system prompt for translation.
  --custom-system-prompt : 用於翻譯的自訂系統提示詞。
• --add-formula-placehold-hint: Add formula placeholder hint for translation. (Currently not recommended, it may affect translation quality, default: False)
  --add-formula-placehold-hint : 為翻譯新增公式佔位符提示。(目前不建議使用，可能會影響翻譯品質，預設值：False)

• --openai-model: OpenAI model to use (default: gpt-4o-mini)
  ' --openai-model : 要使用的 OpenAI 模型 (預設值: gpt-4o-mini)'
• --openai-base-url: Base URL for OpenAI API
  ' --openai-base-url : OpenAI API 的基礎 URL'
• --openai-api-key: API key for OpenAI service
  ' --openai-api-key : OpenAI 服務的 API 金鑰'

• --output, -o: Output directory for translated files. If not set, use current working directory.
  --output , -o ：翻譯檔案的輸出目錄。如果未設定，則使用目前工作目錄。
• --debug, -d: Enable debug logging level and export detailed intermediate results in ~/.cache/yadt/working.
  --debug , -d ：啟用偵錯記錄層級並將詳細的中間結果匯出至 ~/.cache/yadt/working 。
• --report-interval: Progress report interval in seconds (default: 0.1).
  --report-interval : 進度報告間隔，以秒為單位 (預設: 0.1)。

• --generate-offline-assets: Generate an offline assets package in the specified directory. This creates a zip file containing all required models and fonts.
  --generate-offline-assets : 在指定目錄中產生離線資源包。這會建立一個包含所有必要模型和字型的 zip 壓縮檔。
• --restore-offline-assets: Restore an offline assets package from the specified file. This extracts models and fonts from a previously generated package.
  ' --restore-offline-assets : 從指定檔案還原離線資產套件。這會從先前產生的套件中擷取模型和字型。'

• --config, -c: Configuration file path. Use the TOML format.
  --config , -c : 組態檔案路徑。使用 TOML 格式。

Example Configuration:

[babeldoc]
# Basic settings
debug = true
lang-in = "en-US"
lang-out = "zh-CN"
qps = 10
output = "/path/to/output/dir"

# PDF processing options
split-short-lines = false
short-line-split-factor = 0.8
skip-clean = false
dual-translate-first = false
disable-rich-text-translate = false
use-alternating-pages-dual = false
watermark-output-mode = "watermarked"  # Choices: "watermarked", "no_watermark", "both"
max-pages-per-part = 50  # Automatically split the document for translation and merge it back.
# no-watermark = false  # DEPRECATED: Use watermark-output-mode instead
skip-scanned-detection = false  # Skip scanned document detection for faster processing

# Translation service
openai = true
openai-model = "gpt-4o-mini"
openai-base-url = "https://api.openai.com/v1"
openai-api-key = "your-api-key-here"

# Output control
no-dual = false
no-mono = false
min-text-length = 5
report-interval = 0.5

# Offline assets management
# Uncomment one of these options as needed:
# generate-offline-assets = "/path/to/output/dir"
# restore-offline-assets = "/path/to/offline_assets_package.zip"

You can refer to the example in main.py to use BabelDOC's Python API.
你可以參考 main.py 中的範例來使用 BabelDOC 的 Python API。

Please note:

1. Make sure call babeldoc.high_level.init() before using the API
   確保在使用 API 之前呼叫 babeldoc.high_level.init()

2. The current TranslationConfig does not fully validate input parameters, so you need to ensure the validity of input parameters
   目前的 TranslationConfig 未完全驗證輸入參數，因此您需要確保輸入參數的有效性

3. For offline assets management, you can use the following functions:
   對於離線資產管理，您可以使用以下函數：

   # Generate an offline assets package
   from pathlib import Path
   import babeldoc.assets.assets
   
   # Generate package to a specific directory
   # path is optional, default is ~/.cache/babeldoc/assets/offline_assets_{hash}.zip
   babeldoc.assets.assets.generate_offline_assets_package(Path("/path/to/output/dir"))
   
   # Restore from a package file
   # path is optional, default is ~/.cache/babeldoc/assets/offline_assets_{hash}.zip
   babeldoc.assets.assets.restore_offline_assets_package(Path("/path/to/offline_assets_package.zip"))
   
   # You can also restore from a directory containing the offline assets package
   # The tool will automatically find the correct package file based on the hash
   babeldoc.assets.assets.restore_offline_assets_package(Path("/path/to/directory"))

There are a lot projects and teams working on to make document editing and translating easier like:
有許多專案和團隊正致力於讓文件編輯和翻譯變得更容易，像是：

• mathpix
• Doc2X
• minerU
• PDFMathTranslate

There are also some solutions to solve specific parts of the problem like:
也有一些解決方案可以解決問題的特定部分，例如：

• layoutreader: the read order of the text block in a pdf
  layoutreader: PDF 中文字區塊的閱讀順序
• Surya: the structure of the pdf
  Surya: PDF 的結構

This project hopes to promote a standard pipeline and interface to solve the problem.
本專案希望推廣一套標準化流程與介面來解決這個問題。

In fact, there are two main stages of a PDF parser or translator:
事實上，一個 PDF 解析器或轉換器主要有兩個階段：

• Parsing: A stage of parsing means to get the structure of the pdf such as text blocks, images, tables, etc.
  解析：解析階段表示獲取 PDF 的結構，例如文字區塊、圖片、表格等。
• Rendering: A stage of rendering means to render the structure into a new pdf or other format.
  渲染：渲染階段表示將結構渲染成一個新的 PDF 或其他格式。

For a service like mathpix, it will parse the pdf into a structure may be in a XML format, and then render them using a single column reader order as layoutreader does. The bad news is that the original structure lost.
對於像 Mathpix 這樣的服務，它會將 PDF 解析成一個可能為 XML 格式的結構，然後使用單欄閱讀器順序將其渲染，就像 layoutreader 所做的那樣。壞消息是原始結構丟失了。

Some people will use Adobe PDF Parser because it will generate a Word document and it keeps the original structure. But it is somewhat expensive. And you know, a pdf or word document is not a good format for reading in mobile devices.
有些人會使用 Adobe PDF 解析器，因為它會產生 Word 文件並保留原始結構。但它有點貴。而且你知道，PDF 或 Word 文件在行動裝置上閱讀時格式並不好。

We offer an intermediate representation of the results from parser and can be rendered into a new pdf or other format. The pipeline is also a plugin-based system which everybody can add their new model, ocr, renderer, etc.
我們提供解析器結果的中間表示，並且可以被渲染成新的 PDF 或其他格式。該管線也是一個基於外掛的系統，每個人都可以新增他們新的模型、OCR、渲染器等。

• Add line support
• Add table support
• Add cross-page/cross-column paragraph support
  新增跨頁/跨欄段落支援
• More advanced typesetting features
  更進階的排版功能
• Outline support
• ...

Our first 1.0 version goal is to finish a translation from PDF Reference, Version 1.7 to the following language version:
我們第一個 1.0 版本的目標是完成從 PDF Reference, Version 1.7 到以下語言版本的翻譯：

• Simplified Chinese
• Traditional Chinese
• Japanese
• Spanish

And meet the following requirements:
並符合以下要求：

• layout error less than 1%
  版面錯誤少於 1%
• content loss less than 1%
  內容損失小於 1%

1. Parsing errors in the author and reference sections; they get merged into one paragraph after translation.
   作者和參考文獻部分的解析錯誤；翻譯後它們會合併成一個段落。
2. Lines are not supported.
3. Does not support drop caps.
   不支援首字放大
4. Large pages will be skipped.
   大型頁面將會被跳過

We encourage you to contribute to YADT! Please check out the CONTRIBUTING guide.
我們鼓勵您為 YADT 做出貢獻！請參閱 CONTRIBUTING 指南。

Everyone interacting in YADT and its sub-projects' codebases, issue trackers, chat rooms, and mailing lists is expected to follow the YADT Code of Conduct.
所有在 YADT 及其子專案的程式碼庫、問題追蹤器、聊天室和郵寄列表中互動的人，都應遵守 YADT 行為準則。

Immersive Translation sponsors monthly Pro membership redemption codes for active contributors to this project, see details at: CONTRIBUTOR_REWARD.md
Immersive Translation 為本專案的活躍貢獻者提供每月 Pro 會員兌換碼贊助，詳細資訊請參見：CONTRIBUTOR_REWARD.md

• PDFMathTranslate
• DocLayout-YOLO
• pdfminer
• PyMuPDF
• Asynchronize
• PriorityThreadPoolExecutor
  優先順序執行緒池執行器