"""
translate5.py - ドキュメント翻訳・校正ツール

このモジュールは、さまざまなファイル形式（.docx, .pptx, .pdf, .html, .md, .rst, .txt）に対応し、
AIモデル（OpenAI, Gemini, LM Studio, DeepL）を使用して文書の翻訳および校正を行う
コマンドラインツールを提供します。
多言語対応、翻訳単位の選択、プロンプトのカスタマイズなどの高度な機能が含まれています。

:doc:`translate5_usage`
"""
import os
import sys
import argparse
import time
import re
from pathlib import Path
from types import SimpleNamespace
from urllib.parse import urlparse
from configparser import ConfigParser

missing = []
for lib in [
    "chardet",
    "bs4",
    "jinja2",
    "html2text",
    "pdf2docx",
    "docx",
    "pptx",
    "markitdown",
]:
    try:
        __import__(lib)
    except ImportError:
        missing.append(lib)

if missing:
    print(f"Error: Missing libraries:\n{', '.join(missing)}")
    input("\nPress ENTER to terminate>>\n")
    sys.exit(1)

import chardet
from bs4 import BeautifulSoup
from jinja2 import Environment, FileSystemLoader
import html2text

from pdf2docx import Converter
from docx import Document
from pptx import Presentation
from pptx.enum.shapes import MSO_SHAPE_TYPE
from markitdown import MarkItDown

# LLMへの問い合わせは、OpenAI / Gemini / LM Studioを共通に扱う。
from tkai_lib_litellm import read_ai_config, query_ai, query_ai_compatible, extract_text
from translate_core import configure_translation_cfg, translate as translate_core
from translate_backends import (
    translate_html_document,
    translate_markdown_document,
    translate_rst_document,
)


#=========================================================
# 初期化
#=========================================================

parser = None


def initialize():
    """
    プログラムの設定を初期化し、コマンドライン引数を定義します。

    SimpleNamespaceオブジェクトで設定を管理し、argparseで多数のCLI引数を設定します。
    APIキーやモデル、翻訳モード、処理単位などの詳細な設定が含まれます。

    :returns:
        tuple[types.SimpleNamespace, argparse.ArgumentParser]:
            - `cfg`: プログラム設定を含むSimpleNamespaceオブジェクト。
            - `p`: コマンドライン引数パーサー。
    """
    cfg = SimpleNamespace()
    cfg.config_path = "translate5.env"
    cfg.common_config_path = "ai.env"

    # APIキーや共通設定は従来どおり .env / ai.env から
    read_ai_config(cfg.config_path, read_account_inf=False)
    read_ai_config(cfg.common_config_path)

    p = argparse.ArgumentParser(description="Translate/Revise .docx/.pptx/.pdf/.html/.md")

    p.add_argument("--mode", default="je", help="Translation mode (je, ej, jj, etc.)")
    p.add_argument(
        "--infile", "-i",
        default="translate_test.docx",
        help="Input file (.docx/.pptx/.pdf/.html/.md/.rst/.txt)",
    )
    p.add_argument(
        "--output_html_path",
        default=None,
        help="Path for the output HTML file (comparison report, optional)",
    )
    p.add_argument(
        "--html_template_path",
        default="template_translate.html",
        help="Path to the HTML template file for comparison report",
    )

    p.add_argument(
        "--api",
        default="openai5",
        choices=["openai", "gemini", "lmstudio", "deepl", "openai5", "google"],
        help="Translation API to use",
    )
    p.add_argument("--model", default=None, help="Override API model")
    p.add_argument("--endpoint", default=os.getenv("endpoint"), help="API endpoint")

    p.add_argument(
        "--max_tokens",
        type=int,
        default=int(os.getenv("max_tokens", "2000")),
        help="Maximum number of tokens / output length",
    )
    p.add_argument(
        "--openai_api_key",
        default=os.getenv("OPENAI_API_KEY"),
        help="OpenAI API key",
    )
    p.add_argument(
        "--openai_model",
        default=os.getenv("openai_model", "gpt-4o"),
        help="OpenAI model to use",
    )
    p.add_argument(
        "--temperature",
        type=float,
        default=float(os.getenv("temperature", "0.3")),
        help="Sampling temperature",
    )
    p.add_argument(
        "--openai_model5",
        default=os.getenv("openai_model5", "gpt-5.2"),
        help="OpenAI GPT-5 model",
    )
    p.add_argument(
        "--reasoning-effort", "--reasoning_effort",
        dest="reasoning_effort",
        default=os.getenv("reasoning_effort", "low"),
        help=(
            "Reasoning effort. For LM Studio Qwen3.8: low, medium, xhigh "
            "(default: low)"
        ),
    )
    p.add_argument(
        "--google_api_key",
        default=os.getenv("GOOGLE_API_KEY"),
        help="Google API key",
    )
    p.add_argument(
        "--google_model",
        default=os.getenv("google_model", "gemini-2.5-flash"),
        help="Google/Gemini model to use",
    )
    p.add_argument(
        "--lmstudio_model",
        default=os.getenv("lmstudio_model") or os.getenv("LMSTUDIO_MODEL"),
        help="LM Studio model to use when --api lmstudio",
    )
    p.add_argument(
        "--deepl_api_key",
        default=os.getenv("DEEPL_API_KEY"),
        help="DeepL API key",
    )

    p.add_argument(
        "--force_server_charcode",
        default=os.getenv("force_server_charcode", "utf-8"),
        help="force_server_charcode",
    )
    p.add_argument(
        "--tsleep_rpm",
        type=float,
        default=0.5,
        help="Sleep time to avoid rpm (seconds)",
    )

    p.add_argument("--use_md", action="store_true", help="Convert to markdown and process")
    p.add_argument(
        "--limit_to_multibyte_str",
        action="store_true",
        help="When set, only translate text containing multibyte chars (e.g. Japanese)",
    )

    p.add_argument(
        "--process_unit",
        default="paragraph",
        choices=["paragraph", "run"],
        help="Unit of processing for docx/pptx/html",
    )
    p.add_argument(
        "--min_translate_length",
        type=int,
        default=int(os.getenv("min_translate_length", "5")),
        help="Minimum length of text to translate",
    )
    p.add_argument(
        "--allowed_translation_length_ratio",
        type=float,
        default=float(os.getenv("allowed_translation_length_ratio", "5.0")),
        help="Max allowed ratio (translated_len / original_len)",
    )

    # ★ CLI からは prompt 本文のみ上書き可能（roleは統合済み）
    p.add_argument(
        "--translate_prompt",
        type=str,
        default="",
        help="Override translation prompt (full instructions incl. 'あなたは〜').",
    )
    p.add_argument(
        "--reformat_prompt",
        type=str,
        default="",
        help="Override reformat prompt (full instructions).",
    )

    return cfg, p


