translate5 プログラム仕様

translate5.py - ドキュメント翻訳・校正ツール

このモジュールは、さまざまなファイル形式(.docx, .pptx, .pdf, .html, .md, .rst, .txt)に対応し、 AIモデル(OpenAI, Gemini, LM Studio, DeepL)を使用して文書の翻訳および校正を行う コマンドラインツールを提供します。 多言語対応、翻訳単位の選択、プロンプトのカスタマイズなどの高度な機能が含まれています。

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

ai.translate5.check_multibyte_str(text: str, limit_to_multibyte_str: bool) → bool

テキストがマルチバイト文字を含むか、またはマルチバイト文字の有無にかかわらず処理対象とするかを判断します。

`limit_to_multibyte_str`が`True`の場合、テキストに日本語などのマルチバイト文字が 含まれているかをチェックします。`False`の場合は常に`True`を返します。

パラメータ:
  • text (str) -- チェック対象のテキスト。

  • limit_to_multibyte_str (bool) -- マルチバイト文字を含むテキストのみを対象とするかどうかのフラグ。

戻り値:

テキストが処理対象であるかを示す真偽値。

戻り値の型:

bool

ai.translate5.check_translation(text: str, translated: str | None, allowed_translation_length_ratio: float) → bool

翻訳結果が適切であるかを複数の基準でチェックします。

翻訳結果が空でないか、Markdownのコードブロック記号で始まっていないか、 見出しレベルが極端に増加していないか、元のテキストに対する翻訳テキストの 長さの比率が許容範囲内であるかなどを確認します。

パラメータ:
  • text (str) -- 翻訳元のテキスト。

  • translated (str or None) -- 翻訳されたテキスト。

  • allowed_translation_length_ratio (float) -- 翻訳されたテキストの長さが元のテキストの 何倍まで許容されるかの比率。

戻り値:

翻訳結果が許容できる場合はTrue、そうでない場合はFalse。

戻り値の型:

bool

ai.translate5.convert_to_md(infile: str) → str

指定された入力ファイルをMarkdown形式に変換します。

ファイルがHTMLの場合は`html2text`を使用し、それ以外の場合は`MarkItDown`ライブラリを 使用してMarkdownに変換します。

パラメータ:

infile (str) -- 入力ファイルのパス。

戻り値:

変換されたMarkdownテキスト。

戻り値の型:

str

ai.translate5.execute(cfg: SimpleNamespace)

メインの翻訳処理を実行します。

入力ファイルのタイプに応じて適切な翻訳ロジックを選択し、ファイルを読み込み、 LLMまたはDeepLで翻訳し、結果を保存します。翻訳中にエラーが発生した場合でも、 部分的にでも結果を保存しようと試みます。 最終的に、翻訳前後のテキストを比較するHTMLレポートも生成します。

パラメータ:

cfg (types.SimpleNamespace) -- 全てのプログラム設定を含むSimpleNamespaceオブジェクト。

戻り値:

なし

戻り値の型:

None

ai.translate5.get_filetype(path: str) → str | None

ファイルパスからファイルの種類(拡張子に基づく)を判定します。

パラメータ:

path (str) -- 判定対象のファイルパス。

戻り値:

ファイルの種類を示す文字列 ("pdf", "docx", "pptx", "html", "txt", "md", "rst") または認識できない場合はNone。

戻り値の型:

str or None

ai.translate5.html_to_markdown(html_file_path: str) → str

HTMLファイルを読み込み、その内容をMarkdown形式に変換します。

パラメータ:

html_file_path (str) -- 入力HTMLファイルのパス。

戻り値:

変換されたMarkdownテキスト。

戻り値の型:

str

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ファイル、最後に組み込みデフォルトプロンプトが適用されます。

パラメータ:
戻り値:

プロンプト設定が更新された設定オブジェクト。

戻り値の型:

types.SimpleNamespace

ai.translate5.main()

プログラムのエントリポイント。

`initialize()`で設定とCLIパーサーを準備し、`update_variables()`でCLI引数を解析して 設定を更新し、`execute()`で実際の翻訳処理を開始します。

