プログラム translate5.py ドキュメント

プログラムの動作

translate5.py は、様々なドキュメント形式(.docx, .pptx, .pdf, .html, .md, .rst, .txt)を、大規模言語モデル (LLM) または DeepL API を利用して翻訳・校正するツールです。主に専門文書の翻訳と整形を目的としており、以下の主要な機能を提供します。

  • 多様なファイル形式のサポート: DOCX、PPTX、PDF、HTML、Markdown、reStructuredText、プレーンテキスト形式のファイルを直接処理できます。

  • LLM連携: OpenAI (GPT-4o, GPT-5.2), Google/Gemini (gemini-2.5-flash), LM Studio など、複数のLLMプロバイダと連携し、高度な翻訳・校正を実行します。

  • DeepL連携: 高品質な機械翻訳サービスであるDeepL APIとの連携もサポートします。

  • 翻訳方向の指定: 日本語から英語 (je)、英語から日本語 (ej) など、柔軟な翻訳方向を指定できます。

  • プロンプトのカスタマイズ: translate5.ini ファイルやコマンドライン引数を通じて、翻訳・校正プロンプトを詳細にカスタマイズし、特定の翻訳要件に対応できます。

  • 処理単位の選択: DOCXやPPTXファイル内のテキストを段落単位 (paragraph) またはテキストラン単位 (run) で処理するかを選択できます。

  • 翻訳フィルタリング: 翻訳対象の最小文字長、多バイト文字の有無によるフィルタリング、翻訳後のテキスト長の比率による妥当性チェックなどの機能を持ちます。

  • 比較レポートの生成: 翻訳前後のテキストを並べて表示するHTML形式の比較レポートを生成し、翻訳結果の確認とレビューを容易にします。

  • 部分的な翻訳結果の保存: 翻訳プロセス中にエラーが発生した場合でも、処理が中断された時点までの翻訳結果をファイルに保存しようとします。

このプログラムは、手作業によるドキュメント翻訳・校正の時間と労力を削減し、一貫性のある高品質な翻訳出力を効率的に生成することを目指します。

原理