def _prompt_from_section(cp: ConfigParser, section: str) -> str | None:
    """
    ConfigParserから指定されたセクションのプロンプトを読み込みます。

    既存の`role`と`prompt`の構文を維持し、それらを結合して単一のプロンプト文字列を生成します。
    `role`のみが存在する場合も考慮します。

    :param cp: プロンプト設定が格納されたConfigParserオブジェクト。
    :type cp: configparser.ConfigParser
    :param section: 読み込むセクション名。
    :type section: str
    :returns: 結合されたプロンプト文字列、またはセクションが存在しない場合はNone。
    :rtype: str or None
    """
    if not cp.has_section(section):
        return None
    role_val = cp.get(section, "role", fallback="").strip()
    prompt_val = cp.get(section, "prompt", fallback="").lstrip("\n")
    if role_val and prompt_val:
        return (role_val + "\n" + prompt_val).strip()
    return prompt_val.strip() or role_val or None


def _default_translate_prompt(mode: str) -> str:
    """
    指定された翻訳モードに対応するデフォルトの翻訳プロンプトを生成します。

    翻訳の方向（例: `je` = 日本語から英語）に応じて、プロンプトのターゲット言語を調整します。
    AIアシスタントに専門的な文書翻訳の条件を指示します。

    :param mode: 翻訳モード（例: "je", "ej"）。
    :type mode: str
    :returns: デフォルトの翻訳プロンプト文字列。
    :rtype: str
    """
    target = "自然な米国英語" if mode == "je" else "自然で専門的な日本語"
    return (
        "あなたは専門的な文書を正確かつプロフェッショナルに翻訳・校正するアシスタントです。\n"
        f"以下の条件を守り、*#翻訳してほしいテキスト*以降のテキストを{target}に翻訳してください。\n"
        "条件1：元の意味を変えない。テキストに書かれていない解釈・内容は追加しない。\n"
        "条件2：文字数を大きく増やさない（目安 ±30%）。\n"
        "条件3：動詞を含まない短いフレーズはスライド見出しとして扱い、完全な文にしない。\n"
        "条件4：数式・記号・固有名詞・プレースホルダは可能な限り保持する。\n"
        "{{additional_prompt}}\n\n#翻訳してほしいテキスト\n{{text}}"
    )


def load_prompt_config_from_ini(args: argparse.Namespace, cfg: SimpleNamespace) -> SimpleNamespace:
    """
    `translate5.ini` ファイルからプロンプト設定を読み込み、CLI引数やデフォルト値と結合します。

    `translate5.ini` をカレントディレクトリ、入力ファイルディレクトリ、スクリプトディレクトリの順に探し、
    見つかった場合は `[translate]`, `[translate_je]`, `[translate_ej]`, `[reformat]` セクションから
    プロンプトを読み込みます。CLI引数が最優先され、次にINIファイル、最後に組み込みデフォルトプロンプトが適用されます。

    :param args: コマンドライン引数オブジェクト。
    :type args: argparse.Namespace
    :param cfg: 現在の設定オブジェクト。
    :type cfg: types.SimpleNamespace
    :returns: プロンプト設定が更新された設定オブジェクト。
    :rtype: types.SimpleNamespace
    """

    ini_name = "translate5.ini"
    candidate_paths = []

    # 1. 作業ディレクトリ
    candidate_paths.append(os.path.join(os.getcwd(), ini_name))

    # 2. 入力ファイルディレクトリ
    if getattr(args, "infile", None):
        infile_abs = os.path.abspath(args.infile)
        infile_dir = os.path.dirname(infile_abs)
        candidate_paths.append(os.path.join(infile_dir, ini_name))

    # 3. スクリプトディレクトリ
    script_dir = os.path.dirname(os.path.abspath(__file__))
    candidate_paths.append(os.path.join(script_dir, ini_name))

    ini_path = None
    for p in candidate_paths:
        if os.path.isfile(p):
            ini_path = p
            break

    translate_prompts_ini = {}
    reformat_prompt_ini = None

    if ini_path:
        print(f"  Using prompt config file: {ini_path}")
        cp = ConfigParser()
        cp.read(ini_path, encoding="utf-8")

        # Direction-specific sections are preferred.  [translate] remains a
        # backward-compatible fallback for old INI files.
        fallback_prompt = _prompt_from_section(cp, "translate")
        for mode in ("je", "ej"):
            translate_prompts_ini[mode] = (
                _prompt_from_section(cp, f"translate_{mode}") or fallback_prompt
            )

        # [reformat]
        if cp.has_section("reformat"):
            role_val = cp.get("reformat", "role", fallback="").strip()
            prompt_val = cp.get("reformat", "prompt", fallback="")
            prompt_val = prompt_val.lstrip("\n")
            if role_val and prompt_val:
                reformat_prompt_ini = (role_val + "\n" + prompt_val).strip()
            elif prompt_val:
                reformat_prompt_ini = prompt_val.strip()
            elif role_val:
                reformat_prompt_ini = role_val
    else:
        print("  translate5.ini not found. Using built-in default prompts.")

    # ---- 組込みデフォルト (role+prompt一体型) ----

    for mode in ("je", "ej"):
        if not translate_prompts_ini.get(mode):
            translate_prompts_ini[mode] = _default_translate_prompt(mode)

    if not reformat_prompt_ini:
        reformat_prompt_ini = (
            "あなたは専門的な英語文書を、内容を変えずに読みやすく整形するアシスタントです。\n"
            "以下の*＃テキスト*以降は PDF やスライドから抽出したテキストであり、"
            "改行位置や段落順が乱れたり、文が途中で分断されている可能性があります。\n"
            "元の意味・情報を一切削除・要約・追加せず、文や段落のつながりが自然になるように"
            "並び替えと改行のみを調整してください。\n"
            "箇条書きや見出しらしき部分は、その構造を保ってください。\n"
            "出力はプレーンテキストのみとし、余計な説明文は付けないでください。\n\n"
            "＃テキスト\n{{ text }}"
        )

    # ---- 優先順位適用: CLI > ini/結合 > デフォルト ----
    selected_mode = (args.mode or "je").lower()
    cfg.translate_prompts = translate_prompts_ini
    cfg.translate_prompt = (
        args.translate_prompt
        if args.translate_prompt
        else translate_prompts_ini.get(selected_mode, translate_prompts_ini["je"])
    )
    cfg.reformat_prompt = args.reformat_prompt if args.reformat_prompt else reformat_prompt_ini

    # role は内部的には空文字で扱う（全部入りプロンプトで運用）
    cfg.translate_role = ""
    cfg.reformat_role = ""

    return cfg


