translate5.py 技術ドキュメント

プログラムの動作

translate5.py は、多様なドキュメント形式（.docx, .pptx, .pdf, .html, .md, .txt）のテキストを、指定された翻訳API（OpenAI, Google/Gemini, DeepL）を使用して翻訳または修正するPythonスクリプトです。このプログラムは、特に構造化されたドキュメントからのテキスト抽出、翻訳、そして元の形式への再構築を効率的に行うことを目的としています。

主な機能は以下の通りです。

  • 多種多様なファイル形式のサポート: Microsoft Word (.docx)、PowerPoint (.pptx)、PDF (.pdf)、HTML (.html)、Markdown (.md)、プレーンテキスト (.txt) の入力に対応しています。

  • 複数の翻訳APIの利用: OpenAI (GPT-4, GPT-5などのモデル)、Google Gemini、DeepLといった主要なAI翻訳・生成APIを選択して使用できます。

  • 柔軟なプロンプト設定: translate5.ini ファイルまたはコマンドライン引数を通じて、翻訳やテキスト整形のためのプロンプトを詳細にカスタマイズできます。これにより、特定の要件に合わせた翻訳品質やスタイルを実現します。

  • ドキュメント構造の維持: DOCXやPPTXファイルの場合、段落、表、図形内のテキストフレーム、ノート、グラフタイトルなどの要素を解析し、翻訳後も元のドキュメント構造を可能な限り維持します。

  • テキスト処理単位の選択: DOCXやPPTXの翻訳において、処理単位を「段落 (paragraph)」または「テキストラン (run)」から選択できます。

  • 翻訳結果の検証: 翻訳後のテキストについて、元のテキストとの長さの比率や特定の不要なプレフィックス（例えばコードブロックを示す3重引用符）がないかなどをチェックし、不適切な翻訳を排除する仕組みを備えています。

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

  • Markdownを介した処理: --use_md オプションを使用すると、入力ファイルを一度Markdown形式に変換してから翻訳を行い、汎用的なテキスト処理フローを実現します。PDF入力の場合は、変換後にさらに整形APIを適用することも可能です。

本プログラムは、専門文書やプレゼンテーション資料の多言語化、または既存文書の校正・リライト作業を自動化し、作業の効率化と品質向上に貢献します。

原理

translate5.py は、以下の主要な技術とアルゴリズムに基づいて動作します。

  1. ファイル形式の解析と変換:

    • PDF: pdf2docx ライブラリを使用して、PDFファイルをMicrosoft Word (.docx) 形式に変換します。これにより、PDF内のテキストや構造をWordドキュメントとして扱い、その後のテキスト抽出・編集を可能にします。

    • DOCX: python-docx ライブラリを使用して、Wordドキュメント内の段落 (paragraph)、テーブル (table)、および各段落内のテキストラン (run) を読み込み、それらのテキストコンテンツを抽出・置換します。

    • PPTX: python-pptx ライブラリを使用して、PowerPointプレゼンテーション内のスライド (slide)、図形 (shape)、テキストフレーム (text_frame)、テーブル (table)、ノート (notes_slide)、グラフタイトルなどの要素を走査し、テキストコンテンツを抽出・置換します。グループ化された図形 (MSO_SHAPE_TYPE.GROUP) やグラフ (chart) 内のテキストも再帰的に処理します。

    • HTML: BeautifulSoup4 ライブラリを使用してHTMLドキュメントを解析し、string=True で直接的なテキストノードを検索して抽出・置換します。

    • Markdown/テキスト: シンプルにファイルを読み込み、テキストブロックとして処理します。

    • 汎用Markdown変換: html2text や markitdown を使用して、HTMLやその他の対応ドキュメントからMarkdown形式への変換を行います。これにより、多様な入力形式のテキストを統一されたMarkdown形式としてLLMに渡すことが可能になります。

  2. 自然言語処理（翻訳/修正）:

    • 外部APIの統合: プログラムは、OpenAIのGPTシリーズ（query_openai4, query_openai5）、Google Gemini（query_google2）、およびDeepL（query_deepl）といった商用APIと連携します。これらのAPIは、テキスト翻訳やテキスト修正（リライト、整形）の中核を担います。

    • プロンプトエンジニアリング: ユーザーが定義したプロンプトをLLMに送信することで、特定の翻訳スタイルや出力形式を誘導します。プロンプトは translate5.ini ファイルからロードされるか、コマンドライン引数で直接指定され、{{text}} や {{additional_prompt}} のプレースホルダーが実際のテキストや追加指示で置換されます。

    • 処理単位の選択: DOCXやPPTXの場合、--process_unit 引数により「段落 (paragraph)」全体を一度に翻訳するか、より細かい「テキストラン (run)」単位で翻訳するかを選択できます。これにより、コンテキストの維持とAPIコールサイズの最適化を図ります。

    • 多言語テキスト検出: check_multibyte_str 関数は、正規表現 $[\u0800-\uFFFF]$ を用いて、テキストにマルチバイト文字（日本語、中国語など）が含まれているかを判定します。--limit_to_multibyte_str オプションが有効な場合、マルチバイト文字を含むテキストのみが翻訳対象となります。

  3. 翻訳結果の検証:

    • check_translation 関数により、APIから返された翻訳結果が特定の品質基準を満たしているかを検証します。これには、翻訳後のテキストが元のテキストに対して極端に長すぎないか（allowed_translation_length_ratio で指定）、あるいは予期しないプレフィックス（例: コードブロックの3重引用符など）が付加されていないかなどのチェックが含まれます。これにより、不完全または誤ったAPI応答をフィルタリングし、ドキュメントの整合性を保ちます。

  4. レポート生成:

    • Jinja2 テンプレートエンジンを使用して、翻訳前と翻訳後のテキストデータを埋め込んだHTMLファイルを生成します。このHTMLレポートは、元のテキストと翻訳されたテキストを並列に表示することで、翻訳の精度や変更点を視覚的に比較検討できるようにします。