translate5.py は、以下のアルゴリズムと技術要素を組み合わせてドキュメント翻訳を実現しています。

  1. 環境設定と引数解析:

    • initialize() 関数で argparse を用いてコマンドライン引数を解析し、翻訳モード、入力ファイル、API設定、プロンプトなどを取得します。

    • APIキーや共通設定は .env および ai.env ファイルから読み込み、ConfigParser を使用して translate5.ini からプロンプト設定を読み込みます。プロンプトは、CLI引数 > iniファイル > 組込みデフォルト の優先順位で決定されます。

    • SimpleNamespace オブジェクト (cfg) を用いて、すべての設定を一元的に管理します。

  2. 必要な非標準ライブラリのチェック:

    • プログラムの冒頭で、chardet, bs4, jinja2, html2text, pdf2docx, docx, pptx, markitdown などの必須ライブラリがインストールされているかを確認します。不足している場合はエラーメッセージを表示して終了します。

  3. ファイル形式の識別と前処理:

    • get_filetype() 関数で入力ファイルの拡張子からファイル形式を識別します。

    • PDFの場合: pdf2docx.Converter を使用してPDFファイルを一時的なDOCXファイルに変換します。このDOCXファイルを後続の処理で利用します。

    • --use_md オプションが指定されている場合: markitdown.MarkItDown や html2text を利用して、入力ファイル(DOCX, PPTX, PDF, HTMLなど)を一時的なMarkdown形式に変換します。これにより、すべてのドキュメントをMarkdownとして統一的に処理するパスが提供されます。PDFがMarkdownに変換された場合、さらに reformat_prompt を使用してテキストの整形を試みます。

  4. 翻訳処理のコアロジック:

    • translate_core モジュールが LLM または DeepL への問い合わせを抽象化します。

    • LLMへの問い合わせは tkai_lib_litellm.query_ai または query_ai_compatible を介して行われます。これらは litellm ライブラリを内部的に利用し、OpenAI, Gemini, LM Studio などの異なるAPIエンドポイントを共通のインターフェースで扱えるようにします。

    • DeepLへの問い合わせは、必要に応じて tkai_lib.query_deepl を動的にインポートして実行されます。

    • プロンプトは、テンプレート文字列とコンテキスト ({{ text }}, {{ additional_prompt }}) を process_template() 関数で結合して構築されます。

  5. ドキュメント構造の走査とテキストの抽出・置換:

    • DOCX (.docx) および PDF (-> .docx):

      • docx.Document オブジェクトを読み込み、段落 (paragraph) や表のセル内のテキストを走査します。

      • --process_unit 引数に応じて、段落全体または個々のテキストラン (run) を翻訳単位とします。

    • PPTX (.pptx):

      • pptx.Presentation オブジェクトを読み込み、スライド、シェイプ (shape.has_text_frame, shape.has_table, MSO_SHAPE_TYPE.GROUP)、ノートスライド、グラフのタイトルやラベルなどを走査します。

      • --process_unit 引数に応じて、段落全体または個々のテキストランを翻訳単位とします。マスタースライドとレイアウトの翻訳もサポートします。

    • HTML (.html):

      • translate_backends.translate_html_document が BeautifulSoup を使用してHTMLコンテンツを解析し、スクリプト、スタイル、コードブロックなどを除外して、主要なテキストコンテンツを抽出・翻訳します。

    • Markdown (.md) および reStructuredText (.rst):

      • translate_backends.translate_markdown_document または translate_rst_document が、それぞれの形式の構造を維持しつつテキストを翻訳します。

    • Plain Text (.txt):

      • ファイル全体を単一のテキストブロックとして翻訳します。

  6. 翻訳対象のフィルタリングとチェック:

    • to_translate() 関数は、--min_translate_length (最小翻訳文字長) や --limit_to_multibyte_str (多バイト文字のみ翻訳対象とするか) に基づいて、テキストブロックが翻訳の対象となるかを判断します。

    • check_translation() 関数は、LLMからの応答が妥当であるかを検証します。特に、不適切なマークダウン記号(3重引用符)で始まる応答や、元のテキストに比べて極端に長い応答を拒否します。

  7. 結果の保存:

    • 翻訳されたドキュメントは、元のファイル形式に応じた新しいファイル名 (_revised.<ext>) で保存されます。DOCXやPPTXはオブジェクトの save() メソッドで、テキストやHTMLは通常のファイル書き込みで保存されます。

    • 翻訳中にエラーが発生した場合でも、可能な限り翻訳済みの部分を含むファイルが保存されるように設計されています。

  8. 比較HTMLレポートの生成:

    • jinja2 テンプレートエンジンと template_translate.html を使用し、翻訳された各テキストセグメントの原文と訳文を並べて表示するHTMLレポートを生成します。これにより、翻訳の品質を視覚的に確認できます。レポートには、実行時の設定情報も含まれます。

必要な非標準ライブラリとインストール方法

translate5.py の実行には、以下のPython非標準ライブラリが必要です。

pip install chardet beautifulsoup4 Jinja2 html2text pdf2docx python-docx python-pptx markitdown

補足:

  • chardet: 文字エンコーディングの自動検出に使用されます。

  • beautifulsoup4 (bs4): HTMLファイルの解析に使用されます。

  • Jinja2: 比較レポート用のHTMLテンプレートをレンダリングするために使用されます。

  • html2text: HTMLをMarkdownに変換するために使用されます。

  • pdf2docx: PDFファイルをDOCXファイルに変換するために使用されます。

  • python-docx (docx): .docx ファイルの読み書きと内容操作に使用されます。

  • python-pptx (pptx): .pptx ファイルの読み書きと内容操作に使用されます。

  • markitdown: 様々なドキュメント形式をMarkdownに変換するために使用されます。

  • tkai_lib_litellm, translate_core, translate_backends は、このプログラムの内部モジュールであり、別途提供されている必要があります。これらは通常、pip でインストールする形式ではありません。

必要な入力ファイル