def update_variables(cfg: SimpleNamespace, p: argparse.ArgumentParser) -> SimpleNamespace:
    """
    コマンドライン引数を解析し、設定オブジェクト (`cfg`) を更新します。

    argparseで解析された引数から、API、モデル、言語モード、ファイルパスなどの設定を
    `cfg` オブジェクトにコピー・正規化します。また、翻訳エンジン（`translate_core`）の
    設定も行います。

    :param cfg: プログラム設定を保持するSimpleNamespaceオブジェクト。
    :type cfg: types.SimpleNamespace
    :param p: コマンドライン引数パーサー。
    :type p: argparse.ArgumentParser
    :returns: 更新された設定オブジェクト。
    :rtype: types.SimpleNamespace
    """
    args = p.parse_args()

    # 旧名は受け付けるが、以後はtkai_lib_litellmのprovider名へ正規化する。
    api_aliases = {"openai5": "openai", "google": "gemini"}
    normalized_api = api_aliases.get(args.api, args.api)

    # モデル上書き
    if args.model is not None:
        if args.api == "openai5":
            args.openai_model5 = args.model
        elif args.api == "openai":
            args.openai_model = args.model
        elif args.api in ("google", "gemini"):
            args.google_model = args.model
        elif args.api == "lmstudio":
            args.lmstudio_model = args.model

    # mode から言語方向
    if args.mode[0] == "j":
        args.source_lang = "JA"
        # GUI側で既に設定済みでも、CLI/デフォルトロジックに合わせて再度設定
        if not args.limit_to_multibyte_str:
            args.limit_to_multibyte_str = True
    else:
        args.source_lang = "EN"
        if args.mode[0] != "j":
            # 英語ソースの場合は明示的にFalseにする
            args.limit_to_multibyte_str = False

    if args.mode[1] == "j":
        args.target_lang = "JA"
    else:
        args.target_lang = "EN"

    # cfg に基本情報コピー
    cfg.infile = args.infile
    cfg.api = normalized_api
    cfg.openai_model = args.openai_model
    cfg.openai_model5 = args.openai_model5
    cfg.google_model = args.google_model
    cfg.lmstudio_model = args.lmstudio_model or "qwen/qwen3.8-27b"
    cfg.deepl_api_key = args.deepl_api_key
    cfg.endpoint = args.endpoint
    cfg.max_tokens = args.max_tokens
    cfg.temperature = args.temperature
    cfg.reasoning_effort = args.reasoning_effort
    cfg.tsleep_rpm = args.tsleep_rpm
    cfg.use_md = args.use_md
    cfg.limit_to_multibyte_str = args.limit_to_multibyte_str
    cfg.process_unit = args.process_unit
    cfg.min_translate_length = args.min_translate_length
    cfg.allowed_translation_length_ratio = args.allowed_translation_length_ratio
    cfg.mode = args.mode
    cfg.source_lang = args.source_lang
    cfg.target_lang = args.target_lang
    cfg.html_template_path = args.html_template_path

    cfg.openai_api_key = args.openai_api_key
    cfg.google_api_key = args.google_api_key

    if cfg.api == "lmstudio":
        cfg.model = cfg.lmstudio_model
    elif args.api == "openai5":
        cfg.model = cfg.openai_model5
    elif cfg.api == "gemini":
        cfg.model = cfg.google_model
    else:
        cfg.model = cfg.openai_model

    configure_translation_cfg(
        cfg,
        api=args.api,
        model=cfg.model,
        mode=args.mode,
        endpoint=args.endpoint,
        deepl_api_key=args.deepl_api_key,
        temperature=args.temperature,
        max_tokens=cfg.max_tokens,
        reasoning_effort=cfg.reasoning_effort,
        min_translate_length=cfg.min_translate_length,
        allowed_translation_length_ratio=cfg.allowed_translation_length_ratio,
        limit_to_multibyte_str=cfg.limit_to_multibyte_str,
        tsleep_rpm=cfg.tsleep_rpm,
    )

    # ini + デフォルト + CLI 上書きで prompt を確定（roleは内部で空）
    cfg = load_prompt_config_from_ini(args, cfg)

    return cfg


def usage():
    """
    コマンドライン引数の使用法を出力します。

    argparse.ArgumentParserオブジェクトの`print_usage()`メソッドを呼び出します。

    :returns: なし
    :rtype: None
    """
    global parser
    if parser:
        parser.print_usage()


# ------------------------------------------------------
# ユーティリティ
# ------------------------------------------------------
def process_template(template: str, context: dict) -> str:
    """
    テンプレート文字列内のプレースホルダーを置換し、特殊文字を展開します。

    テンプレート文字列中の`\\t`, `\\n`, `\\r`を実際の特殊文字に変換し、
    `{{ key }}`形式のプレースホルダーを`context`辞書の値で置換します。

    :param template: 処理対象のテンプレート文字列。
    :type template: str
    :param context: プレースホルダーの置換に使うキーと値の辞書。
    :type context: dict
    :returns: 置換・展開済みの文字列。
    :rtype: str
    """
    template = template.replace(r"\t", "\t")
    template = template.replace(r"\n", "\n")
    template = template.replace(r"\r", "\r")

    def replace_placeholder(match):
        key = match.group(1).strip()
        return str(context.get(key, f"{{{{ {key} }}}}"))

    return re.sub(r"\{\{\s*(.*?)\s*\}\}", replace_placeholder, template)


def save(path: str, text: str):
    """
    指定されたパスにテキストをUTF-8エンコーディングで保存します。

    :param path: ファイルを保存するパス。
    :type path: str
    :param text: 保存するテキスト内容。
    :type text: str
    :returns: なし
    :rtype: None
    """
    with open(path, "w", encoding="utf-8") as f:
        f.write(text)


def read_file(path: str) -> str:
    """
    指定されたパスのファイルをUTF-8エンコーディングで読み込みます。

    ファイルが存在しない場合はエラーメッセージを出力し、プログラムを終了します。

    :param path: 読み込むファイルのパス。
    :type path: str
    :returns: ファイルの内容。
    :rtype: str
    """
    if not os.path.exists(path):
        print(f"\nError in read_file(): File [{path}] does not exist\n")
        sys.exit(1)
    with open(path, "r", encoding="utf-8") as fp:
        return fp.read()


