translate_url.py ダウンロード/コピー

translate_url.py をダウンロード

translate_url.py
translate_url.py
  1"""HTMLページを取得し、そのテキストノードをDeepLまたはLLMで翻訳します。
  2
  3このスクリプトは、指定されたURLからHTMLコンテンツをフェッチし、その中のテキストノードを
  4設定された翻訳API(DeepL、OpenAI、Gemini、LM Studio)を使用して翻訳します。
  5翻訳結果は新しいHTMLファイルとして保存されます。
  6
  7.. seealso::
  8   :doc:`translate_url_usage` (利用ガイドラインや詳細な使用例はこちら)
  9"""
 10
 11import argparse
 12import os
 13import re
 14from pathlib import Path
 15from types import SimpleNamespace
 16from urllib.parse import urlparse
 17
 18import chardet
 19import requests
 20from bs4 import BeautifulSoup
 21
 22from tkai_lib_litellm import read_ai_config
 23from translate_core import check_translation, configure_translation_cfg, to_translate, translate
 24from translate_backends import translate_html_document
 25
 26
 27DEFAULT_PROMPT = """You are a precise professional translator.
 28Translate the following text without adding commentary. Preserve its meaning,
 29HTML-adjacent punctuation, symbols, proper nouns, and short heading style.
 30
 31# Text to translate
 32{{text}}"""
 33
 34
 35def build_parser():
 36    """コマンドライン引数を解析するためのArgumentParserを設定します。
 37
 38    :returns: 設定されたArgumentParserオブジェクト。
 39    :rtype: argparse.ArgumentParser
 40    """
 41    parser = argparse.ArgumentParser(description="Translate HTML fetched from a URL.")
 42    parser.add_argument("url", help="URL of the HTML page to translate")
 43    parser.add_argument("--source-lang", default="JA", help="Source language for DeepL (default: JA)")
 44    parser.add_argument("--target-lang", default="EN", help="Target language for DeepL (default: EN)")
 45    parser.add_argument("--api", choices=["deepl", "openai", "gemini", "lmstudio"], default="deepl")
 46    parser.add_argument("--model", help="Model for OpenAI, Gemini, or LM Studio")
 47    parser.add_argument("--endpoint", default=os.getenv("endpoint"), help="DeepL endpoint")
 48    parser.add_argument("--output", "-o", help="Output HTML path")
 49    parser.add_argument("--config", default="translate.env", help="Tool-specific .env file")
 50    parser.add_argument("--common-config", default="ai.env", help="Shared .env/account configuration")
 51    parser.add_argument("--encoding", default=os.getenv("force_server_charcode", ""), help="Force server character encoding")
 52    parser.add_argument("--timeout", type=float, default=60.0, help="HTTP timeout in seconds")
 53    parser.add_argument("--max-tokens", type=int, default=int(os.getenv("max_tokens", "2000")))
 54    parser.add_argument("--temperature", type=float, default=float(os.getenv("temperature", "0.3")))
 55    parser.add_argument("--reasoning-effort", default=os.getenv("reasoning_effort", "low"))
 56    parser.add_argument("--min-translate-length", type=int, default=int(os.getenv("min_translate_length", "5")))
 57    parser.add_argument("--allowed-translation-length-ratio", type=float, default=float(os.getenv("allowed_translation_length_ratio", "5.0")))
 58    parser.add_argument("--limit-to-multibyte-str", action="store_true", help="Translate only text containing multibyte characters")
 59    parser.add_argument("--all-text", action="store_true", help="Translate eligible English text as well")
 60    parser.add_argument("--prompt", default=DEFAULT_PROMPT, help="Full LLM translation prompt")
 61    parser.add_argument("--sleep", type=float, default=0.0, help="Delay after each API call (seconds)")
 62    parser.add_argument("--overwrite", action="store_true", help="Allow overwriting the output file")
 63    parser.add_argument("--quiet", action="store_true", help="Do not print every translated text node")
 64    return parser
 65
 66
 67def resolve_config(args):
 68    """コマンドライン引数と環境変数から翻訳設定を解決・構成します。
 69
 70    .envファイルから設定を読み込み、選択されたAPIに応じたデフォルトモデルを設定し、
 71    最終的な翻訳設定オブジェクトを構築します。
 72
 73    :param args: コマンドライン引数。
 74    :type args: argparse.Namespace
 75    :returns: 構成された翻訳設定オブジェクト。
 76    :rtype: types.SimpleNamespace
 77    """
 78    read_ai_config(args.config, read_account_inf=False)
 79    read_ai_config(args.common_config)
 80    default_models = {
 81        "openai": os.getenv("openai_model", "gpt-4o"),
 82        "gemini": os.getenv("google_model", "gemini-2.5-flash"),
 83        "lmstudio": os.getenv("lmstudio_model", "qwen/qwen3.8-27b"),
 84    }
 85    cfg = SimpleNamespace(
 86        api=args.api,
 87        model=args.model or default_models.get(args.api),
 88        endpoint=args.endpoint or os.getenv("endpoint"),
 89        deepl_api_key=os.getenv("DEEPL_API_KEY"),
 90        source_lang=args.source_lang.upper(),
 91        target_lang=args.target_lang.upper(),
 92        temperature=args.temperature,
 93        max_tokens=args.max_tokens,
 94        reasoning_effort=args.reasoning_effort,
 95        tsleep_rpm=args.sleep,
 96        timeout=args.timeout,
 97        min_translate_length=args.min_translate_length,
 98        allowed_translation_length_ratio=args.allowed_translation_length_ratio,
 99        limit_to_multibyte_str=args.limit_to_multibyte_str or not args.all_text,
100    )
101    return configure_translation_cfg(
102        cfg,
103        api=cfg.api,
104        model=cfg.model,
105        source_lang=cfg.source_lang,
106        target_lang=cfg.target_lang,
107        endpoint=cfg.endpoint,
108        deepl_api_key=cfg.deepl_api_key,
109        temperature=cfg.temperature,
110        max_tokens=cfg.max_tokens,
111        reasoning_effort=cfg.reasoning_effort,
112        min_translate_length=cfg.min_translate_length,
113        allowed_translation_length_ratio=cfg.allowed_translation_length_ratio,
114        limit_to_multibyte_str=cfg.limit_to_multibyte_str,
115        tsleep_rpm=cfg.tsleep_rpm,
116    )
117
118
119def output_path(url, requested):
120    """翻訳済みHTMLの出力パスを決定します。
121
122    指定された出力パスがある場合はそれを直接使用し、ない場合は元のURLから
123    ファイル名を生成します。生成されるファイル名には"_en"サフィックスを追加します。
124
125    :param url: 元のHTMLページのURL。
126    :type url: str
127    :param requested: ユーザーが指定した出力パス。指定がない場合はNone。
128    :type requested: str or None
129    :returns: 翻訳済みHTMLの出力パス。
130    :rtype: pathlib.Path
131    """
132    if requested:
133        return Path(requested)
134    name = Path(urlparse(url).path).name or "index.html"
135    stem, suffix = os.path.splitext(name)
136    suffix = suffix or ".html"
137    stem = re.sub(r"_jp$", "_en", stem, flags=re.IGNORECASE) if re.search(r"_jp$", stem, re.IGNORECASE) else stem + "_en"
138    return Path(stem + suffix)
139
140
141def fetch_html(url, encoding, timeout):
142    """指定されたURLからHTMLコンテンツを取得します。
143
144    HTTP GETリクエストを実行し、リダイレクトを処理します。
145    また、文字エンコーディングを自動検出するか、指定されたエンコーディングを強制的に適用します。
146
147    :param url: 取得するURL。
148    :type url: str
149    :param encoding: 強制的に適用する文字エンコーディング。空の場合は自動検出。
150    :type encoding: str
151    :param timeout: HTTPリクエストのタイムアウト時間(秒)。
152    :type timeout: float
153    :returns: 取得したHTMLテキストと最終的なURLのタプル。
154    :rtype: tuple[str, str]
155    :raises requests.exceptions.RequestException: HTTPリクエストが失敗した場合。
156    """
157    response = requests.get(url, allow_redirects=True, timeout=timeout)
158    response.raise_for_status()
159    detected = chardet.detect(response.content).get("encoding")
160    response.encoding = encoding or response.encoding or detected or "utf-8"
161    print(f"Fetched: {response.url}")
162    print(f"Encoding: {response.encoding} (detected: {detected or 'unknown'})")
163    return response.text, response.url
164
165
166def translate_html(html, prompt, cfg, quiet=False):
167    """取得したHTMLコンテンツのテキストノードを翻訳します。
168
169    `translate_html_document` 関数を使用して、HTMLドキュメント内の翻訳対象テキストノードを走査し、
170    設定されたAPI(DeepLまたはLLM)で翻訳を実行します。
171
172    :param html: 翻訳対象のHTML文字列。
173    :type html: str
174    :param prompt: LLM翻訳に使用するプロンプトテンプレート。DeepLの場合は無視されます。
175    :type prompt: str
176    :param cfg: 翻訳設定オブジェクト。
177    :type cfg: types.SimpleNamespace
178    :param quiet: 翻訳されたテキストノードを標準出力に表示しない場合はTrue。
179    :type quiet: bool
180    :returns: 翻訳済みHTML文字列と翻訳データ(詳細は`translate_html_document`による)のタプル。
181    :rtype: tuple[str, Any]
182    """
183    return translate_html_document(html, prompt, cfg)
184
185
186def main():
187    """スクリプトのエントリポイント関数。
188
189    コマンドライン引数を解析し、翻訳設定を解決します。
190    その後、指定されたURLからHTMLを取得し、その内容を翻訳し、結果をファイルに保存します。
191    必要なAPIキーやモデルが設定されていない場合はエラーで終了します。
192    """
193    args = build_parser().parse_args()
194    cfg = resolve_config(args)
195    if cfg.api == "deepl" and not cfg.deepl_api_key:
196        raise SystemExit("ERROR: DEEPL_API_KEY is not configured.")
197    if cfg.api == "deepl" and not cfg.endpoint:
198        raise SystemExit("ERROR: DeepL endpoint is not configured.")
199    if cfg.api != "deepl" and not cfg.model:
200        raise SystemExit(f"ERROR: a model is required for api={cfg.api}.")
201
202    html, final_url = fetch_html(args.url, args.encoding, args.timeout)
203    destination = output_path(final_url, args.output)
204    if destination.exists() and not args.overwrite:
205        raise SystemExit(f"ERROR: output exists: {destination} (use --overwrite)")
206    print(f"Translate [{final_url}] {cfg.source_lang} -> {cfg.target_lang} via {cfg.api}")
207    translated, data = translate_html(html, args.prompt, cfg, args.quiet)
208    destination.write_text(translated, encoding="utf-8")
209    print(f"Saved {destination} ({len(data)} text nodes translated)")
210
211
212if __name__ == "__main__":
213    main()