戻り値:

なし

戻り値の型:

None

ai.translate5.n_leading_chars(s: str, c: str = '#') → int

文字列の先頭にある指定された文字の数を数えます。

主にMarkdownの見出しレベル(#)やリストアイテム(*)の数を判断するために使用されます。

パラメータ:
  • s (str) -- 検査対象の文字列。

  • c (str) -- 数える対象の文字(デフォルトは`#`)。

戻り値:

先頭に連続する指定文字の数。

戻り値の型:

int

ai.translate5.pdf_to_docx(pdf_file: str, docx_file: str)

PDFファイルをWord文書(.docx)に変換します。

パラメータ:
  • pdf_file (str) -- 入力PDFファイルのパス。

  • docx_file (str) -- 出力Wordファイルのパス。

戻り値:

なし

戻り値の型:

None

ai.translate5.process_template(template: str, context: dict) → str

テンプレート文字列内のプレースホルダーを置換し、特殊文字を展開します。

テンプレート文字列中の`t`, n, `r`を実際の特殊文字に変換し、 `{{ key }}`形式のプレースホルダーを`context`辞書の値で置換します。

パラメータ:
  • template (str) -- 処理対象のテンプレート文字列。

  • context (dict) -- プレースホルダーの置換に使うキーと値の辞書。

戻り値:

置換・展開済みの文字列。

戻り値の型:

str

ai.translate5.read_file(path: str) → str

指定されたパスのファイルをUTF-8エンコーディングで読み込みます。

ファイルが存在しない場合はエラーメッセージを出力し、プログラムを終了します。

パラメータ:

path (str) -- 読み込むファイルのパス。

戻り値:

ファイルの内容。

戻り値の型:

str

ai.translate5.replace_path(path: str, ext: str) → str

ファイルパスの拡張子を新しいものに置換します。

パラメータ:
  • path (str) -- 元のファイルパス。

  • ext (str) -- 新しい拡張子(例: ".docx", ".md")。

戻り値:

拡張子が置換された新しいファイルパス。

戻り値の型:

str

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によって処理されたテキスト。

戻り値の型:

str

ai.translate5.save(path: str, text: str)

指定されたパスにテキストをUTF-8エンコーディングで保存します。

パラメータ:
  • path (str) -- ファイルを保存するパス。

  • text (str) -- 保存するテキスト内容。

戻り値:

なし

戻り値の型:

None

ai.translate5.to_translate(text: str | None, min_translate_length: int, limit_to_multibyte_str: bool) → bool

特定のテキストブロックが翻訳対象であるかを判断します。

テキストがNoneでないか、空でないか、最小翻訳長以上であるか、そしてマルチバイト文字制限が 有効な場合はマルチバイト文字を含むかをチェックします。

パラメータ:
  • text (str or None) -- 翻訳対象として考慮するテキスト。

  • min_translate_length (int) -- 翻訳するテキストの最小文字長。

  • limit_to_multibyte_str (bool) -- マルチバイト文字を含むテキストのみを翻訳対象とするかどうかのフラグ。

戻り値:

テキストが翻訳対象であるかを示す真偽値。

戻り値の型:

bool

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) -- 翻訳設定オブジェクト。

戻り値:

翻訳されたテキスト。

戻り値の型:

str

ai.translate5.translate_docx(doc: Document, api: str, api_model: str, prompt: str, cfg: SimpleNamespace) → tuple[Document, list]

Word文書 (.docx) の内容を翻訳します。

文書内の段落とテーブルのセルを走査し、`process_unit`設定に基づいて 段落単位またはラン(文字の連続)単位でテキストを翻訳します。

パラメータ:
  • doc (docx.Document) -- 翻訳対象のDocumentオブジェクト。

  • api (str) -- 使用するAPIの種類。

  • api_model (str) -- 使用するAPIモデル。

  • prompt (str) -- 翻訳に使用するプロンプト。

  • cfg (types.SimpleNamespace) -- 翻訳設定オブジェクト。

戻り値:

翻訳されたDocumentオブジェクトと翻訳データのリスト。

戻り値の型:

tuple[docx.Document, list]

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からスクリプト、スタイル、コードを除外したテキストを翻訳します。

パラメータ:
  • text (str) -- 入力HTMLコンテンツ。

  • api (str) -- 使用するAPIの種類。

  • api_model (str) -- 使用するAPIモデル。

  • prompt (str) -- 翻訳に使用するプロンプト。

  • cfg (types.SimpleNamespace) -- 翻訳設定オブジェクト。

戻り値:

翻訳されたHTMLコンテンツと翻訳データのリスト。

戻り値の型:

tuple[str or None, list]

ai.translate5.translate_pptx(ppt: Presentation, api: str, api_model: str, prompt: str, cfg: SimpleNamespace) → tuple[Presentation, list]

PowerPointプレゼンテーション (.pptx) の内容を翻訳します。

各スライド内のテキストフレーム、テーブル、グループ化されたシェイプ、ノート、 チャートのタイトルやデータラベルなどを走査し、テキストを翻訳します。 `process_unit`設定に基づいて段落単位またはラン(文字の連続)単位で処理します。

パラメータ:
  • ppt (pptx.Presentation) -- 翻訳対象のPresentationオブジェクト。

  • api (str) -- 使用するAPIの種類。

  • api_model (str) -- 使用するAPIモデル。

  • prompt (str) -- 翻訳に使用するプロンプト。

  • cfg (types.SimpleNamespace) -- 翻訳設定オブジェクト。

戻り値:

翻訳されたPresentationオブジェクトと翻訳データのリスト。

戻り値の型:

tuple[pptx.Presentation, list]

ai.translate5.translate_text(text: str, api: str, api_model: str, prompt: str, cfg: SimpleNamespace) → tuple[str, list]

プレーンテキストブロック全体を翻訳します。

入力されたテキストが翻訳条件を満たす場合、`translate`関数を使用して テキスト全体を翻訳します。

パラメータ:
  • text (str) -- 翻訳対象のプレーンテキスト。

  • api (str) -- 使用するAPIの種類。

  • api_model (str) -- 使用するAPIモデル。

  • prompt (str) -- 翻訳に使用するプロンプト。

  • cfg (types.SimpleNamespace) -- 翻訳設定オブジェクト。

戻り値:

翻訳されたテキストと翻訳データのリスト。

戻り値の型:

tuple[str, list]

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を呼び出してテキストを翻訳します。 成功した場合は翻訳結果を返し、失敗した場合はエラーメッセージを出力し元のテキストを返します。

パラメータ:
  • text (str) -- 翻訳する元のテキスト。

  • deepl_api_key (str) -- DeepL APIのキー。

  • endpoint (str) -- DeepL APIのエンドポイントURL。

  • source_lang (str) -- (オプション) ソース言語のコード(デフォルト: "JA")。

  • target_lang (str) -- (オプション) ターゲット言語のコード(デフォルト: "EN")。

  • cfg (types.SimpleNamespace or None) -- (オプション) 設定オブジェクト。`tsleep_rpm`のために使用。

戻り値:

DeepLによって翻訳されたテキスト、またはエラーの場合は元のテキスト。

戻り値の型:

str

例外:

RuntimeError -- DeepLを使用する場合に`tkai_lib.py`が見つからない場合。

ai.translate5.update_variables(cfg: SimpleNamespace, p: ArgumentParser) → SimpleNamespace

コマンドライン引数を解析し、設定オブジェクト (cfg) を更新します。

argparseで解析された引数から、API、モデル、言語モード、ファイルパスなどの設定を cfg オブジェクトにコピー・正規化します。また、翻訳エンジン(translate_core)の 設定も行います。

パラメータ:
戻り値:

更新された設定オブジェクト。

戻り値の型:

types.SimpleNamespace

ai.translate5.usage()

コマンドライン引数の使用法を出力します。

argparse.ArgumentParserオブジェクトの`print_usage()`メソッドを呼び出します。

戻り値:

なし

戻り値の型:

None