研究者や技術者が大量の英語PDF論文やマニュアルを扱う際、言語の壁は深刻なボトルネックとなる。従来の翻訳ツールでは数式やレイアウトが崩れやすく、1件ずつの処理では非効率的である。PDFMathTranslateの一括翻訳機能は、こうした課題を解決するために設計された。

ディレクトリ走査とファイル収集

def collect_pdf_files(root_dir: str) -> list[str]:
    """
    指定ディレクトリ配下の全PDFパスを再帰的に収集
    """
    if not os.path.exists(root_dir):
        raise FileNotFoundError(f"ディレクトリが存在しません: {root_dir}")

    pdf_list = []
    for current_path, _, filenames in os.walk(root_dir):
        for filename in filenames:
            if filename.lower().endswith('.pdf'):
                full_path = os.path.join(current_path, filename)
                pdf_list.append(full_path)
    return pdf_list

並列処理による高速化アーキテクチャ

def batch_translate(pdf_paths: list[str], dest_folder: str = "", **options):
    """
    複数PDFを並列で翻訳処理
    """
    if len(pdf_paths) == 0:
        raise RuntimeError("処理対象ファイルが指定されていません")

    invalid_files = [f for f in pdf_paths if not os.path.isfile(f)]
    if invalid_files:
        for bad_file in invalid_files:
            print(f"[ERROR] ファイル未発見: {bad_file}", file=sys.stderr)
        raise FileNotFoundError("一部ファイルがアクセス不能です")

    results = []
    worker_pool = ThreadPoolExecutor(max_workers=options.get('threads', 4))
    futures = {
        worker_pool.submit(translate_single, path, dest_folder, **options): path
        for path in pdf_paths
    }

    for future in as_completed(futures):
        try:
            output_path = future.result()
            results.append(output_path)
        except Exception as err:
            print(f"[WARNING] 処理失敗: {futures[future]} → {err}")

    worker_pool.shutdown(wait=True)
    return results

並列度別の性能比較

ネットワークロバスト処理

def fetch_remote_pdf(url: str) -> str:
    """URLからPDFを一時ファイルとして取得"""
    try:
        response = requests.get(url, timeout=30, stream=True)
        response.raise_for_status()

        with tempfile.NamedTemporaryFile(delete=False, suffix='.pdf') as tmp:
            for chunk in response.iter_content(chunk_size=8192):
                tmp.write(chunk)
            return tmp.name

    except requests.RequestException as net_err:
        raise ConnectionError(f"ダウンロード失敗: {url}") from net_err
    except Exception as io_err:
        raise IOError(f"一時ファイル作成エラー") from io_err

実用的なコマンド例

# 学術論文群をDeepLで中国語に一括変換（8スレッド）
pdf2zh --dir ./papers/ -s deepl -lo zh -t 8 --output ./zh_papers/

# 技術ドキュメントをGoogle翻訳で日本語化（フォントサブセットスキップ）
pdf2zh --dir ./manuals/ -s google -lo ja -t 4 --skip-subset-fonts

# 教育資料をOpenAIでスペイン語化（互換モード有効）
pdf2zh --dir ./materials/ -s openai -lo es -t 6 --compatible

リソース使用率の最適化

高度なカスタマイズオプション

# カスタムプロンプトを使用して翻訳品質を調整
pdf2zh --dir ./research/ --prompt ./style_guide.txt -s ollama -t 6

# 特定ページ範囲のみを一括処理（例：目次＋結論部）
pdf2zh --dir ./reports/ -p "1,3-5,20-22" -o ./extracted/

トラブルシューティングガイド

# デバッグログを詳細出力（stderrをファイルに保存）
pdf2zh --dir ./debug_target/ --verbose -t 2 2> debug.log