これらの機能は、argparse によるコマンドライン引数処理、configparser によるINIファイルからの設定読み込み、および pathlib などの標準ライブラリと組み合わされて、柔軟かつ堅牢なドキュメント翻訳・修正ワークフローを提供します。

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

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

chardet
bs4
jinja2
html2text
pdf2docx
docx
pptx
markitdown

これらのライブラリは、pipコマンドを使用して一括でインストールできます。

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

注: tkai_lib はプログラムの内部モジュールとして扱われるか、別途提供されるカスタムライブラリであるため、上記のpipインストールリストには含まれません。

必要な入力ファイル

translate5.py は、以下のファイルを入力として期待します。

  1. 翻訳対象ファイル:

    • ファイル形式: .docx, .pptx, .pdf, .html, .md, .txt

    • 指定方法: コマンドライン引数 --infile または -i でパスを指定します。

    • 例: translate_test.docx, presentation.pptx, report.pdf, webpage.html, readme.md, document.txt

  2. 設定ファイル:

    • translate5.env: プログラム固有のAPIキーや設定（openai_api_key, google_api_key, deepl_api_key など）を格納する環境設定ファイル。プログラムはこれを自動的に読み込みます。

    • ai.env: tkai_lib が使用する共通のAI関連設定を格納する環境設定ファイル。

    • これらのファイルは、APIキーを直接コードに記述する代わりに、安全に管理するために使用されます。ファイルが存在しない場合、環境変数から値が読み込まれます。

  3. プロンプト定義ファイル (オプション):

    • translate5.ini: 翻訳およびテキスト整形のための詳細なプロンプト定義を含むINI形式のファイル。このファイルは以下の優先順位で探索されます。

      1. カレントディレクトリ

      2. 入力ファイルが置かれているディレクトリ

      3. translate5.py スクリプトが置かれているディレクトリ

    • ファイルが見つからない場合、プログラムに組み込まれたデフォルトのプロンプトが使用されます。

    • 内容の例:

      [translate]
role = あなたは専門的な英語を正確かつプロフェッショナルに翻訳・校正するアシスタントです。
prompt = *#翻訳してほしいテキスト*以降のテキストは学会プレゼンテーション等の一部です。\n以下の条件を守り、自然な米国英語に翻訳してください。\n条件1：元の意味を変えない。テキストに書かれていない解釈・内容は追加しない。\n条件2：文字数を大きく増やさない（目安 ±30%）。\n条件3：動詞を含まない短いフレーズはスライド見出しとして扱い、完全な文にしない。\n条件4：数式・記号・固有名詞は可能な限り保持する。\n{{additional_prompt}}\n\n#翻訳してほしいテキスト\n{{text}}

[reformat]
role = あなたは専門的な英語文書を、内容を変えずに読みやすく整形するアシスタントです。
prompt = 以下の*＃テキスト*以降は PDF やスライドから抽出したテキストであり、改行位置や段落順が乱れたり、文が途中で分断されている可能性があります。\n元の意味・情報を一切削除・要約・追加せず、文や段落のつながりが自然になるように並び替えと改行のみを調整してください。\n箇条書きや見出しらしき部分は、その構造を保ってください。\n出力はプレーンテキストのみとし、余計な説明文は付けないでください。\n\n＃テキスト\n{{ text }}

  4. HTMLテンプレートファイル (オプション):

    • template_translate.html: 翻訳比較レポートを生成するためのJinja2テンプレートファイル。コマンドライン引数 --html_template_path でパスを指定できます。

    • 指定がない場合、デフォルト名 template_translate.html でカレントディレクトリ、次にスクリプトディレクトリが探索されます。