def replace_path(path: str, ext: str) -> str:
    """
    ファイルパスの拡張子を新しいものに置換します。

    :param path: 元のファイルパス。
    :type path: str
    :param ext: 新しい拡張子（例: ".docx", ".md"）。
    :type ext: str
    :returns: 拡張子が置換された新しいファイルパス。
    :rtype: str
    """
    return os.path.splitext(path)[0] + ext


def check_multibyte_str(text: str, limit_to_multibyte_str: bool) -> bool:
    """
    テキストがマルチバイト文字を含むか、またはマルチバイト文字の有無にかかわらず処理対象とするかを判断します。

    `limit_to_multibyte_str`が`True`の場合、テキストに日本語などのマルチバイト文字が
    含まれているかをチェックします。`False`の場合は常に`True`を返します。

    :param text: チェック対象のテキスト。
    :type text: str
    :param limit_to_multibyte_str: マルチバイト文字を含むテキストのみを対象とするかどうかのフラグ。
    :type limit_to_multibyte_str: bool
    :returns: テキストが処理対象であるかを示す真偽値。
    :rtype: bool
    """
    if not limit_to_multibyte_str:
        return True
    pattern = re.compile(r"[\u0800-\uFFFF]")
    return bool(pattern.search(text))


def html_to_markdown(html_file_path: str) -> str:
    """
    HTMLファイルを読み込み、その内容をMarkdown形式に変換します。

    :param html_file_path: 入力HTMLファイルのパス。
    :type html_file_path: str
    :returns: 変換されたMarkdownテキスト。
    :rtype: str
    """
    with open(html_file_path, "r", encoding="utf-8") as html_file:
        html_content = html_file.read()
    return html2text.html2text(html_content)


def convert_to_md(infile: str) -> str:
    """
    指定された入力ファイルをMarkdown形式に変換します。

    ファイルがHTMLの場合は`html2text`を使用し、それ以外の場合は`MarkItDown`ライブラリを
    使用してMarkdownに変換します。

    :param infile: 入力ファイルのパス。
    :type infile: str
    :returns: 変換されたMarkdownテキスト。
    :rtype: str
    """
    if ".html" in infile.lower():
        return html_to_markdown(infile)
    else:
        print(f"Convert {infile} to markdown")
        md = MarkItDown()
        result = md.convert(infile)
        return result.text_content


def n_leading_chars(s: str, c: str = "#") -> int:
    """
    文字列の先頭にある指定された文字の数を数えます。

    主にMarkdownの見出しレベル（`#`）やリストアイテム（`*`）の数を判断するために使用されます。

    :param s: 検査対象の文字列。
    :type s: str
    :param c: 数える対象の文字（デフォルトは`#`）。
    :type c: str
    :returns: 先頭に連続する指定文字の数。
    :rtype: int
    """
    return len(s) - len(s.lstrip(c))


def pdf_to_docx(pdf_file: str, docx_file: str):
    """
    PDFファイルをWord文書（.docx）に変換します。

    :param pdf_file: 入力PDFファイルのパス。
    :type pdf_file: str
    :param docx_file: 出力Wordファイルのパス。
    :type docx_file: str
    :returns: なし
    :rtype: None
    """
    cv = Converter(pdf_file)
    cv.convert(docx_file, start=0, end=None)
    cv.close()
    print(f"Converted '{pdf_file}' to '{docx_file}' successfully.")


def get_filetype(path: str) -> str | None:
    """
    ファイルパスからファイルの種類（拡張子に基づく）を判定します。

    :param path: 判定対象のファイルパス。
    :type path: str
    :returns: ファイルの種類を示す文字列
              ("pdf", "docx", "pptx", "html", "txt", "md", "rst")
              または認識できない場合はNone。
    :rtype: str or None
    """
    ext = os.path.splitext(path)[1].lower()
    if ext == ".pdf":
        return "pdf"
    if ext == ".docx":
        return "docx"
    if ext == ".pptx":
        return "pptx"
    if ext in (".html", ".htm"):
        return "html"
    if ext in (".txt", ".text"):
        return "txt"
    if ext == ".md":
        return "md"
    if ext == ".rst":
        return "rst"
    return None


def to_translate(text: str | None, min_translate_length: int, limit_to_multibyte_str: bool) -> bool:
    """
    特定のテキストブロックが翻訳対象であるかを判断します。

    テキストがNoneでないか、空でないか、最小翻訳長以上であるか、そしてマルチバイト文字制限が
    有効な場合はマルチバイト文字を含むかをチェックします。

    :param text: 翻訳対象として考慮するテキスト。
    :type text: str or None
    :param min_translate_length: 翻訳するテキストの最小文字長。
    :type min_translate_length: int
    :param limit_to_multibyte_str: マルチバイト文字を含むテキストのみを翻訳対象とするかどうかのフラグ。
    :type limit_to_multibyte_str: bool
    :returns: テキストが翻訳対象であるかを示す真偽値。
    :rtype: bool
    """
    if text is None:
        return False
    text0 = text.strip()
    if text0 == "":
        return False
    if len(text0) < min_translate_length:
        return False

    is_mb = check_multibyte_str(text0, limit_to_multibyte_str)

    if not is_mb and not bool(re.search("[a-zA-Z]", text0)):
        return False

    return is_mb if limit_to_multibyte_str else True


