translate_core.py ダウンロード/コピー
translate_core.py
translate_core.py
1"""Small, dependency-light core shared by file and URL translation tools.
2
3このモジュールは、ファイルやURLの翻訳ツールが共有する、軽量で依存関係の少ないコア機能を提供します。
4主に、APIの正規化、言語ペアの決定、翻訳設定の構成、テキストの変換前処理、
5そしてLiteLLMまたはDeepLを使用した実際の翻訳処理が含まれます。
6
7関連リンク:
8 :doc:`translate_core_usage`
9"""
10
11import re
12import time
13
14import requests
15
16from tkai_lib_litellm import extract_text, query_ai, query_ai_compatible
17
18API_ALIASES = {"openai5": "openai", "google": "gemini"}
19CANONICAL_APIS = ("openai", "gemini", "lmstudio", "deepl")
20
21
22def normalize_api(api):
23 """翻訳ツールが使用する正規のプロバイダー名を返します。
24
25 与えられたAPI名を、システムが認識する標準的なAPI名に変換します。
26 エイリアスが定義されている場合はそれを使用し、最終的にサポートされているAPI名であることを確認します。
27
28 :param api: str: 正規化するAPI名。
29 :returns: str: 正規化されたAPI名。
30 :raises ValueError: サポートされていない翻訳APIが指定された場合。
31 """
32 normalized = API_ALIASES.get((api or "").strip().lower(), (api or "").strip().lower())
33 if normalized not in CANONICAL_APIS:
34 raise ValueError(f"Unsupported translation API: {api}")
35 return normalized
36
37
38def language_pair_from_mode(mode):
39 """確立された2文字のモード(je/ej/jj/ee)を言語コードに変換します。
40
41 翻訳モード(例: 'je'は日本語から英語へ)を、ソース言語とターゲット言語の2文字のISOコード
42 ('JA'または'EN')のタプルに変換します。
43
44 :param mode: str: 翻訳モードを示す2文字の文字列 (j=日本語, e=英語)。
45 :returns: tuple[str, str]: ソース言語とターゲット言語のISOコード(例: ('JA', 'EN'))。
46 :raises ValueError: 無効な翻訳モードが指定された場合。
47 """
48 mode = (mode or "je").lower()
49 if len(mode) < 2 or mode[0] not in "je" or mode[1] not in "je":
50 raise ValueError(f"Invalid translation mode: {mode}")
51 return ("JA" if mode[0] == "j" else "EN", "JA" if mode[1] == "j" else "EN")
52
53
54def configure_translation_cfg(
55 cfg,
56 *,
57 api,
58 model=None,
59 mode=None,
60 source_lang=None,
61 target_lang=None,
62 endpoint=None,
63 deepl_api_key=None,
64 temperature=None,
65 max_tokens=None,
66 reasoning_effort=None,
67 min_translate_length=None,
68 allowed_translation_length_ratio=None,
69 limit_to_multibyte_str=None,
70 tsleep_rpm=None,
71):
72 """`translate` 関数が消費するプロバイダーに依存しない設定を構成します。
73
74 フロントエンドは独自のウィジェットやレガシーモデルフィールドを保持できますが、
75 値が収集された後にこの関数を一度呼び出す必要があります。
76 したがって、実際の翻訳パスは ``cfg.api`` と ``cfg.model`` にのみ依存します。
77 この関数は、提供された引数に基づいて設定オブジェクトの属性を設定します。
78
79 :param cfg: object: 設定を格納するオブジェクト。既存の属性も考慮されます。
80 :param api: str: 使用する翻訳APIの名前(例: 'openai', 'deepl')。
81 :param model: str | None: 使用するAIモデルの名前。DeepLの場合は不要です。
82 :param mode: str | None: 翻訳モード(例: 'je')。指定された場合、source_langとtarget_langを上書きします。
83 :param source_lang: str | None: ソース言語のISOコード(例: 'JA', 'EN')。
84 :param target_lang: str | None: ターゲット言語のISOコード(例: 'JA', 'EN')。
85 :param endpoint: str | None: DeepL APIのエンドポイントURL。
86 :param deepl_api_key: str | None: DeepL APIの認証キー。
87 :param temperature: float | None: AIモデルの応答のランダム性を制御する温度設定。
88 :param max_tokens: int | None: AIモデルの応答で生成される最大トークン数。
89 :param reasoning_effort: float | None: LM Studioなどのモデルにおける推論の労力。
90 :param min_translate_length: int | None: 翻訳を試みる最小テキスト長。
91 :param allowed_translation_length_ratio: float | None: 翻訳結果の許容される最大長と元のテキスト長の比率。
92 :param limit_to_multibyte_str: bool | None: 翻訳を多バイト文字を含む文字列に限定するかどうか。
93 :param tsleep_rpm: float | None: APIリクエスト間の遅延時間(RPMに基づく)。
94 :returns: object: 設定が更新された ``cfg`` オブジェクト。
95 """
96 cfg.api = normalize_api(api)
97 cfg.model = model or None
98 if mode is not None:
99 source_lang, target_lang = language_pair_from_mode(mode)
100 cfg.mode = mode
101 cfg.source_lang = (source_lang or getattr(cfg, "source_lang", "JA")).upper()
102 cfg.target_lang = (target_lang or getattr(cfg, "target_lang", "EN")).upper()
103 cfg.endpoint = endpoint if cfg.api == "deepl" else None
104 if deepl_api_key is not None:
105 cfg.deepl_api_key = deepl_api_key
106 for name, value in {
107 "temperature": temperature,
108 "max_tokens": max_tokens,
109 "reasoning_effort": reasoning_effort,
110 "min_translate_length": min_translate_length,
111 "allowed_translation_length_ratio": allowed_translation_length_ratio,
112 "tsleep_rpm": tsleep_rpm,
113 }.items():
114 if value is not None:
115 setattr(cfg, name, value)
116 if limit_to_multibyte_str is None:
117 limit_to_multibyte_str = cfg.source_lang == "JA"
118 cfg.limit_to_multibyte_str = bool(limit_to_multibyte_str)
119 return cfg
120
121
122def process_template(template, context):
123 """エスケープされた制御文字と ``{{ name }}`` プレースホルダーを展開します。
124
125 テンプレート文字列内のエスケープシーケンス(\\t, \\n, \\r)を実際の制御文字に変換し、
126 ``{{ key }}`` の形式で記述されたプレースホルダーを `context` 辞書の値で置換します。
127 キーが `context` に存在しない場合は、プレースホルダーはそのまま残されます。
128
129 :param template: str: 処理するテンプレート文字列。
130 :param context: dict[str, Any]: プレースホルダーを置換するためのキーと値の辞書。
131 :returns: str: 展開されたテンプレート文字列。
132 """
133 template = template.replace(r"\t", "\t").replace(r"\n", "\n").replace(r"\r", "\r")
134 return re.sub(
135 r"\{\{\s*(.*?)\s*\}\}",
136 lambda match: str(context.get(match.group(1).strip(), match.group(0))),
137 template,
138 )
139
140
141def check_multibyte_str(text, limit_to_multibyte_str):
142 """文字列に多バイト文字が含まれているかを確認します。
143
144 `limit_to_multibyte_str` がTrueの場合のみ、テキストに多バイト文字(U+0800からU+FFFFの範囲)が
145 含まれているかをチェックします。Falseの場合は常にTrueを返します。
146
147 :param text: str: チェックするテキスト。
148 :param limit_to_multibyte_str: bool: 多バイト文字の有無でチェックを制限するかどうか。
149 :returns: bool: テキストが多バイト文字を含んでいる(またはチェックが制限されていない)場合はTrue、それ以外はFalse。
150 """
151 return not limit_to_multibyte_str or bool(re.search(r"[\u0800-\uFFFF]", text))
152
153
154def to_translate(text, min_translate_length=1, limit_to_multibyte_str=False):
155 """指定されたテキストが翻訳対象であるかどうかを判断します。
156
157 テキストがNoneでないこと、最小長を超えること、
158 そして多バイト文字の制限がある場合はそれに適合すること、
159 または英字が含まれることを確認します。
160
161 :param text: str | None: 翻訳対象として確認するテキスト。
162 :param min_translate_length: int: 翻訳を試みる最小テキスト長。デフォルトは1。
163 :param limit_to_multibyte_str: bool: 翻訳を多バイト文字を含む文字列に限定するかどうか。デフォルトはFalse。
164 :returns: bool: テキストが翻訳対象と見なされる場合はTrue、それ以外はFalse。
165 """
166 if text is None:
167 return False
168 text = str(text).strip()
169 if len(text) < min_translate_length:
170 return False
171 has_multibyte = check_multibyte_str(text, limit_to_multibyte_str)
172 if not has_multibyte and not re.search(r"[a-zA-Z]", text):
173 return False
174 return has_multibyte if limit_to_multibyte_str else True
175
176
177def n_leading_chars(text, char="#"):
178 """文字列の先頭にある特定の文字の数を数えます。
179
180 :param text: str: チェックする文字列。
181 :param char: str: 先頭から数える文字。デフォルトは'#'。
182 :returns: int: 先頭にある指定された文字の数。
183 """
184 return len(text) - len(text.lstrip(char))
185
186
187def check_translation(original, translated, allowed_translation_length_ratio=5.0):
188 """翻訳結果の妥当性を基本的な基準に基づいてチェックします。
189
190 翻訳されたテキストが空でないこと、マークダウンのブロックとして始まっていないこと、
191 先行するハッシュ記号やアスタリスクの数が不適切でないこと、
192 そして元のテキストに対する長さの比率が許容範囲内であることを確認します。
193
194 :param original: str: 翻訳元のテキスト。
195 :param translated: str: 翻訳されたテキスト。
196 :param allowed_translation_length_ratio: float: 翻訳結果の許容される最大長と元のテキスト長の比率。デフォルトは5.0。
197 :returns: bool: 翻訳結果が妥当と見なされる場合はTrue、それ以外はFalse。
198 """
199 if not translated or translated.startswith(("'''", "```")):
200 return False
201 before = n_leading_chars(original, "#")
202 after = n_leading_chars(translated, "#")
203 if after > before:
204 return False
205 before = n_leading_chars(original, "*")
206 after = n_leading_chars(translated, "*")
207 if after == before + 1:
208 return False
209 return not original or len(translated) <= len(original) * allowed_translation_length_ratio
210
211
212def _translate_with_deepl(text, cfg):
213 """DeepL APIを使用してテキストを翻訳します。
214
215 DeepL APIキーとエンドポイントが設定されていることを確認し、
216 指定されたテキストをDeepLに送信して翻訳結果を取得します。
217
218 :param text: str: 翻訳するテキスト。
219 :param cfg: object: 翻訳設定を含むオブジェクト(deepl_api_key, endpoint, source_lang, target_lang, timeout)。
220 :returns: str: DeepLによって翻訳されたテキスト。
221 :raises RuntimeError: DEEPL_API_KEYまたはDeepLエンドポイントが設定されていない場合。
222 :raises requests.exceptions.RequestException: DeepL APIからのHTTPエラーが発生した場合。
223 """
224 if not getattr(cfg, "deepl_api_key", None):
225 raise RuntimeError("DEEPL_API_KEY is not set")
226 if not getattr(cfg, "endpoint", None):
227 raise RuntimeError("DeepL endpoint is not set")
228 response = requests.post(
229 cfg.endpoint,
230 headers={"Authorization": f"DeepL-Auth-Key {cfg.deepl_api_key}"},
231 data={"text": text, "source_lang": cfg.source_lang, "target_lang": cfg.target_lang},
232 timeout=getattr(cfg, "timeout", 60),
233 )
234 response.raise_for_status()
235 return response.json()["translations"][0]["text"]
236
237
238def translate(text, prompt, cfg):
239 """LiteLLMまたはDeepLを介して1つのテキストブロックを翻訳/校正します。
240
241 設定オブジェクト `cfg` の `api` に基づいて、DeepL APIまたはLiteLLM互換のAIモデルを使用して
242 テキストを翻訳します。翻訳後、設定されたRPM (Requests Per Minute) に基づいて
243 遅延を発生させることができます。
244
245 :param text: str: 翻訳するテキストブロック。
246 :param prompt: str: AIモデルに送信するプロンプトのテンプレート。`{{ text }}` などのプレースホルダーを含めます。
247 :param cfg: object: 翻訳設定を含むオブジェクト。
248 (api, model, temperature, max_tokens, reasoning_effort, tsleep_rpm, deepl_api_key, endpoint, source_lang, target_lang)
249 :returns: str: 翻訳または校正されたテキスト。
250 :raises RuntimeError: DeepL APIキーまたはエンドポイントが設定されていない場合(DeepL使用時)、またはAI APIがテキストを返さない場合。
251 """
252 if cfg.api == "deepl":
253 result = _translate_with_deepl(text, cfg)
254 else:
255 prompt_text = process_template(
256 prompt,
257 {"text": text, "additional_prompt": "翻訳・校正結果のみを出力してください。前置きや後付けのメッセージは不要です。"},
258 )
259 if cfg.api == "lmstudio":
260 kwargs = {"temperature": cfg.temperature, "max_tokens": cfg.max_tokens}
261 if getattr(cfg, "reasoning_effort", None):
262 kwargs["extra_body"] = {"reasoning_effort": cfg.reasoning_effort}
263 response = query_ai(prompt_text, cfg.model, role="", provider="lmstudio", **kwargs)
264 else:
265 response = query_ai_compatible(
266 prompt_text, cfg.model, role="", provider=cfg.api,
267 temperature=cfg.temperature, max_tokens=cfg.max_tokens,
268 reasoning_effort=getattr(cfg, "reasoning_effort", None),
269 )
270 result = extract_text(response)
271 if not result:
272 raise RuntimeError("Translation API returned no text")
273
274 delay = getattr(cfg, "tsleep_rpm", 0.0)
275 if delay > 0:
276 time.sleep(delay)
277 return result.strip()