生成される出力ファイル

translate5.py は、実行により以下のファイルを生成します。

  1. 翻訳/修正済みドキュメント:

    • ファイル名: 入力ファイル名に _revised が付加され、元の拡張子（またはMarkdownモードの場合は .md、PDF入力でMarkdownモードでない場合は .docx）が使用されます。

      • 例: input.docx → input_revised.docx

      • 例: input.pdf （--use_md なし）→ input_revised.docx

      • 例: input.html （--use_md あり）→ input_revised.md

    • 内容: 翻訳または修正されたテキストが反映されたドキュメントです。DOCX, PPTX, HTML, MD, TXT形式で出力されます。

    • 保存タイミング: 翻訳処理中にエラーが発生した場合でも、可能な限りそれまでに翻訳された内容がこのファイルに保存されます。

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

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

      • 例: input.docx → input_compare.html

    • 内容: 元のテキストと翻訳/修正後のテキストを並列に表示するウェブページ形式のレポートです。これにより、翻訳の変更点や精度を視覚的に確認できます。

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

    • [入力ファイル名].md: --use_md オプションが指定された場合、入力ファイルをMarkdownに変換した中間ファイルです。

      • 例: input.html （--use_md あり）→ input.md

    • [入力ファイル名]_reformat.md: PDF入力で --use_md オプションが指定された場合、PDFからMarkdownに変換され、さらに整形APIを適用した結果が保存される中間ファイルです。

      • 例: input.pdf （--use_md あり）→ input_reformat.md

    • [入力ファイル名].docx: .pdf ファイルが入力された場合、一時的に変換されるDOCX形式の中間ファイルです。

      • 例: input.pdf （--use_md なし）→ input.docx

これらの出力ファイルは、全て入力ファイルと同じディレクトリに生成されます。

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

translate5.py は、コマンドライン引数を通じて実行オプションを制御します。以下に主要な引数を示します。

usage: translate5.py [-h] [--mode MODE] [--infile INFILE] [--output_html_path OUTPUT_HTML_PATH] [--html_template_path HTML_TEMPLATE_PATH] [--api {openai5,openai,google,gemini,deepl}] [--model MODEL] [--endpoint ENDPOINT] [--max_tokens MAX_TOKENS] [--openai_api_key OPENAI_API_KEY] [--openai_model OPENAI_MODEL] [--temperature TEMPERATURE] [--openai_model5 OPENAI_MODEL5] [--reasoning_effort REASONING_EFFORT] [--google_api_key GOOGLE_API_KEY] [--google_model GOOGLE_MODEL] [--deepl_api_key DEEPL_API_KEY] [--force_server_charcode FORCE_SERVER_CHARCODE] [--tsleep_rpm TSLEEP_RPM] [--use_md] [--limit_to_multibyte_str] [--process_unit {paragraph,run}] [--min_translate_length MIN_TRANSLATE_LENGTH] [--allowed_translation_length_ratio ALLOWED_TRANSLATION_LENGTH_RATIO] [--translate_prompt TRANSLATE_PROMPT] [--reformat_prompt REFORMAT_PROMPT]

Translate/Revise .docx/.pptx/.pdf/.html/.md

options:
  -h, --help            show this help message and exit
  --mode MODE           Translation mode (je, ej, jj, etc.) (default: je)
  -i INFILE, --infile INFILE
                        Input file (.docx/.pptx/.pdf/.html/.md/.txt) (default: translate_test.docx)
  --output_html_path OUTPUT_HTML_PATH
                        Path for the output HTML file (comparison report, optional) (default: None)
  --html_template_path HTML_TEMPLATE_PATH
                        Path to the HTML template file for comparison report (default: template_translate.html)
  --api {openai5,openai,google,gemini,deepl}
                        Translation API to use (default: openai5)
  --model MODEL         Override API model (default: None)
  --endpoint ENDPOINT   API endpoint (default: env:endpoint)
  --max_tokens MAX_TOKENS
                        Maximum number of tokens / output length (default: env:2000)
  --openai_api_key OPENAI_API_KEY
                        OpenAI API key (default: env:OPENAI_API_KEY)
  --openai_model OPENAI_MODEL
                        OpenAI model to use (default: env:gpt-4o)
  --temperature TEMPERATURE
                        Sampling temperature (default: env:0.3)
  --openai_model5 OPENAI_MODEL5
                        OpenAI GPT-5 model (default: env:gpt-5.2)
  --reasoning_effort REASONING_EFFORT
                        Reasoning effort level for GPT-5 (default: env:low)
  --google_api_key GOOGLE_API_KEY
                        Google API key (default: env:GOOGLE_API_KEY)
  --google_model GOOGLE_MODEL
                        Google/Gemini model to use (default: env:gemini-2.5-flash)
  --deepl_api_key DEEPL_API_KEY
                        DeepL API key (default: env:DEEPL_API_KEY)
  --force_server_charcode FORCE_SERVER_CHARCODE
                        force_server_charcode (default: env:utf-8)
  --tsleep_rpm TSLEEP_RPM
                        Sleep time to avoid rpm (seconds) (default: 0.5)
  --use_md              Convert to markdown and process
  --limit_to_multibyte_str
                        When set, only translate text containing multibyte chars (e.g. Japanese)
  --process_unit {paragraph,run}
                        Unit of processing for docx/pptx/html (default: paragraph)
  --min_translate_length MIN_TRANSLATE_LENGTH
                        Minimum length of text to translate (default: env:5)
  --allowed_translation_length_ratio ALLOWED_TRANSLATION_LENGTH_RATIO
                        Max allowed ratio (translated_len / original_len) (default: env:5.0)
  --translate_prompt TRANSLATE_PROMPT
                        Override translation prompt (full instructions incl. 'あなたは〜'). (default: )
  --reformat_prompt REFORMAT_PROMPT
                        Override reformat prompt (full instructions). (default: )

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

