translate5 プログラム仕様
translate5.py - AI翻訳・校正ツール
このスクリプトは、OpenAI, Google Gemini, DeepLなどのAIモデルを利用して、 各種ドキュメント（.docx, .pptx, .pdf, .html, .md, .txt）の翻訳または校正を行います。 コマンドライン引数または設定ファイル（translate5.ini）を通じて、翻訳モード、使用するAPI、 モデル、プロンプトなどの詳細な設定が可能です。翻訳結果は新しいファイルとして保存され、 オプションで比較用のHTMLレポートも生成されます。
関連リンク: translate5.py 技術ドキュメント
- ai.translate5.check_multibyte_str(text, limit_to_multibyte_str)[ソース]
テキストに多バイト文字が含まれているか、または多バイト文字のチェックが不要かを判断します。
`limit_to_multibyte_str`がFalseの場合、常にTrueを返します。 Trueの場合、Unicodeの多バイト文字範囲（U+0800からU+FFFF）に一致する文字を検索します。
:param : param text: str: チェックするテキスト。 :param : param limit_to_multibyte_str: bool: 多バイト文字のみを対象とするかどうかのフラグ。
- 戻り値:
- テキストが多バイト文字を含んでいるか、または多バイト文字のチェックが不要な場合にTrue。
多バイト文字のチェックが有効で、テキストに多バイト文字が含まれない場合はFalse。
- 戻り値の型:
- ai.translate5.check_translation(text, translated, allowed_translation_length_ratio)[ソース]
翻訳結果が適切かどうかを検証します。
以下の条件で翻訳を不適切と判断します: - 翻訳結果がNoneである。 - 翻訳結果がMarkdownコードブロックの開始（'''`または```）で始まる。 - 翻訳結果が元のテキストより多くの先頭ハッシュ（#）を持つ。 - 翻訳結果が元のテキストより1つだけ多くの先頭アスタリスク（*）を持つ。 - 翻訳結果の長さが元のテキストの長さに対して`allowed_translation_length_ratio`倍を超える。
:param : param text: str: 元のテキスト。 :param : param translated: str: 翻訳されたテキスト。 :param : param allowed_translation_length_ratio: float: 翻訳されたテキストの長さが元のテキストの長さの最大何倍まで許容されるか。
- 戻り値:
翻訳結果が適切であると判断された場合にTrue、そうでない場合にFalse。
- 戻り値の型:
- ai.translate5.convert_to_md(infile)[ソース]
指定された入力ファイルをMarkdown形式に変換します。
入力ファイルがHTMLの場合、`html_to_markdown`を使用します。 その他の形式の場合、MarkItDownライブラリを使用して変換を試みます。
:param : param infile: str: 変換する入力ファイルのパス。
- 戻り値:
変換されたMarkdownテキスト。
- 戻り値の型:
- ai.translate5.execute(cfg)[ソース]
設定オブジェクトに基づき、ファイルの翻訳または校正の主要な処理を実行します。
入力ファイルのタイプを判定し、PDFのDOCX変換、Markdownへの変換、 または各ドキュメントタイプ（HTML, DOCX, PPTX, TXT, MD）に応じた 翻訳処理を呼び出します。翻訳中にエラーが発生した場合でも、 部分的にでも翻訳されたドキュメントの保存を試み、 最終的に翻訳結果の比較HTMLレポートを生成します。
:param : param cfg: types.SimpleNamespace: アプリケーションのすべての設定を保持するオブジェクト。
- ai.translate5.get_filetype(path)[ソース]
ファイルパスからファイルタイプ（拡張子に基づいたカテゴリ）を判定します。
:param : param path: str: 判定するファイルのパス。
- 戻り値:
- ファイルタイプ（"pdf", "docx", "pptx", "html", "txt", "md"）
または不明な場合はNone。
- 戻り値の型:
str or None
- ai.translate5.html_to_markdown(html_file_path)[ソース]
HTMLファイルを読み込み、その内容をMarkdown形式に変換します。
:param : param html_file_path: str: HTMLファイルのパス。
- 戻り値:
変換されたMarkdownテキスト。
- 戻り値の型:
- ai.translate5.initialize()[ソース]
アプリケーションの初期設定を行い、コマンドライン引数パーサーを構築します。
APIキーや共通設定は`translate5.env`および`ai.env`から読み込まれ、 翻訳モード、入力ファイル、使用するAPI、モデル、プロンプトなどの 各種設定のためのコマンドライン引数を定義します。
- 戻り値:
cfg: 設定値を保持するSimpleNamespaceオブジェクト。
p: コマンドライン引数を解析するためのArgumentParserオブジェクト。
- 戻り値の型:
- ai.translate5.load_prompt_config_from_ini(args, cfg)[ソース]
`translate5.ini`ファイルから翻訳および整形プロンプトを読み込み、設定オブジェクトに格納します。
- INIファイルは以下の順序で探索されます:
カレントディレクトリ
入力ファイルが存在するディレクトリ
スクリプトが実行されているディレクトリ
INIファイル内で`[translate]`または`[reformat]`セクションに`role`と`prompt`が定義されている場合、 これらは結合されて一つのプロンプトとして扱われます。 コマンドライン引数（--translate_prompt, --reformat_prompt）が最優先され、 次にINIファイルからの設定、最後に組み込みのデフォルトプロンプトが適用されます。
:param : param args: argparse.Namespace: コマンドライン引数を格納するオブジェクト。 :param : param cfg: types.SimpleNamespace: 設定値を保持するSimpleNamespaceオブジェクト。
- 戻り値:
プロンプト設定が更新されたSimpleNamespaceオブジェクト。
- 戻り値の型:
- ai.translate5.n_leading_chars(s, c='#')[ソース]
文字列の先頭にある指定された文字の数を数えます。
:param : param s: str: 処理対象の文字列。 :param : param c: str: 数える対象の文字（デフォルトは'#'）。
- 戻り値:
文字列の先頭にある指定された文字の数。
- 戻り値の型:
- ai.translate5.pdf_to_docx(pdf_file, docx_file)[ソース]
PDFファイルをDOCX形式に変換します。
:param : param pdf_file: str: 入力PDFファイルのパス。 :param : param docx_file: str: 出力DOCXファイルのパス。
- ai.translate5.process_template(template: str, context: dict) str[ソース]
テンプレート文字列内の特殊文字（t, n, r）を展開し、 `{{ key }}`形式のプレースホルダーをコンテキスト辞書の値で置換します。
:param : param template: str: 処理対象のテンプレート文字列。 :param : param context: dict: プレースホルダー置換に使用するキーと値の辞書。
- 戻り値:
プレースホルダーが置換され、特殊文字が展開された文字列。
- 戻り値の型:
- ai.translate5.read_file(path)[ソース]
指定されたパスからファイルの全内容をUTF-8エンコーディングで読み込みます。 ファイルが存在しない場合はエラーメッセージを表示し、プログラムを終了します。
:param : param path: str: 読み込むファイルのパス。
- 戻り値:
ファイルの内容。
- 戻り値の型:
- ai.translate5.replace_path(path, ext)[ソース]
指定されたファイルのパスの拡張子を新しいものに置き換えます。
:param : param path: str: 元のファイルのパス。 :param : param ext: str: 新しい拡張子（例: ".docx", ".md"）。
- 戻り値:
拡張子が置き換えられた新しいパス。
- 戻り値の型:
- ai.translate5.revise_with_google(text, google_model, prompt, temperature, max_tokens, cfg)[ソース]
Google Geminiモデル（tkai_lib.query_google2）を使用してテキストを翻訳/校正します。
:param : param text: str: 翻訳/校正する元のテキスト。 :param : param google_model: str: 使用するGoogle Geminiモデル名。 :param : param prompt: str: 翻訳/校正指示のプロンプト。 :param : param temperature: float: サンプリングの温度設定。 :param : param max_tokens: int: 生成される最大出力トークン数。 :param : param cfg: types.SimpleNamespace: 設定オブジェクト。Google APIキーなどを保持。
- 戻り値:
翻訳/校正されたテキスト。APIからの応答が無効な場合（安全フィルターなど）は空文字列。
- 戻り値の型:
- ai.translate5.revise_with_openai4(text, openai_model, prompt, temperature, max_tokens, cfg)[ソース]
OpenAI GPT-4系モデル（tkai_lib.query_openai4）を使用してテキストを翻訳/校正します。
:param : param text: str: 翻訳/校正する元のテキスト。 :param : param openai_model: str: 使用するOpenAIモデル名（例: "gpt-4o"）。 :param : param prompt: str: 翻訳/校正指示のプロンプト。 :param : param temperature: float: サンプリングの温度設定。 :param : param max_tokens: int: 生成される最大トークン数。 :param : param cfg: types.SimpleNamespace: 設定オブジェクト。OpenAI APIキーなどを保持。
- 戻り値:
翻訳/校正されたテキスト。APIからの応答がない場合は空文字列。
- 戻り値の型:
- ai.translate5.revise_with_openai5(text, openai_model5, prompt, effort, max_output_tokens, cfg)[ソース]
OpenAI GPT-5系モデル（tkai_lib.query_openai5）を使用してテキストを翻訳/校正します。
:param : param text: str: 翻訳/校正する元のテキスト。 :param : param openai_model5: str: 使用するOpenAI GPT-5系モデル名。 :param : param prompt: str: 翻訳/校正指示のプロンプト。 :param : param effort: str: GPT-5の推論努力レベル（例: "low"）。 :param : param max_output_tokens: int: 生成される最大出力トークン数。 :param : param cfg: types.SimpleNamespace: 設定オブジェクト。OpenAI APIキーなどを保持。
- 戻り値:
翻訳/校正されたテキスト。APIからの応答がない場合は空文字列。
- 戻り値の型:
- ai.translate5.save(path, text)[ソース]
指定されたパスにテキストコンテンツをUTF-8エンコーディングで保存します。
:param : param path: str: ファイルを保存するパス。 :param : param text: str: 保存するテキストコンテンツ。
- ai.translate5.to_translate(text, min_translate_length, limit_to_multibyte_str)[ソース]
与えられたテキストが翻訳の対象となるべきかを判断します。
以下の条件をチェックします: - テキストがNoneでないこと。 - テキストが空文字列でないこと。 - テキストの長さが最小翻訳長以上であること。 - `limit_to_multibyte_str`がTrueの場合、多バイト文字を含むこと。 - `limit_to_multibyte_str`がFalseの場合、または多バイト文字を含まない場合でもアルファベットを含むこと。
:param : param text: str: 翻訳対象としてチェックするテキスト。 :param : param min_translate_length: int: 翻訳対象とする最小のテキスト長。 :param : param limit_to_multibyte_str: bool: 多バイト文字のみを翻訳対象とするかのフラグ。
- 戻り値:
テキストが翻訳対象と判断される場合にTrue、そうでない場合にFalse。
- 戻り値の型:
- ai.translate5.translate(text, api, prompt, cfg)[ソース]
指定されたAPIと設定に基づいてテキストを翻訳または校正します。
:param : param text: str: 翻訳/校正する元のテキスト。 :param : param api: str: 使用するAPIの種類（"openai5", "openai", "google", "gemini", "deepl"）。 :param : param prompt: str: 翻訳/校正指示のプロンプト。 :param : param cfg: types.SimpleNamespace: 設定オブジェクト。APIキー、モデル名、温度などを保持。
- 戻り値:
翻訳/校正されたテキスト。
- 戻り値の型:
- 例外:
SystemExit -- サポートされていないAPIが指定された場合。
- ai.translate5.translate_docx(doc, api, api_model, prompt, cfg)[ソース]
Wordドキュメント（.docx）ファイル内の翻訳可能なテキスト要素をAIで翻訳します。
ドキュメントの段落とテーブルセル内のテキストを走査し、process_unit （"paragraph"または"run"）に基づいて翻訳を行います。 翻訳に失敗した場合や、`check_translation`で不適切と判断された場合は、元のテキストが保持されます。 翻訳されたすべてのオリジナルと翻訳のペアをリストに記録します。
:param : param doc: docx.Document: 翻訳対象のDocumentオブジェクト。 :param : param api: str: 使用するAPIの種類。 :param : param api_model: str: 使用するAPIのモデル名（DeepLの場合は不要だが引数として存在）。 :param : param prompt: str: 翻訳指示のプロンプト。 :param : param cfg: types.SimpleNamespace: 設定オブジェクト。最小翻訳長、多バイト文字制限、RPM待機時間などを保持。
- ai.translate5.translate_html(text, api, api_model, prompt, cfg)[ソース]
HTMLコンテンツ内の翻訳可能なテキスト要素をAIで翻訳します。
BeautifulSoupを使用してHTMLを解析し、各テキストノードを翻訳対象として処理します。 翻訳に失敗した場合や、`check_translation`で不適切と判断された場合は、元のテキストが保持されます。 翻訳されたすべてのオリジナルと翻訳のペアをリストに記録します。
:param : param text: str: 翻訳対象のHTMLコンテンツ文字列。 :param : param api: str: 使用するAPIの種類。 :param : param api_model: str: 使用するAPIのモデル名（DeepLの場合は不要だが引数として存在）。 :param : param prompt: str: 翻訳指示のプロンプト。 :param : param cfg: types.SimpleNamespace: 設定オブジェクト。最小翻訳長、多バイト文字制限、RPM待機時間などを保持。
- ai.translate5.translate_pptx(ppt, api, api_model, prompt, cfg)[ソース]
PowerPointプレゼンテーション（.pptx）ファイル内の翻訳可能なテキスト要素をAIで翻訳します。
スライド、図形、グループ、テーブル、ノート、チャートのタイトルや軸ラベルのテキストフレームを走査し、 `process_unit`（"paragraph"または"run"）に基づいて翻訳を行います。 翻訳に失敗した場合や、`check_translation`で不適切と判断された場合は、元のテキストが保持されます。 オプションでスライドマスターとレイアウトの静的テキストも翻訳します。 翻訳されたすべてのオリジナルと翻訳のペアをリストに記録します。
:param : param ppt: pptx.Presentation: 翻訳対象のPresentationオブジェクト。 :param : param api: str: 使用するAPIの種類。 :param : param api_model: str: 使用するAPIのモデル名（DeepLの場合は不要だが引数として存在）。 :param : param prompt: str: 翻訳指示のプロンプト。 :param : param cfg: types.SimpleNamespace: 設定オブジェクト。最小翻訳長、多バイト文字制限、RPM待機時間などを保持。
- ai.translate5.translate_text(text, api, api_model, prompt, cfg)[ソース]
プレーンテキストをAIで翻訳します。
単一のテキストブロック全体を翻訳対象として処理します。 翻訳に失敗した場合、元のテキストが保持されます。 翻訳されたオリジナルテキストと翻訳結果のペアをリストに記録します。
:param : param text: str: 翻訳対象のプレーンテキスト文字列。 :param : param api: str: 使用するAPIの種類。 :param : param api_model: str: 使用するAPIのモデル名（DeepLの場合は不要だが引数として存在）。 :param : param prompt: str: 翻訳指示のプロンプト。 :param : param cfg: types.SimpleNamespace: 設定オブジェクト。最小翻訳長、多バイト文字制限などを保持。
- ai.translate5.translate_with_deepl(text, deepl_api_key, endpoint, source_lang='JA', target_lang='EN', cfg=None)[ソース]
DeepL API（tkai_lib.query_deepl）を使用してテキストを翻訳します。
:param : param text: str: 翻訳する元のテキスト。 :param : param deepl_api_key: str: DeepL APIキー。 :param : param endpoint: str: DeepL APIのエンドポイントURL。 :param : param source_lang: str: ソース言語のISO 639-1コード（例: "JA"）。デフォルトは"JA"。 :param : param target_lang: str: ターゲット言語のISO 639-1コード（例: "EN"）。デフォルトは"EN"。 :param : param cfg: types.SimpleNamespace: 設定オブジェクト。APIコール間の待機時間などを保持。
- 戻り値:
翻訳されたテキスト。DeepL APIがエラーを返した場合は元のテキスト。
- 戻り値の型:
- ai.translate5.update_variables(cfg, p)[ソース]
コマンドライン引数を解析し、設定オブジェクト（cfg）を更新します。
モデルの上書き、翻訳モード（例: 'je'）からのソース言語とターゲット言語の決定、 多バイト文字のみを翻訳する設定（日本語ソースの場合）などを処理します。 また、INIファイルからのプロンプト読み込みも行い、最終的な設定を`cfg`オブジェクトに格納します。
:param : param cfg: types.SimpleNamespace: 更新前の設定値を保持するSimpleNamespaceオブジェクト。 :param : param p: argparse.ArgumentParser: コマンドライン引数を解析するためのArgumentParserオブジェクト。
- 戻り値:
コマンドライン引数とINIファイル設定で更新されたSimpleNamespaceオブジェクト。
- 戻り値の型: