translate5_GUI.py 技術ドキュメント

プログラムの動作

translate5_GUI.py は、AI翻訳ツール translate5 の機能にアクセスするためのグラフィカルユーザーインターフェース (GUI) を提供するPythonプログラムです。これにより、コマンドライン引数や設定ファイルの手動編集なしに、ユーザーが視覚的に翻訳設定を行い、実行できるようになります。

主な機能:

  • 入力ファイル選択: DOCX, PPTX, PDF, HTML, MD, RST, TXT など、多様な形式のソースドキュメントを選択できます。

  • HTMLテンプレート指定: 翻訳結果をHTMLとして出力する際に使用するテンプレートファイルを指定できます。

  • 翻訳方向の切り替え: 日本語から英語 (je) または英語から日本語 (ej) の翻訳モードを選択できます。

  • 処理単位の選択: 翻訳の最小単位を「段落 (paragraph)」、「実行 (run)」、「Markdown (md)」から選択できます。「md」はMarkdown専用の処理フラグとして機能します。

  • APIプロバイダーとモデルの選択: OpenAI、Gemini、LM Studio、DeepL などのAI翻訳サービスを選択し、利用可能なモデルの中から具体的なモデルを指定できます。LM Studio のモデルリストは実行時にサーバーから取得されます。

  • 生成パラメータの調整: temperature、max_tokens、reasoning_effort などのAIモデルの応答生成に関するパラメータをGUIから設定できます。

  • 翻訳ルールの設定: min_translate_length、allowed_translation_length_ratio、limit_to_multibyte_str (日本語ソースに限定) など、翻訳結果の品質や挙動を制御するルールを設定できます。

  • プロンプトの編集: 翻訳指示 (Translate Prompt) および再フォーマット指示 (Reformat Prompt) をGUI上で直接編集・保存できます。翻訳方向に応じてプロンプトが自動的に切り替わります。

  • 設定の永続化: ユーザーが行ったGUI上の設定は、translate5_GUI.ini ファイルに自動的に保存され、次回起動時にロードされます。

  • 非同期実行: 翻訳処理は別のスレッドで実行されるため、長時間の翻訳中でもGUIが応答し続けます。

  • エラー処理: 実行中にエラーが発生した場合、詳細なエラーメッセージをコピー可能なダイアログで表示します。

解決する課題:

  • translate5 の複雑な設定オプションを、視覚的かつ直感的に操作できる環境を提供します。

  • コマンドライン操作に不慣れなユーザーでも、簡単にAI翻訳ツールを利用できるようにします。

  • 複数の翻訳設定やプロンプトを容易に切り替えて試行錯誤できるワークフローを支援します。

  • 設定を自動保存・ロードすることで、ユーザーの利便性を高めます。

原理

translate5_GUI.py は、以下の主要な原理と技術に基づいて動作します。

  • GUIフレームワーク: Pythonの標準ライブラリである tkinter を使用して、ユーザーインターフェースを構築しています。オプションで ttkthemes ライブラリを導入することで、GUIの外観を改善しています。

  • 設定管理: configparser モジュールを用いて、GUI上の設定を translate5_GUI.ini ファイルに読み書きします。これにより、ユーザーの設定がプログラムの再起動後も保持されます。

  • 翻訳ロジックの委譲: 実際の翻訳処理は、translate5 モジュール、tkai_lib_litellm モジュール、および translate_core モジュールに委譲されています。

    • initialize() および update_variables(): translate5 の設定オブジェクト (self.cfg) を初期化し、環境変数やデフォルト値で更新します。

    • configure_translation_cfg(): translate_core から呼び出され、選択されたAPI、モデル、モード、パラメータに基づいて翻訳設定を正規化・構成します。

    • execute(): translate5 モジュールの主要な翻訳実行関数を呼び出し、実際の翻訳タスクを開始します。

  • API/モデルの動的な切り替え: 選択されたAPIプロバイダー (例: OpenAI, Gemini) に応じて、利用可能なモデルのドロップダウンリストが動的に更新されます。normalize_api() 関数はAPI名を標準化し、list_provider_models() は LM Studio などのプロバイダーからモデル情報を取得します。

  • 非同期処理: _run_execute_thread() メソッド内で threading.Thread を使用し、execute() 関数を別スレッドで実行します。これにより、翻訳処理中にGUIがブロックされるのを防ぎ、ユーザーは他の操作を行うことができます。

  • エラーハンドリング: try-except ブロックを使用して、翻訳実行中に発生する可能性のある例外を捕捉します。エラー発生時には、traceback モジュールで取得した詳細な情報を CopyableErrorDialog というカスタムダイアログで表示し、ユーザーがエラーメッセージを簡単にコピーできるようにします。

  • プロンプト管理: _translate_prompts 辞書を用いて、翻訳方向 (je または ej) ごとに異なる翻訳プロンプトを記憶・適用します。これにより、ユーザーは各方向で最適なプロンプトを維持できます。

  • 処理単位の特殊処理: GUIで選択された処理単位が "md" (Markdown) の場合、内部的には self.cfg.use_md フラグを True に設定し、self.cfg.process_unit を "paragraph" にマッピングします。これは translate5 がMarkdownコンテンツを特別に扱うための機構です。

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

translate5_GUI.py を実行するには、以下の非標準ライブラリと、関連するカスタムモジュールが必要です。

  • ttkthemes: tkinter アプリケーションにテーマを適用するためのライブラリです。必須ではありませんが、GUIの外観を向上させます。

    pip install ttkthemes
    
  • translate5: 本プログラムがGUIとして機能する対象となる、コアな翻訳ロジックを提供するモジュールです。

  • tkai_lib_litellm: AIモデルのリストアップなどの機能を提供するモジュールです。

  • translate_core: 翻訳設定の構成など、翻訳に関連するユーティリティ機能を提供するモジュールです。

上記 translate5, tkai_lib_litellm, translate_core は、通常 translate5_GUI.py と同じプロジェクトの一部として提供されるカスタムモジュールです。これらがPythonのパスから利用可能であることを確認してください。もしこれらがPyPIで公開されている場合は、以下のコマンドでインストールできます(ただし、これは一般的な仮定であり、具体的なインストール方法はこのドキュメントの範囲外です)。

# (translate5 が PyPI に存在する場合の例)
pip install translate5 tkai_lib_litellm

環境変数: また、以下の環境変数にAIサービスのAPIキーを設定する必要があります。

  • OPENAI_API_KEY: OpenAI API のキー

  • GOOGLE_API_KEY: Google Gemini API のキー

  • DEEPL_API_KEY: DeepL API のキー

  • lmstudio_model (オプション): LM Studio で使用するデフォルトモデル名

  • endpoint (オプション): DeepL などで使用するAPIエンドポイント

これらの環境変数は、プログラム起動前に設定しておく必要があります。

必要な入力ファイル

プログラムの動作には、主に以下の入力ファイルが必要です。

  1. ソースドキュメント:

    • 指定方法: GUIの「Input file (.docx/.pptx/.pdf/.html/.md/.rst/.txt):」フィールドでパスを指定します。

    • 期待されるファイル形式: .docx, .pptx, .pdf, .html, .htm, .md, .rst, .txt

    • 内容: 翻訳対象となるテキストが含まれるドキュメントファイルです。

    • 注意: 指定されたファイルが存在しない場合、エラーメッセージが表示され翻訳は実行されません。

  2. HTMLテンプレートファイル (任意):

    • 指定方法: GUIの「HTML template (template_translate.html):」フィールドでパスを指定します。指定がない場合、template_translate.html がデフォルトとして使用されます。

    • 期待されるファイル形式: .html, .htm

    • 内容: 翻訳後の内容を埋め込むためのHTML構造を提供するテンプレートファイルです。PDFやDOCXなどの非HTML形式の入力からHTML出力を生成する際に利用されます。

  3. 設定ファイル (自動生成/ロード): translate5_GUI.ini

    • 指定方法: プログラムと同じディレクトリに自動的に生成され、ロードされます。ユーザーが直接指定する必要はありません。

    • 期待されるファイル形式: INI形式 (テキストファイル)

    • 内容: GUIのウィンドウサイズ、直前に選択した入力ファイルパス、翻訳モード、API設定、プロンプトなどのすべてのGUI設定が保存されます。