# ------------------------------------------------------
# 翻訳系ラッパ
# ------------------------------------------------------
def 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`で渡します。

    :param text: LLMで処理する元のテキスト。
    :type text: str
    :param prompt: LLMに与えるプロンプト。テンプレートとして処理されます。
    :type prompt: str
    :param cfg: API設定、モデル名、温度、最大トークン数などが含まれる設定オブジェクト。
    :type cfg: types.SimpleNamespace
    :returns: LLMによって処理されたテキスト。
    :rtype: str
    """
    prompt_text = process_template(
        prompt,
        {
            "text": text,
            "additional_prompt": (
                "翻訳・校正結果のみを出力してください。"
                "前置きや後付けのメッセージは不要です。"
            ),
        },
    )

    if cfg.api == "lmstudio":
        # Qwen3.8の推論量はLM Studio OpenAI互換APIのextra_bodyへ渡す。
        call_kwargs = {
            "temperature": cfg.temperature,
            "max_tokens": cfg.max_tokens,
        }
        if cfg.reasoning_effort:
            call_kwargs["extra_body"] = {
                "reasoning_effort": cfg.reasoning_effort,
            }
        response = query_ai(
            prompt=prompt_text,
            model=cfg.model,
            role="",
            provider="lmstudio",
            **call_kwargs,
        )
    else:
        response = query_ai_compatible(
            prompt=prompt_text,
            model=cfg.model,
            role="",
            provider=cfg.api,
            temperature=cfg.temperature,
            max_tokens=cfg.max_tokens,
            reasoning_effort=cfg.reasoning_effort,
        )

    text_out = extract_text(response)
    if not text_out:
        return ""

    usage = getattr(response, "usage", None)
    if usage:
        print(f"  prompt_tokens     : {getattr(usage, 'prompt_tokens', 'n/a')}")
        print(f"  completion_tokens: {getattr(usage, 'completion_tokens', 'n/a')}")

    if cfg.tsleep_rpm > 0:
        time.sleep(cfg.tsleep_rpm)

    return text_out.strip()


def 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を呼び出してテキストを翻訳します。
    成功した場合は翻訳結果を返し、失敗した場合はエラーメッセージを出力し元のテキストを返します。

    :param text: 翻訳する元のテキスト。
    :type text: str
    :param deepl_api_key: DeepL APIのキー。
    :type deepl_api_key: str
    :param endpoint: DeepL APIのエンドポイントURL。
    :type endpoint: str
    :param source_lang: (オプション) ソース言語のコード（デフォルト: "JA"）。
    :type source_lang: str
    :param target_lang: (オプション) ターゲット言語のコード（デフォルト: "EN"）。
    :type target_lang: str
    :param cfg: (オプション) 設定オブジェクト。`tsleep_rpm`のために使用。
    :type cfg: types.SimpleNamespace or None
    :returns: DeepLによって翻訳されたテキスト、またはエラーの場合は元のテキスト。
    :rtype: str
    :raises RuntimeError: DeepLを使用する場合に`tkai_lib.py`が見つからない場合。
    """
    # DeepL はLLM APIではないため、必要時だけ従来ライブラリを読み込む。
    try:
        from tkai_lib import query_deepl, extract_deepl_text
    except ImportError as exc:
        raise RuntimeError(
            "DeepLを使う場合は従来の tkai_lib.py も必要です。"
        ) from exc

    response = query_deepl(
        text,
        source_lang,
        target_lang,
        deepl_api_key=deepl_api_key,
        endpoint=endpoint,
    )

    if cfg and cfg.tsleep_rpm > 0:
        time.sleep(cfg.tsleep_rpm)

    if response.status_code == 200:
        return extract_deepl_text(response)
    else:
        print(f"Error: {response.status_code}, {response.text}")
        return text


def translate(text: str, api: str, prompt: str, cfg: SimpleNamespace) -> str:
    """
    翻訳処理の中核となるラッパー関数。

    `translate_core`モジュールからインポートされた翻訳関数を呼び出します。
    この関数がLLMの種類に応じて実際の翻訳処理を分岐させます。

    :param text: 翻訳するテキスト。
    :type text: str
    :param api: 使用するAPIの種類（例: "openai", "gemini", "deepl"）。
    :type api: str
    :param prompt: 翻訳に使用するプロンプト。
    :type prompt: str
    :param cfg: 翻訳設定オブジェクト。
    :type cfg: types.SimpleNamespace
    :returns: 翻訳されたテキスト。
    :rtype: str
    """
    # translate_core は URL/COM 版とも共有する唯一のAPI分岐点。
    return translate_core(text, prompt, cfg)


# ------------------------------------------------------
# 翻訳結果チェック
# ------------------------------------------------------
def check_translation(text: str, translated: str | None, allowed_translation_length_ratio: float) -> bool:
    """
    翻訳結果が適切であるかを複数の基準でチェックします。

    翻訳結果が空でないか、Markdownのコードブロック記号で始まっていないか、
    見出しレベルが極端に増加していないか、元のテキストに対する翻訳テキストの
    長さの比率が許容範囲内であるかなどを確認します。

    :param text: 翻訳元のテキスト。
    :type text: str
    :param translated: 翻訳されたテキスト。
    :type translated: str or None
    :param allowed_translation_length_ratio: 翻訳されたテキストの長さが元のテキストの
                                             何倍まで許容されるかの比率。
    :type allowed_translation_length_ratio: float
    :returns: 翻訳結果が許容できる場合はTrue、そうでない場合はFalse。
    :rtype: bool
    """
    if translated is None:
        return False
    if translated.startswith("'''"):
        return False
    if translated.startswith("```"):
        return False

    ntranslated = n_leading_chars(translated, "#")
    ntext = n_leading_chars(text, "#")
    if ntranslated > ntext:
        return False

    ntranslated = n_leading_chars(translated, "*")
    ntext = n_leading_chars(text, "*")
    if ntranslated == ntext + 1:
        return False

    if len(text) > 0 and len(translated) > len(text) * allowed_translation_length_ratio:
        return False

    return True


# ------------------------------------------------------
# 各フォーマット別処理
# ------------------------------------------------------
def translate_html(text: str, api: str, api_model: str, prompt: str, cfg: SimpleNamespace) -> tuple[str | None, list]:
    """
    HTMLドキュメントのテキストコンテンツを翻訳します。

    `translate_backends`モジュールから`translate_html_document`を呼び出し、
    HTMLからスクリプト、スタイル、コードを除外したテキストを翻訳します。

    :param text: 入力HTMLコンテンツ。
    :type text: str
    :param api: 使用するAPIの種類。
    :type api: str
    :param api_model: 使用するAPIモデル。
    :type api_model: str
    :param prompt: 翻訳に使用するプロンプト。
    :type prompt: str
    :param cfg: 翻訳設定オブジェクト。
    :type cfg: types.SimpleNamespace
    :returns: 翻訳されたHTMLコンテンツと翻訳データのリスト。
    :rtype: tuple[str or None, list]
    """
    print("\n>>> Analyzing HTML (script/style/code are excluded)...")
    return translate_html_document(text, prompt, cfg)


