translate5 プログラム仕様
translate5.py - ドキュメント翻訳・校正ツール
このモジュールは、さまざまなファイル形式(.docx, .pptx, .pdf, .html, .md, .rst, .txt)に対応し、 AIモデル(OpenAI, Gemini, LM Studio, DeepL)を使用して文書の翻訳および校正を行う コマンドラインツールを提供します。 多言語対応、翻訳単位の選択、プロンプトのカスタマイズなどの高度な機能が含まれています。
- ai.translate5.check_multibyte_str(text: str, limit_to_multibyte_str: bool) bool
テキストがマルチバイト文字を含むか、またはマルチバイト文字の有無にかかわらず処理対象とするかを判断します。
`limit_to_multibyte_str`が`True`の場合、テキストに日本語などのマルチバイト文字が 含まれているかをチェックします。`False`の場合は常に`True`を返します。
- ai.translate5.check_translation(text: str, translated: str | None, allowed_translation_length_ratio: float) bool
翻訳結果が適切であるかを複数の基準でチェックします。
翻訳結果が空でないか、Markdownのコードブロック記号で始まっていないか、 見出しレベルが極端に増加していないか、元のテキストに対する翻訳テキストの 長さの比率が許容範囲内であるかなどを確認します。
- ai.translate5.convert_to_md(infile: str) str
指定された入力ファイルをMarkdown形式に変換します。
ファイルがHTMLの場合は`html2text`を使用し、それ以外の場合は`MarkItDown`ライブラリを 使用してMarkdownに変換します。
- ai.translate5.execute(cfg: SimpleNamespace)
メインの翻訳処理を実行します。
入力ファイルのタイプに応じて適切な翻訳ロジックを選択し、ファイルを読み込み、 LLMまたはDeepLで翻訳し、結果を保存します。翻訳中にエラーが発生した場合でも、 部分的にでも結果を保存しようと試みます。 最終的に、翻訳前後のテキストを比較するHTMLレポートも生成します。
- パラメータ:
cfg (types.SimpleNamespace) -- 全てのプログラム設定を含むSimpleNamespaceオブジェクト。
- 戻り値:
なし
- 戻り値の型:
None
- ai.translate5.initialize()
プログラムの設定を初期化し、コマンドライン引数を定義します。
SimpleNamespaceオブジェクトで設定を管理し、argparseで多数のCLI引数を設定します。 APIキーやモデル、翻訳モード、処理単位などの詳細な設定が含まれます。
- 戻り値:
- tuple[types.SimpleNamespace, argparse.ArgumentParser]:
cfg: プログラム設定を含むSimpleNamespaceオブジェクト。
p: コマンドライン引数パーサー。
- ai.translate5.load_prompt_config_from_ini(args: Namespace, cfg: SimpleNamespace) SimpleNamespace
translate5.ini ファイルからプロンプト設定を読み込み、CLI引数やデフォルト値と結合します。
translate5.ini をカレントディレクトリ、入力ファイルディレクトリ、スクリプトディレクトリの順に探し、 見つかった場合は [translate], [translate_je], [translate_ej], [reformat] セクションから プロンプトを読み込みます。CLI引数が最優先され、次にINIファイル、最後に組み込みデフォルトプロンプトが適用されます。
- パラメータ:
args (argparse.Namespace) -- コマンドライン引数オブジェクト。
cfg (types.SimpleNamespace) -- 現在の設定オブジェクト。
- 戻り値:
プロンプト設定が更新された設定オブジェクト。
- 戻り値の型:
- ai.translate5.main()
プログラムのエントリポイント。
`initialize()`で設定とCLIパーサーを準備し、`update_variables()`でCLI引数を解析して 設定を更新し、`execute()`で実際の翻訳処理を開始します。
- 戻り値:
なし
- 戻り値の型:
None
- ai.translate5.n_leading_chars(s: str, c: str = '#') int
文字列の先頭にある指定された文字の数を数えます。
主にMarkdownの見出しレベル(#)やリストアイテム(*)の数を判断するために使用されます。
- ai.translate5.process_template(template: str, context: dict) str
テンプレート文字列内のプレースホルダーを置換し、特殊文字を展開します。
テンプレート文字列中の`t`, n, `r`を実際の特殊文字に変換し、 `{{ key }}`形式のプレースホルダーを`context`辞書の値で置換します。
- ai.translate5.read_file(path: str) str
指定されたパスのファイルをUTF-8エンコーディングで読み込みます。
ファイルが存在しない場合はエラーメッセージを出力し、プログラムを終了します。
- ai.translate5.revise_with_llm(text: str, prompt: str, cfg: SimpleNamespace) str
LLM(OpenAI, Gemini, LM Studio)を呼び出してテキストを翻訳または校正します。
`tkai_lib_litellm`を介してAIモデルと対話し、与えられたプロンプトに基づいてテキストを処理します。 LM Studioの場合、`reasoning_effort`を`extra_body`で渡します。
- パラメータ:
text (str) -- LLMで処理する元のテキスト。
prompt (str) -- LLMに与えるプロンプト。テンプレートとして処理されます。
cfg (types.SimpleNamespace) -- API設定、モデル名、温度、最大トークン数などが含まれる設定オブジェクト。
- 戻り値:
LLMによって処理されたテキスト。
- 戻り値の型:
- ai.translate5.to_translate(text: str | None, min_translate_length: int, limit_to_multibyte_str: bool) bool
特定のテキストブロックが翻訳対象であるかを判断します。
テキストがNoneでないか、空でないか、最小翻訳長以上であるか、そしてマルチバイト文字制限が 有効な場合はマルチバイト文字を含むかをチェックします。
- ai.translate5.translate(text: str, api: str, prompt: str, cfg: SimpleNamespace) str
翻訳処理の中核となるラッパー関数。
`translate_core`モジュールからインポートされた翻訳関数を呼び出します。 この関数がLLMの種類に応じて実際の翻訳処理を分岐させます。
- パラメータ:
text (str) -- 翻訳するテキスト。
api (str) -- 使用するAPIの種類(例: "openai", "gemini", "deepl")。
prompt (str) -- 翻訳に使用するプロンプト。
cfg (types.SimpleNamespace) -- 翻訳設定オブジェクト。
- 戻り値:
翻訳されたテキスト。
- 戻り値の型:
- ai.translate5.translate_docx(doc: Document, api: str, api_model: str, prompt: str, cfg: SimpleNamespace) tuple[Document, list]
Word文書 (.docx) の内容を翻訳します。
文書内の段落とテーブルのセルを走査し、`process_unit`設定に基づいて 段落単位またはラン(文字の連続)単位でテキストを翻訳します。
- ai.translate5.translate_html(text: str, api: str, api_model: str, prompt: str, cfg: SimpleNamespace) tuple[str | None, list]
HTMLドキュメントのテキストコンテンツを翻訳します。
`translate_backends`モジュールから`translate_html_document`を呼び出し、 HTMLからスクリプト、スタイル、コードを除外したテキストを翻訳します。
- ai.translate5.translate_pptx(ppt: Presentation, api: str, api_model: str, prompt: str, cfg: SimpleNamespace) tuple[Presentation, list]
PowerPointプレゼンテーション (.pptx) の内容を翻訳します。
各スライド内のテキストフレーム、テーブル、グループ化されたシェイプ、ノート、 チャートのタイトルやデータラベルなどを走査し、テキストを翻訳します。 `process_unit`設定に基づいて段落単位またはラン(文字の連続)単位で処理します。
- ai.translate5.translate_text(text: str, api: str, api_model: str, prompt: str, cfg: SimpleNamespace) tuple[str, list]
プレーンテキストブロック全体を翻訳します。
入力されたテキストが翻訳条件を満たす場合、`translate`関数を使用して テキスト全体を翻訳します。
- ai.translate5.translate_with_deepl(text: str, deepl_api_key: str, endpoint: str, source_lang: str = 'JA', target_lang: str = 'EN', cfg: SimpleNamespace | None = None) str
DeepL APIを使用してテキストを翻訳します。
`tkai_lib`をインポートし、DeepL APIを呼び出してテキストを翻訳します。 成功した場合は翻訳結果を返し、失敗した場合はエラーメッセージを出力し元のテキストを返します。
- パラメータ:
- 戻り値:
DeepLによって翻訳されたテキスト、またはエラーの場合は元のテキスト。
- 戻り値の型:
- 例外:
RuntimeError -- DeepLを使用する場合に`tkai_lib.py`が見つからない場合。
- ai.translate5.update_variables(cfg: SimpleNamespace, p: ArgumentParser) SimpleNamespace
コマンドライン引数を解析し、設定オブジェクト (cfg) を更新します。
argparseで解析された引数から、API、モデル、言語モード、ファイルパスなどの設定を cfg オブジェクトにコピー・正規化します。また、翻訳エンジン(translate_core)の 設定も行います。
- パラメータ:
cfg (types.SimpleNamespace) -- プログラム設定を保持するSimpleNamespaceオブジェクト。
p (argparse.ArgumentParser) -- コマンドライン引数パーサー。
- 戻り値:
更新された設定オブジェクト。
- 戻り値の型:
- ai.translate5.usage()
コマンドライン引数の使用法を出力します。
argparse.ArgumentParserオブジェクトの`print_usage()`メソッドを呼び出します。
- 戻り値:
なし
- 戻り値の型:
None