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()