def translate_pptx(ppt: Presentation, api: str, api_model: str, prompt: str, cfg: SimpleNamespace) -> tuple[Presentation, list]:
    """
    PowerPointプレゼンテーション (.pptx) の内容を翻訳します。

    各スライド内のテキストフレーム、テーブル、グループ化されたシェイプ、ノート、
    チャートのタイトルやデータラベルなどを走査し、テキストを翻訳します。
    `process_unit`設定に基づいて段落単位またはラン（文字の連続）単位で処理します。

    :param ppt: 翻訳対象のPresentationオブジェクト。
    :type ppt: pptx.Presentation
    :param api: 使用するAPIの種類。
    :type api: str
    :param api_model: 使用するAPIモデル。
    :type api_model: str
    :param prompt: 翻訳に使用するプロンプト。
    :type prompt: str
    :param cfg: 翻訳設定オブジェクト。
    :type cfg: types.SimpleNamespace
    :returns: 翻訳されたPresentationオブジェクトと翻訳データのリスト。
    :rtype: tuple[pptx.Presentation, list]
    """
    cfg.translate_master = False

    data = []
    print()
    print(">>> Translating PPTX (shapes, groups, tables, notes, charts)...")

    def translate_paragraph(paragraph):
        nonlocal data
        if cfg.process_unit == "paragraph":
            text = paragraph.text
            if to_translate(text, cfg.min_translate_length, cfg.limit_to_multibyte_str):
                original_text = text
                try:
                    revised_text = translate(text, api, prompt, cfg)
                except Exception as e:
                    print(f"  *** Translation failed for this paragraph. Skipping. Error: {e}")
                    return # 失敗時は元のテキストを保持
                    
                print(f"[Original] {original_text}")
                print(f"  -> [Revised] {revised_text}")
                if check_translation(original_text, revised_text, cfg.allowed_translation_length_ratio):
                    paragraph.text = revised_text
                    data.append({"original": original_text, "translated": revised_text})
                else:
                    print("  *** This translation is rejected")
        else:
            for run in paragraph.runs:
                if to_translate(run.text, cfg.min_translate_length, cfg.limit_to_multibyte_str):
                    original_text = run.text
                    try:
                        revised_text = translate(run.text, api, prompt, cfg)
                    except Exception as e:
                        print(f"  *** Translation failed for this run. Skipping. Error: {e}")
                        continue # 失敗時は元のテキストを保持
                        
                    print(f"[Original] {original_text}")
                    print(f"  -> [Revised] {revised_text}")
                    if check_translation(original_text, revised_text, cfg.allowed_translation_length_ratio):
                        run.text = revised_text
                        data.append({"original": original_text, "translated": revised_text})
                    else:
                        print("  *** This translation is rejected")

    def translate_shape(shape):
        if shape.has_text_frame:
            for paragraph in shape.text_frame.paragraphs:
                translate_paragraph(paragraph)

        if shape.has_table:
            for row in shape.table.rows:
                for cell in row.cells:
                    for paragraph in cell.text_frame.paragraphs:
                        translate_paragraph(paragraph)

        if shape.shape_type == MSO_SHAPE_TYPE.GROUP:
            for shp in shape.shapes:
                translate_shape(shp)

        if hasattr(shape, "has_chart") and shape.has_chart:
            chart = shape.chart

            if chart.has_title and chart.chart_title.has_text_frame:
                for paragraph in chart.chart_title.text_frame.paragraphs:
                    translate_paragraph(paragraph)

            if hasattr(chart, "category_axis"):
                ax = chart.category_axis
                if getattr(ax, "has_title", False) and ax.axis_title.has_text_frame:
                    for paragraph in ax.axis_title.text_frame.paragraphs:
                        translate_paragraph(paragraph)

            if hasattr(chart, "value_axis"):
                ax = chart.value_axis
                if getattr(ax, "has_title", False) and ax.axis_title.has_text_frame:
                    for paragraph in ax.axis_title.text_frame.paragraphs:
                        translate_paragraph(paragraph)

            for series in chart.series:
                for pt in getattr(series, "points", []):
                    lbl = getattr(pt, "data_label", None)
                    if lbl is not None and getattr(lbl, "has_text_frame", False):
                        for paragraph in lbl.text_frame.paragraphs:
                            translate_paragraph(paragraph)

    for slide_idx, slide in enumerate(ppt.slides, start=1):
        print(f"\n--- Slide {slide_idx} ---")
        for shape in slide.shapes:
            translate_shape(shape)

        if slide.has_notes_slide:
            notes_slide = slide.notes_slide
            ntf = getattr(notes_slide, "notes_text_frame", None)
            if ntf is not None:
                print("  Translating notes...")
                for paragraph in ntf.paragraphs:
                    translate_paragraph(paragraph)

    # マスタースライド翻訳フラグ（無指定時は従来通り True 扱い）
    if getattr(cfg, "translate_master", True):
        print("\n>>> Translating slide masters and layouts (static text)...")
        for master in ppt.slide_masters:
            for shape in master.shapes:
                translate_shape(shape)
            for layout in master.slide_layouts:
                for shape in layout.shapes:
                    translate_shape(shape)
    else:
        print("\n>>> Skipping translation of slide masters and layouts (static text).")

    return ppt, data


