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

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