生成される出力ファイル

translate5_GUI.py は、内部で呼び出す translate5 モジュールの機能を通じて出力ファイルを生成します。具体的なファイル名や形式は、入力ファイルの種類、選択された翻訳モード、および translate5 の内部ロジックに依存しますが、一般的な挙動は以下の通りです。

  • ファイル名: 通常、入力ファイル名に翻訳言語を示すサフィックス(例: _ja, _en)や _translated を付加し、元のファイルと同じディレクトリに保存されます。

    • 例1: input.docx を日本語から英語に翻訳 → input_en.docx

    • 例2: input.md を英語から日本語に翻訳 → input_ja.md

    • 例3: report.pdf を翻訳し、HTMLテンプレートを使用してHTML出力する場合 → report_translated.html

  • ファイル形式:

    • 入力ファイルの形式が保持されることが多いですが、translate5 の機能や使用するテンプレートによっては、PDFやDOCXなどの入力からHTML形式の出力が生成される場合があります。

    • HTMLテンプレートが指定されている場合、出力はHTMLファイルになります。

  • 内容: 翻訳されたコンテンツを含むドキュメントです。元のドキュメントの構造が可能な限り維持され、指定されたAIモデルによって翻訳されたテキストが埋め込まれます。

プログラムのソースコードでは self.cfg.output_html_path = None と設定されており、出力パスの決定は translate5 コアモジュールに委ねられています。そのため、上記の出力形式は translate5 のデフォルトの挙動に基づくものです。

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

translate5_GUI.py はGUIアプリケーションであるため、直接コマンドライン引数を取って翻訳を実行する形式ではありません。プログラムを起動するには、以下のコマンドを使用します。

python translate5_GUI.py

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

translate5_GUI.py はGUIアプリケーションであるため、コマンドラインで具体的な引数を与えて実行する操作は存在しません。すべての操作は、起動後に表示されるGUIウィンドウを通じて行われます。

以下に、GUIでの一般的な使用シナリオを説明します。

  1. プログラムの起動: ターミナルまたはコマンドプロンプトで以下のコマンドを実行し、GUIウィンドウを開きます。

    python translate5_GUI.py
    
  2. 入力ファイルの選択: 「Input file」フィールドの横にある「Browse」ボタンをクリックし、翻訳したいファイル(例: my_document.docx)を選択します。

  3. 翻訳モードの選択: 「Mode / Options」セクションで、「日本語→英語 (je)」または「英語→日本語 (ej)」のラジオボタンを選択します。

  4. APIとモデルの設定: 「API」セクションで、使用したいAPI(例: openai)をドロップダウンから選択し、次に model(例: gpt-4o)を選択します。

  5. プロンプトの調整 (任意): 「Prompts」セクションにある「Translate Prompt」や「Reformat Prompt」のテキストエリアで、翻訳やフォーマットに関する指示を編集します。

  6. 翻訳の実行: 画面下部にある「Run execute()」ボタンをクリックします。 プログラムは別スレッドで翻訳処理を開始し、ステータスバーに「Running execute() ...」と表示されます。

  7. 結果の確認: 翻訳が完了すると、ステータスバーに「Done.」と表示されます。翻訳されたファイルは、通常、元の入力ファイルと同じディレクトリに、my_document_en.docx (英語翻訳の場合) のような名前で生成されます。

このプロセスを通じて、ユーザーは直感的に翻訳設定を行い、結果を得ることができます。