def translate_docx(doc: Document, api: str, api_model: str, prompt: str, cfg: SimpleNamespace) -> tuple[Document, list]:
    """
    Word文書 (.docx) の内容を翻訳します。

    文書内の段落とテーブルのセルを走査し、`process_unit`設定に基づいて
    段落単位またはラン（文字の連続）単位でテキストを翻訳します。

    :param doc: 翻訳対象のDocumentオブジェクト。
    :type doc: docx.Document
    :param api: 使用するAPIの種類。
    :type api: str
    :param api_model: 使用するAPIモデル。
    :type api_model: str
    :param prompt: 翻訳に使用するプロンプト。
    :type prompt: str
    :param cfg: 翻訳設定オブジェクト。
    :type cfg: types.SimpleNamespace
    :returns: 翻訳されたDocumentオブジェクトと翻訳データのリスト。
    :rtype: tuple[docx.Document, list]
    """
    data = []
    print()
    print(">>> Processing paragraphs/runs...")

    if cfg.process_unit == "paragraph":
        for paragraph in doc.paragraphs:
            if to_translate(paragraph.text, cfg.min_translate_length, cfg.limit_to_multibyte_str):
                original_text = paragraph.text
                try:
                    revised_text = translate(paragraph.text, api, prompt, cfg)
                except Exception as e:
                    print(f"  *** Translation failed for this paragraph. Skipping. Error: {e}")
                    continue
                    
                print(f"[Original] {original_text}")
                print(f"  -> [Revised] {revised_text}")
                if check_translation(original_text, revised_text, cfg.allowed_translation_length_ratio):
                    paragraph.text = revised_text
                    data.append({"original": original_text, "translated": revised_text})
                else:
                    print("  *** This translation is rejected")
    else:
        for paragraph in doc.paragraphs:
            for run in paragraph.runs:
                if to_translate(run.text, cfg.min_translate_length, cfg.limit_to_multibyte_str):
                    original_text = run.text
                    try:
                        revised_text = translate(run.text, api, prompt, cfg)
                    except Exception as e:
                        print(f"  *** Translation failed for this run. Skipping. Error: {e}")
                        continue
                        
                    print(f"[Original] {original_text}")
                    print(f"  -> [Revised] {revised_text}")
                    if check_translation(original_text, revised_text, cfg.allowed_translation_length_ratio):
                        run.text = revised_text
                        data.append({"original": original_text, "translated": revised_text})
                    else:
                        print("  *** This translation is rejected")

    print(">>> Processing tables...")
    for table in doc.tables:
        for row in table.rows:
            for cell in row.cells:
                for paragraph in cell.paragraphs:
                    if cfg.process_unit == "paragraph":
                        if to_translate(paragraph.text, cfg.min_translate_length, cfg.limit_to_multibyte_str):
                            original_text = paragraph.text
                            try:
                                revised_text = translate(paragraph.text, api, prompt, cfg)
                            except Exception as e:
                                print(f"  *** Translation failed for this table cell (paragraph). Skipping. Error: {e}")
                                continue
                                
                            print(f"[Original] {original_text}")
                            print(f"  -> [Revised] {revised_text}")
                            if check_translation(original_text, revised_text, cfg.allowed_translation_length_ratio):
                                paragraph.text = revised_text
                                data.append({"original": original_text, "translated": revised_text})
                            else:
                                print("  *** This translation is rejected")
                    else:
                        for run in paragraph.runs:
                            if to_translate(run.text, cfg.min_translate_length, cfg.limit_to_multibyte_str):
                                original_text = run.text
                                try:
                                    revised_text = translate(run.text, api, prompt, cfg)
                                except Exception as e:
                                    print(f"  *** Translation failed for this table cell (run). Skipping. Error: {e}")
                                    continue
                                    
                                print(f"[Original] {original_text}")
                                print(f"  -> [Revised] {revised_text}")
                                if check_translation(original_text, revised_text, cfg.allowed_translation_length_ratio):
                                    run.text = revised_text
                                    data.append({"original": original_text, "translated": revised_text})
                                else:
                                    print("  *** This translation is rejected")
    return doc, data


def translate_text(text: str, api: str, api_model: str, prompt: str, cfg: SimpleNamespace) -> tuple[str, list]:
    """
    プレーンテキストブロック全体を翻訳します。

    入力されたテキストが翻訳条件を満たす場合、`translate`関数を使用して
    テキスト全体を翻訳します。

    :param text: 翻訳対象のプレーンテキスト。
    :type text: str
    :param api: 使用するAPIの種類。
    :type api: str
    :param api_model: 使用するAPIモデル。
    :type api_model: str
    :param prompt: 翻訳に使用するプロンプト。
    :type prompt: str
    :param cfg: 翻訳設定オブジェクト。
    :type cfg: types.SimpleNamespace
    :returns: 翻訳されたテキストと翻訳データのリスト。
    :rtype: tuple[str, list]
    """
    data = []
    print(">>> Translating plain text...")
    revised_text = text
    if to_translate(text, cfg.min_translate_length, cfg.limit_to_multibyte_str):
        original_text = text
        try:
            revised_text = translate(text, api, prompt, cfg)
        except Exception as e:
            print(f"  *** Translation failed for the entire text block. Skipping. Error: {e}")
            revised_text = original_text # 失敗時は元のテキストを保持
            
        print(f"[Original] {original_text}")
        print(f"  -> [Revised] {revised_text}")
        data.append({"original": original_text, "translated": revised_text})
    return revised_text, data


