translate_core プログラム仕様
Small, dependency-light core shared by file and URL translation tools.
このモジュールは、ファイルやURLの翻訳ツールが共有する、軽量で依存関係の少ないコア機能を提供します。 主に、APIの正規化、言語ペアの決定、翻訳設定の構成、テキストの変換前処理、 そしてLiteLLMまたはDeepLを使用した実際の翻訳処理が含まれます。
- translate_core.check_multibyte_str(text, limit_to_multibyte_str)
文字列に多バイト文字が含まれているかを確認します。
limit_to_multibyte_str がTrueの場合のみ、テキストに多バイト文字(U+0800からU+FFFFの範囲)が 含まれているかをチェックします。Falseの場合は常にTrueを返します。
- パラメータ:
text -- str: チェックするテキスト。
limit_to_multibyte_str -- bool: 多バイト文字の有無でチェックを制限するかどうか。
- 戻り値:
bool: テキストが多バイト文字を含んでいる(またはチェックが制限されていない)場合はTrue、それ以外はFalse。
- translate_core.check_translation(original, translated, allowed_translation_length_ratio=5.0)
翻訳結果の妥当性を基本的な基準に基づいてチェックします。
翻訳されたテキストが空でないこと、マークダウンのブロックとして始まっていないこと、 先行するハッシュ記号やアスタリスクの数が不適切でないこと、 そして元のテキストに対する長さの比率が許容範囲内であることを確認します。
- パラメータ:
original -- str: 翻訳元のテキスト。
translated -- str: 翻訳されたテキスト。
allowed_translation_length_ratio -- float: 翻訳結果の許容される最大長と元のテキスト長の比率。デフォルトは5.0。
- 戻り値:
bool: 翻訳結果が妥当と見なされる場合はTrue、それ以外はFalse。
- translate_core.configure_translation_cfg(cfg, *, api, model=None, mode=None, source_lang=None, target_lang=None, endpoint=None, deepl_api_key=None, temperature=None, max_tokens=None, reasoning_effort=None, min_translate_length=None, allowed_translation_length_ratio=None, limit_to_multibyte_str=None, tsleep_rpm=None)
translate 関数が消費するプロバイダーに依存しない設定を構成します。
フロントエンドは独自のウィジェットやレガシーモデルフィールドを保持できますが、 値が収集された後にこの関数を一度呼び出す必要があります。 したがって、実際の翻訳パスは
cfg.apiとcfg.modelにのみ依存します。 この関数は、提供された引数に基づいて設定オブジェクトの属性を設定します。- パラメータ:
cfg -- object: 設定を格納するオブジェクト。既存の属性も考慮されます。
api -- str: 使用する翻訳APIの名前(例: 'openai', 'deepl')。
model -- str | None: 使用するAIモデルの名前。DeepLの場合は不要です。
mode -- str | None: 翻訳モード(例: 'je')。指定された場合、source_langとtarget_langを上書きします。
source_lang -- str | None: ソース言語のISOコード(例: 'JA', 'EN')。
target_lang -- str | None: ターゲット言語のISOコード(例: 'JA', 'EN')。
endpoint -- str | None: DeepL APIのエンドポイントURL。
deepl_api_key -- str | None: DeepL APIの認証キー。
temperature -- float | None: AIモデルの応答のランダム性を制御する温度設定。
max_tokens -- int | None: AIモデルの応答で生成される最大トークン数。
reasoning_effort -- float | None: LM Studioなどのモデルにおける推論の労力。
min_translate_length -- int | None: 翻訳を試みる最小テキスト長。
allowed_translation_length_ratio -- float | None: 翻訳結果の許容される最大長と元のテキスト長の比率。
limit_to_multibyte_str -- bool | None: 翻訳を多バイト文字を含む文字列に限定するかどうか。
tsleep_rpm -- float | None: APIリクエスト間の遅延時間(RPMに基づく)。
- 戻り値:
object: 設定が更新された
cfgオブジェクト。
- translate_core.language_pair_from_mode(mode)
確立された2文字のモード(je/ej/jj/ee)を言語コードに変換します。
翻訳モード(例: 'je'は日本語から英語へ)を、ソース言語とターゲット言語の2文字のISOコード ('JA'または'EN')のタプルに変換します。
- パラメータ:
mode -- str: 翻訳モードを示す2文字の文字列 (j=日本語, e=英語)。
- 戻り値:
tuple[str, str]: ソース言語とターゲット言語のISOコード(例: ('JA', 'EN'))。
- 例外:
ValueError -- 無効な翻訳モードが指定された場合。
- translate_core.n_leading_chars(text, char='#')
文字列の先頭にある特定の文字の数を数えます。
- パラメータ:
text -- str: チェックする文字列。
char -- str: 先頭から数える文字。デフォルトは'#'。
- 戻り値:
int: 先頭にある指定された文字の数。
- translate_core.normalize_api(api)
翻訳ツールが使用する正規のプロバイダー名を返します。
与えられたAPI名を、システムが認識する標準的なAPI名に変換します。 エイリアスが定義されている場合はそれを使用し、最終的にサポートされているAPI名であることを確認します。
- パラメータ:
api -- str: 正規化するAPI名。
- 戻り値:
str: 正規化されたAPI名。
- 例外:
ValueError -- サポートされていない翻訳APIが指定された場合。
- translate_core.process_template(template, context)
エスケープされた制御文字と
{{ name }}プレースホルダーを展開します。テンプレート文字列内のエスケープシーケンス(t, n, r)を実際の制御文字に変換し、
{{ key }}の形式で記述されたプレースホルダーを context 辞書の値で置換します。 キーが context に存在しない場合は、プレースホルダーはそのまま残されます。- パラメータ:
template -- str: 処理するテンプレート文字列。
context -- dict[str, Any]: プレースホルダーを置換するためのキーと値の辞書。
- 戻り値:
str: 展開されたテンプレート文字列。
- translate_core.to_translate(text, min_translate_length=1, limit_to_multibyte_str=False)
指定されたテキストが翻訳対象であるかどうかを判断します。
テキストがNoneでないこと、最小長を超えること、 そして多バイト文字の制限がある場合はそれに適合すること、 または英字が含まれることを確認します。
- パラメータ:
text -- str | None: 翻訳対象として確認するテキスト。
min_translate_length -- int: 翻訳を試みる最小テキスト長。デフォルトは1。
limit_to_multibyte_str -- bool: 翻訳を多バイト文字を含む文字列に限定するかどうか。デフォルトはFalse。
- 戻り値:
bool: テキストが翻訳対象と見なされる場合はTrue、それ以外はFalse。
- translate_core.translate(text, prompt, cfg)
LiteLLMまたはDeepLを介して1つのテキストブロックを翻訳/校正します。
設定オブジェクト cfg の api に基づいて、DeepL APIまたはLiteLLM互換のAIモデルを使用して テキストを翻訳します。翻訳後、設定されたRPM (Requests Per Minute) に基づいて 遅延を発生させることができます。
- パラメータ:
text -- str: 翻訳するテキストブロック。
prompt -- str: AIモデルに送信するプロンプトのテンプレート。{{ text }} などのプレースホルダーを含めます。
cfg -- object: 翻訳設定を含むオブジェクト。 (api, model, temperature, max_tokens, reasoning_effort, tsleep_rpm, deepl_api_key, endpoint, source_lang, target_lang)
- 戻り値:
str: 翻訳または校正されたテキスト。
- 例外:
RuntimeError -- DeepL APIキーまたはエンドポイントが設定されていない場合(DeepL使用時)、またはAI APIがテキストを返さない場合。