translate5.py は以下の入力ファイルを必要とします。

  1. 翻訳対象のドキュメントファイル:

    • コマンドライン引数 --infile または -i で指定します。

    • 対応形式: .docx, .pptx, .pdf, .html, .md, .rst, .txt

  2. APIキーおよび共通設定ファイル:

    • translate5.env (プログラム固有の設定やAPIキー)

    • ai.env (共通のAPIキーや設定)

    • これらは通常、環境変数として設定されるか、スクリプトと同じディレクトリ、または親ディレクトリに配置される .env 形式のファイルです。

    • 例:

      OPENAI_API_KEY="sk-..."
      GOOGLE_API_KEY="AIza..."
      DEEPL_API_KEY="..."
      openai_model="gpt-4o"
      max_tokens="4000"
      temperature="0.7"
      
  3. プロンプト設定ファイル (オプション):

    • translate5.ini

    • このファイルは、カレントディレクトリ、入力ファイルが存在するディレクトリ、またはスクリプトが配置されているディレクトリの順に検索されます。

    • 翻訳や整形のためのカスタムプロンプトを定義できます。

    • 例:

      [translate_je]
      prompt = あなたは日本語の専門家です。以下の日本語をビジネスレベルの自然な英語に翻訳してください。
      [reformat]
      prompt = あなたはプロの編集者です。以下のテキストの改行を調整し、意味の通る段落に再構成してください。
      
  4. 比較レポート用HTMLテンプレートファイル:

    • template_translate.html (デフォルト名)

    • コマンドライン引数 --html_template_path でパスを指定できます。

    • このファイルは、カレントディレクトリまたはスクリプトが配置されているディレクトリに配置されている必要があります。

生成される出力ファイル

translate5.py は以下のファイルを生成します。

  1. 翻訳済みドキュメントファイル:

    • 入力ファイル名に _revised が付加されたファイルが生成されます。

    • 例: input.docx -> input_revised.docx

    • ファイル形式は入力ファイルに依存しますが、--use_md オプションが指定された場合は .md 形式で出力されます。

    • input.pdf が --use_md なしで処理される場合、input_revised.docx が生成されます。

    • input.pdf が --use_md ありで処理される場合、input_revised.md が生成されます。

  2. 比較レポートHTMLファイル:

    • 入力ファイル名に _compare.html が付加されたファイルが生成されます。

    • 例: input.docx -> input_compare.html

    • このファイルには、翻訳前後のテキストが並べて表示され、翻訳結果のレビューに役立ちます。

  3. 中間ファイル (特定のシナリオのみ):

    • PDF入力時、--use_md オプションが指定されていない場合:

      • 入力ファイル名.docx (例: input.pdf -> input.docx)

      • PDFから変換された一時的なDOCXファイル。

    • --use_md オプションが指定されている場合:

      • 入力ファイル名.md (例: input.docx -> input.md)

      • 元のドキュメントから変換された一時的なMarkdownファイル。

      • PDF入力の場合、さらに整形されたMarkdownファイルとして 入力ファイル名_reformat.md が生成されることがあります。

コマンドラインでの使用例 (Usage)

基本的なコマンドライン書式は以下の通りです。

python translate5.py [OPTIONS]

主なオプション:

  • -i INFILE, --infile INFILE: 翻訳する入力ファイルのパスを指定します(必須)。

  • --mode {je,ej,jj,...}: 翻訳モードを指定します。

    • je: 日本語から英語 (Japanese to English)

    • ej: 英語から日本語 (English to Japanese)

    • jj: 日本語から日本語 (日本語の校正・整形)

    • ee: 英語から英語 (英語の校正・整形)

  • --api {openai,gemini,lmstudio,deepl,openai5,google}: 使用する翻訳APIを指定します。

    • openai5 と google はそれぞれ openai と gemini のエイリアスとして扱われます。

  • --model MODEL: APIで使用するモデルを上書きします。

  • --endpoint ENDPOINT: APIのエンドポイントURLを指定します (LM Studio など)。

  • --openai_api_key OPENAI_API_KEY: OpenAI APIキーを直接指定します(環境変数や .env より優先)。

  • --google_api_key GOOGLE_API_KEY: Google APIキーを直接指定します。

  • --deepl_api_key DEEPL_API_KEY: DeepL APIキーを直接指定します。

  • --max_tokens MAX_TOKENS: LLMからの応答の最大トークン数を指定します。

  • --temperature TEMPERATURE: LLMのサンプリング温度を指定します(数値が低いほど確定的)。

  • --reasoning-effort {low,medium,xhigh}: LM Studio Qwen3.8 など特定のモデルの推論強度を指定します。

  • --use_md: 入力ファイルをMarkdownに変換してから処理します。

  • --process_unit {paragraph,run}: DOCX/PPTXの処理単位を段落またはランで指定します。

  • --limit_to_multibyte_str: 多バイト文字を含むテキストのみを翻訳対象とします。

  • --min_translate_length MIN_TRANSLATE_LENGTH: 翻訳するテキストの最小文字長を指定します。

  • --allowed_translation_length_ratio RATIO: 翻訳後のテキスト長が元のテキスト長の何倍まで許容されるかを指定します。

  • --translate_prompt PROMPT: 翻訳プロンプト全体を上書きします(3重引用符は使用しないでください)。

  • --reformat_prompt PROMPT: 整形プロンプト全体を上書きします(3重引用符は使用しないでください)。

  • --output_html_path PATH: 比較HTMLレポートの出力パスを指定します。

  • --html_template_path PATH: 比較HTMLレポート用のテンプレートファイルのパスを指定します。