# ------------------------------------------------------
# メイン実行
# ------------------------------------------------------
def execute(cfg: SimpleNamespace):
    """
    メインの翻訳処理を実行します。

    入力ファイルのタイプに応じて適切な翻訳ロジックを選択し、ファイルを読み込み、
    LLMまたはDeepLで翻訳し、結果を保存します。翻訳中にエラーが発生した場合でも、
    部分的にでも結果を保存しようと試みます。
    最終的に、翻訳前後のテキストを比較するHTMLレポートも生成します。

    :param cfg: 全てのプログラム設定を含むSimpleNamespaceオブジェクト。
    :type cfg: types.SimpleNamespace
    :returns: なし
    :rtype: None
    """
    filetype = get_filetype(cfg.infile)

    if filetype is None:
        print(f"\nError in execute(): Invalid extension in [{cfg.infile}]\n")
        sys.exit(1)

    # ------------------ ファイルパス設定 ------------------
    # NOTE: GUI側のロジックと重複するが、ここではCUI実行時のパスを決定する
    if filetype == "md":
        outfile = replace_path(cfg.infile, "_revised.md")
    elif filetype == "rst":
        outfile = replace_path(cfg.infile, "_revised.rst")
    elif cfg.use_md:
        mdfile = replace_path(cfg.infile, ".md")
        outfile = replace_path(cfg.infile, "_revised.md")
    elif filetype == "pdf":
        outfile = replace_path(cfg.infile, "_revised.md" if cfg.use_md else "_revised.docx")
    elif filetype == "docx":
        outfile = replace_path(cfg.infile, "_revised.docx")
    elif filetype == "html":
        outfile = replace_path(cfg.infile, "_revised.html")
    elif filetype == "pptx":
        outfile = replace_path(cfg.infile, "_revised.pptx")
    elif filetype == "txt":
        outfile = replace_path(cfg.infile, "_revised.txt")
    else:
        print(f"\nError in execute(): Unsupported extension in [{cfg.infile}]\n")
        sys.exit(1)

    output_comparison_html_path = replace_path(cfg.infile, "_compare.html")
    output_reformat_md = replace_path(cfg.infile, "_reformat.md")
    output_docx = replace_path(cfg.infile, ".docx")

    print("=== Translate and revise file ===")
    print(f"  Input file              : {cfg.infile}")
    # ... (設定情報の出力は省略) ...
    print(f"  Output file             : {outfile}")

    if not os.path.isfile(cfg.infile):
        print(f"Error: File [{cfg.infile}] does not exist")
        usage()
        sys.exit(1)

    data = []
    translated_document = None # 翻訳済みドキュメントオブジェクト/テキストを保持する変数
    
    # ------------------ 翻訳処理本体 (Tryブロックで囲む) ------------------
    try:
        # ---- md/txt ----
        if filetype in ("md", "rst", "txt"):
            print(f"Read [{cfg.infile}]")
            text = read_file(cfg.infile)
            if filetype == "md":
                text, data = translate_markdown_document(text, cfg.translate_prompt, cfg)
            elif filetype == "rst":
                text, data = translate_rst_document(text, cfg.translate_prompt, cfg)
            else:
                text, data = translate_text(text, cfg.api, cfg.openai_model, cfg.translate_prompt, cfg)
            translated_document = text
            if text is None:
                print(f"Error for filetype = {filetype}: Could not get text")

        # ---- use_md モード ----
        elif cfg.use_md:
            print(f"Read [{cfg.infile}] and convert to markdown")
            text = convert_to_md(cfg.infile)
            if text is None:
                print("Error for md: Could not get text")
                
            print(f"=== Saving markdown to {mdfile} ===")
            save(mdfile, text)

            if filetype == "pdf":
                print(f"Reformatting [{mdfile}] by API...")
                # reformat → translate
                text2 = translate(text, cfg.api, cfg.reformat_prompt, cfg)
                if not text2:
                    print("Error: Could not get reformatted text")
                else:
                    print(f"Reformatted MD file is saved to [{output_reformat_md}]")
                    save(output_reformat_md, text2)
                    text = text2

            text, data = translate_markdown_document(text, cfg.translate_prompt, cfg)
            translated_document = text
            if text is None:
                print("Error in getting translated text: Could not get text")
                
        # ---- 通常モード (docx, pptx, html, pdf -> docx) ----
        else:
            if filetype == "pdf":
                print(f"Converting [{cfg.infile}] to [{output_docx}]")
                pdf_to_docx(cfg.infile, output_docx)
                print(f"Read [{output_docx}]")
                doc = Document(output_docx)
                translated_document, data = translate_docx(doc, cfg.api, cfg.openai_model, cfg.translate_prompt, cfg)

            elif filetype == "pptx":
                ppt = Presentation(cfg.infile)
                translated_document, data = translate_pptx(ppt, cfg.api, cfg.openai_model, cfg.translate_prompt, cfg)

            elif filetype == "docx":
                print(f"Read [{cfg.infile}]")
                doc = Document(cfg.infile)
                translated_document, data = translate_docx(doc, cfg.api, cfg.openai_model, cfg.translate_prompt, cfg)

            elif filetype == "html":
                print(f"Read [{cfg.infile}]")
                html = read_file(cfg.infile)
                translated_document, data = translate_html(html, cfg.api, cfg.openai_model, cfg.translate_prompt, cfg)

    except Exception as e:
        # 翻訳中にエラーが発生した場合、メッセージを出力して保存処理へ進む
        print(f"\n[ERROR] Translation process interrupted by an exception: {e}")
        # スタックトレースはGUI側で表示されるため、ここでは簡易的なメッセージに留める
        # ここで処理を終了せずに、以下の保存処理に進むのが重要

    # ------------------ 翻訳結果の保存 (エラーに関わらず実行) ------------------
    print()
    if translated_document is not None:
        try:
            if filetype in ("md", "rst", "txt") or cfg.use_md:
                # md, txt, または use_mdモードの場合
                print(f"=== Saving revised text to {outfile} ===")
                save(outfile, translated_document)
            elif filetype == "html" and not cfg.use_md:
                # html の場合
                print(f"=== Saving revised html to {outfile} ===")
                save(outfile, translated_document)
            elif filetype in ("docx", "pdf", "pptx") and not cfg.use_md:
                # docx, pdf (docx), pptx のドキュメントオブジェクトの場合
                save_doc_type = "docx" if filetype in ("docx", "pdf") else "pptx"
                print(f"=== Saving revised {save_doc_type} to {outfile} ===")
                translated_document.save(outfile)
        except Exception as save_e:
            print(f"[ERROR] Failed to save the partially translated file to {outfile}: {save_e}")
            
    # ------------------------------------------------------
    # 比較HTML生成
    # ------------------------------------------------------
    print()
    print(f"Creating comparison HTML file from template [{cfg.html_template_path}]")

    if not data and translated_document is None:
        print("--- [WARNING] No translation data or document object available. Skipping HTML report.")
        return # 保存対象がないためここで終了

    context = cfg.__dict__.copy()
    context["data"] = data

    current_dir = os.getcwd()
    script_dir = os.path.dirname(os.path.abspath(__file__))
    
    # テンプレートファイルの探索ロジック（そのまま維持）
    if not os.path.isfile(cfg.html_template_path):
        template_filename = os.path.basename(cfg.html_template_path)
        cand = os.path.join(current_dir, template_filename)
        if os.path.isfile(cand):
            cfg.html_template_path = cand
    if not os.path.isfile(cfg.html_template_path):
        template_filename = os.path.basename(cfg.html_template_path)
        cand = os.path.join(script_dir, template_filename)
        if os.path.isfile(cand):
            cfg.html_template_path = cand

    print(f"  Template path: [{cfg.html_template_path}]")

    if os.path.isfile(cfg.html_template_path):
        try:
            template_dir = os.path.dirname(cfg.html_template_path)
            template_file = os.path.basename(cfg.html_template_path)

            env = Environment(loader=FileSystemLoader(template_dir))
            template = env.get_template(template_file)

            rendered_html = template.render(context)

            print()
            print(f"Save translation data to [{output_comparison_html_path}]")
            with open(output_comparison_html_path, "w", encoding="utf-8") as f:
                f.write(rendered_html)
            print(f"  Finished.\n")
        except Exception as html_e:
            print(f"[ERROR] Failed to generate comparison HTML report: {html_e}")
    else:
        print()
        print(f"--- [WARNING] Template file '{cfg.html_template_path}' not found.")
        print(f"---           Looked in current and script directories.")
        print("---           Skipping generation of comparison HTML report.")
    print()


def main():
    """
    プログラムのエントリポイント。

    `initialize()`で設定とCLIパーサーを準備し、`update_variables()`でCLI引数を解析して
    設定を更新し、`execute()`で実際の翻訳処理を開始します。

    :returns: なし
    :rtype: None
    """
    global parser
    cfg, parser = initialize()
    cfg = update_variables(cfg, parser)
    execute(cfg)


if __name__ == "__main__":
    main()
    print()
    usage()
    input("\nPress ENTER to terminate>>\n")