ここでは、translate5.py の具体的な使用例をいくつか紹介します。実行前に translate5.env または環境変数に各APIキーが設定されていることを確認してください。

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

入力ファイル: sample.docx (日本語の内容を含む)

python translate5.py --infile sample.docx --mode je --api openai --openai_model gpt-4o

実行結果の説明:

  • sample.docx が読み込まれ、OpenAIのGPT-4oモデルを使用して日本語から英語へ翻訳されます。

  • 翻訳された内容は sample_revised.docx として保存されます。

  • 元のテキストと翻訳後のテキストを比較する sample_compare.html が生成されます。

  • コンソールには、各段落やテキストランの翻訳ログが出力されます。

例2: PDFファイルをGoogle Gemini Flashで整形・翻訳し、Markdownとして出力する

入力ファイル: document.pdf (レイアウトが乱れている可能性のあるPDF)

python translate5.py --infile document.pdf --mode ej --api google --google_model gemini-1.5-flash --use_md

実行結果の説明:

  • document.pdf がまず document.docx へ、次に document.md へと内部的に変換されます。

  • 変換されたMarkdownテキストはGoogle Gemini Flashモデルを使用して整形（reformat_prompt が適用）され、document_reformat.md として保存されます。

  • 整形されたMarkdownテキストがさらに翻訳（translate_prompt が適用）され、document_revised.md として保存されます。

  • 比較レポート document_compare.html も生成されます。

  • この例では、PDFの構造が複雑でテキスト抽出が困難な場合に、まずMarkdownに変換し、AIで整形することで、より良い翻訳結果を得ることを目指します。

例3: HTMLファイルをDeepLで英語から日本語に翻訳する

入力ファイル: webpage.html (英語のウェブページ内容を含む)

python translate5.py --infile webpage.html --mode ej --api deepl --deepl_api_key YOUR_DEEPL_API_KEY

実行結果の説明:

  • webpage.html が読み込まれ、DeepL APIを使用して英語から日本語へ翻訳されます。

  • 翻訳されたHTMLコンテンツは webpage_revised.html として保存されます。

  • 元のHTMLと翻訳後のHTMLの比較レポート webpage_compare.html が生成されます。

  • --deepl_api_key は環境変数で設定することも可能です。

例4: 最小翻訳長と翻訳比率を調整してTXTファイルを翻訳する

入力ファイル: notes.txt (短いフレーズや長い文章が混在するテキスト)

python translate5.py -i notes.txt --mode jj --api openai --min_translate_length 10 --allowed_translation_length_ratio 3.0

実行結果の説明:

  • notes.txt がOpenAI APIで日本語から日本語へ（校正・リライト目的で）処理されます。

  • --min_translate_length 10: 長さ10文字未満のテキストは翻訳の対象外となります。これにより、短い単語や記号のみの行が不必要に翻訳されるのを防ぎます。

  • --allowed_translation_length_ratio 3.0: 翻訳後のテキストが元のテキストの3倍を超える長さになった場合、その翻訳は拒否されます。これにより、過剰な展開や不要な情報の追加を防ぎ、より簡潔な出力を促します。

  • 翻訳されたテキストは notes_revised.txt に、比較レポートは notes_compare.html に保存されます。

これらの例は、translate5.py が提供する柔軟なオプションの一部を示しています。必要に応じて、他の引数やAPIを組み合わせて使用してください。