"""HTMLページを取得し、そのテキストノードをDeepLまたはLLMで翻訳します。
このスクリプトは、指定されたURLからHTMLコンテンツをフェッチし、その中のテキストノードを
設定された翻訳API(DeepL、OpenAI、Gemini、LM Studio)を使用して翻訳します。
翻訳結果は新しいHTMLファイルとして保存されます。
.. seealso::
:doc:`translate_url_usage` (利用ガイドラインや詳細な使用例はこちら)
"""
import argparse
import os
import re
from pathlib import Path
from types import SimpleNamespace
from urllib.parse import urlparse
import chardet
import requests
from bs4 import BeautifulSoup
from tkai_lib_litellm import read_ai_config
from translate_core import check_translation, configure_translation_cfg, to_translate, translate
from translate_backends import translate_html_document
DEFAULT_PROMPT = """You are a precise professional translator.
Translate the following text without adding commentary. Preserve its meaning,
HTML-adjacent punctuation, symbols, proper nouns, and short heading style.
# Text to translate
{{text}}"""
def build_parser():
"""コマンドライン引数を解析するためのArgumentParserを設定します。
:returns: 設定されたArgumentParserオブジェクト。
:rtype: argparse.ArgumentParser
"""
parser = argparse.ArgumentParser(description="Translate HTML fetched from a URL.")
parser.add_argument("url", help="URL of the HTML page to translate")
parser.add_argument("--source-lang", default="JA", help="Source language for DeepL (default: JA)")
parser.add_argument("--target-lang", default="EN", help="Target language for DeepL (default: EN)")
parser.add_argument("--api", choices=["deepl", "openai", "gemini", "lmstudio"], default="deepl")
parser.add_argument("--model", help="Model for OpenAI, Gemini, or LM Studio")
parser.add_argument("--endpoint", default=os.getenv("endpoint"), help="DeepL endpoint")
parser.add_argument("--output", "-o", help="Output HTML path")
parser.add_argument("--config", default="translate.env", help="Tool-specific .env file")
parser.add_argument("--common-config", default="ai.env", help="Shared .env/account configuration")
parser.add_argument("--encoding", default=os.getenv("force_server_charcode", ""), help="Force server character encoding")
parser.add_argument("--timeout", type=float, default=60.0, help="HTTP timeout in seconds")
parser.add_argument("--max-tokens", type=int, default=int(os.getenv("max_tokens", "2000")))
parser.add_argument("--temperature", type=float, default=float(os.getenv("temperature", "0.3")))
parser.add_argument("--reasoning-effort", default=os.getenv("reasoning_effort", "low"))
parser.add_argument("--min-translate-length", type=int, default=int(os.getenv("min_translate_length", "5")))
parser.add_argument("--allowed-translation-length-ratio", type=float, default=float(os.getenv("allowed_translation_length_ratio", "5.0")))
parser.add_argument("--limit-to-multibyte-str", action="store_true", help="Translate only text containing multibyte characters")
parser.add_argument("--all-text", action="store_true", help="Translate eligible English text as well")
parser.add_argument("--prompt", default=DEFAULT_PROMPT, help="Full LLM translation prompt")
parser.add_argument("--sleep", type=float, default=0.0, help="Delay after each API call (seconds)")
parser.add_argument("--overwrite", action="store_true", help="Allow overwriting the output file")
parser.add_argument("--quiet", action="store_true", help="Do not print every translated text node")
return parser
def resolve_config(args):
"""コマンドライン引数と環境変数から翻訳設定を解決・構成します。
.envファイルから設定を読み込み、選択されたAPIに応じたデフォルトモデルを設定し、
最終的な翻訳設定オブジェクトを構築します。
:param args: コマンドライン引数。
:type args: argparse.Namespace
:returns: 構成された翻訳設定オブジェクト。
:rtype: types.SimpleNamespace
"""
read_ai_config(args.config, read_account_inf=False)
read_ai_config(args.common_config)
default_models = {
"openai": os.getenv("openai_model", "gpt-4o"),
"gemini": os.getenv("google_model", "gemini-2.5-flash"),
"lmstudio": os.getenv("lmstudio_model", "qwen/qwen3.8-27b"),
}
cfg = SimpleNamespace(
api=args.api,
model=args.model or default_models.get(args.api),
endpoint=args.endpoint or os.getenv("endpoint"),
deepl_api_key=os.getenv("DEEPL_API_KEY"),
source_lang=args.source_lang.upper(),
target_lang=args.target_lang.upper(),
temperature=args.temperature,
max_tokens=args.max_tokens,
reasoning_effort=args.reasoning_effort,
tsleep_rpm=args.sleep,
timeout=args.timeout,
min_translate_length=args.min_translate_length,
allowed_translation_length_ratio=args.allowed_translation_length_ratio,
limit_to_multibyte_str=args.limit_to_multibyte_str or not args.all_text,
)
return configure_translation_cfg(
cfg,
api=cfg.api,
model=cfg.model,
source_lang=cfg.source_lang,
target_lang=cfg.target_lang,
endpoint=cfg.endpoint,
deepl_api_key=cfg.deepl_api_key,
temperature=cfg.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,
)
def output_path(url, requested):
"""翻訳済みHTMLの出力パスを決定します。
指定された出力パスがある場合はそれを直接使用し、ない場合は元のURLから
ファイル名を生成します。生成されるファイル名には"_en"サフィックスを追加します。
:param url: 元のHTMLページのURL。
:type url: str
:param requested: ユーザーが指定した出力パス。指定がない場合はNone。
:type requested: str or None
:returns: 翻訳済みHTMLの出力パス。
:rtype: pathlib.Path
"""
if requested:
return Path(requested)
name = Path(urlparse(url).path).name or "index.html"
stem, suffix = os.path.splitext(name)
suffix = suffix or ".html"
stem = re.sub(r"_jp$", "_en", stem, flags=re.IGNORECASE) if re.search(r"_jp$", stem, re.IGNORECASE) else stem + "_en"
return Path(stem + suffix)
def fetch_html(url, encoding, timeout):
"""指定されたURLからHTMLコンテンツを取得します。
HTTP GETリクエストを実行し、リダイレクトを処理します。
また、文字エンコーディングを自動検出するか、指定されたエンコーディングを強制的に適用します。
:param url: 取得するURL。
:type url: str
:param encoding: 強制的に適用する文字エンコーディング。空の場合は自動検出。
:type encoding: str
:param timeout: HTTPリクエストのタイムアウト時間(秒)。
:type timeout: float
:returns: 取得したHTMLテキストと最終的なURLのタプル。
:rtype: tuple[str, str]
:raises requests.exceptions.RequestException: HTTPリクエストが失敗した場合。
"""
response = requests.get(url, allow_redirects=True, timeout=timeout)
response.raise_for_status()
detected = chardet.detect(response.content).get("encoding")
response.encoding = encoding or response.encoding or detected or "utf-8"
print(f"Fetched: {response.url}")
print(f"Encoding: {response.encoding} (detected: {detected or 'unknown'})")
return response.text, response.url
def translate_html(html, prompt, cfg, quiet=False):
"""取得したHTMLコンテンツのテキストノードを翻訳します。
`translate_html_document` 関数を使用して、HTMLドキュメント内の翻訳対象テキストノードを走査し、
設定されたAPI(DeepLまたはLLM)で翻訳を実行します。
:param html: 翻訳対象のHTML文字列。
:type html: str
:param prompt: LLM翻訳に使用するプロンプトテンプレート。DeepLの場合は無視されます。
:type prompt: str
:param cfg: 翻訳設定オブジェクト。
:type cfg: types.SimpleNamespace
:param quiet: 翻訳されたテキストノードを標準出力に表示しない場合はTrue。
:type quiet: bool
:returns: 翻訳済みHTML文字列と翻訳データ(詳細は`translate_html_document`による)のタプル。
:rtype: tuple[str, Any]
"""
return translate_html_document(html, prompt, cfg)
def main():
"""スクリプトのエントリポイント関数。
コマンドライン引数を解析し、翻訳設定を解決します。
その後、指定されたURLからHTMLを取得し、その内容を翻訳し、結果をファイルに保存します。
必要なAPIキーやモデルが設定されていない場合はエラーで終了します。
"""
args = build_parser().parse_args()
cfg = resolve_config(args)
if cfg.api == "deepl" and not cfg.deepl_api_key:
raise SystemExit("ERROR: DEEPL_API_KEY is not configured.")
if cfg.api == "deepl" and not cfg.endpoint:
raise SystemExit("ERROR: DeepL endpoint is not configured.")
if cfg.api != "deepl" and not cfg.model:
raise SystemExit(f"ERROR: a model is required for api={cfg.api}.")
html, final_url = fetch_html(args.url, args.encoding, args.timeout)
destination = output_path(final_url, args.output)
if destination.exists() and not args.overwrite:
raise SystemExit(f"ERROR: output exists: {destination} (use --overwrite)")
print(f"Translate [{final_url}] {cfg.source_lang} -> {cfg.target_lang} via {cfg.api}")
translated, data = translate_html(html, args.prompt, cfg, args.quiet)
destination.write_text(translated, encoding="utf-8")
print(f"Saved {destination} ({len(data)} text nodes translated)")
if __name__ == "__main__":
main()