コマンドラインでの具体的な使用例

例1: DOCXファイルを日本語から英語へ翻訳 (OpenAI GPT-4o)

document.docx という日本語のDOCXファイルを、OpenAIの gpt-4o モデルを使って英語に翻訳する例です。

python translate5.py -i document.docx --mode je --api openai --model gpt-4o

実行結果の説明:

  • document.docx が読み込まれます。

  • OpenAI API (GPT-4o) を利用して、段落単位(デフォルト)またはテキストラン単位で翻訳が実行されます。

  • 翻訳結果は document_revised.docx として保存されます。

  • 翻訳前後の比較レポートが document_compare.html として生成されます。

  • コンソールには、翻訳の進捗(原文と訳文)、API呼び出しのトークン使用量などが表示されます。

例2: PDFファイルをMarkdown経由で英語へ翻訳 (Google Gemini Flash)

report.pdf というPDFファイルをMarkdownに変換し、その後Googleのgemini-2.5-flashモデルを使って英語に翻訳する例です。

python translate5.py -i report.pdf --mode je --api gemini --model gemini-2.5-flash --use_md

実行結果の説明:

  • report.pdf が markitdown を使ってMarkdown形式に変換され、report.md として一時的に保存されます。

  • 変換されたMarkdownテキストは、reformat_prompt(もし定義されていれば)で整形された後、report_reformat.md として保存されます。

  • 整形後のMarkdownテキストがGoogle Gemini API (gemini-2.5-flash) を使って英語に翻訳されます。

  • 最終的な翻訳結果は report_revised.md として保存されます。

  • 翻訳前後の比較レポートが report_compare.html として生成されます。

  • コンソールには、PDFからMarkdownへの変換、整形、翻訳の進捗が表示されます。

例3: HTMLファイルを英語から日本語へ翻訳 (DeepL API)

article.html という英語のHTMLファイルを、DeepL APIを使って日本語に翻訳する例です。

python translate5.py -i article.html --mode ej --api deepl --deepl_api_key YOUR_DEEPL_API_KEY

実行結果の説明:

  • article.html が読み込まれ、BeautifulSoup を使ってHTML構造が解析されます。

  • DeepL APIを利用して、HTML内の主要なテキストコンテンツが英語から日本語に翻訳されます。

  • 翻訳結果は article_revised.html として保存されます。

  • 翻訳前後の比較レポートが article_compare.html として生成されます。

  • コンソールには、HTML解析とDeepL翻訳の進捗が表示されます。

例4: カスタムプロンプトを使用したMarkdownファイルの日本語校正

draft.md という日本語のMarkdownファイルを、OpenAIを使って日本語の校正を行う例です。カスタムプロンプトを直接コマンドラインで与えます。

python translate5.py -i draft.md --mode jj --api openai --model gpt-4o \
    --translate_prompt "あなたはプロの編集者です。以下のテキストを文法的に正しく、より自然で洗練された日本語に校正してください。意味は変えないでください。\n\n#元のテキスト\n{{text}}"

実行結果の説明:

  • draft.md が読み込まれます。

  • 指定されたカスタムプロンプトを使用して、OpenAI API (GPT-4o) によりテキストの校正が実行されます。

  • 校正結果は draft_revised.md として保存されます。

  • 校正前後の比較レポートが draft_compare.html として生成されます。

  • コンソールには、校正の進捗とAPI呼び出し情報が表示されます。

  • この例では --mode jj (日本語から日本語) が指定されているため、翻訳ではなく日本語の品質向上に焦点を当てた処理が行われます。