Pythonプログラム translate_core.py の技術ドキュメント

このドキュメントは、Pythonで記述された translate_core.py プログラムの技術的な側面を詳細に解説します。


プログラムの動作

translate_core.py は、ファイルやURLの翻訳ツールで共有される、軽量で依存性の少ないコアモジュールです。その主な目的は、様々な翻訳API(DeepL、OpenAI、Gemini、LM Studioなど)を抽象化し、一貫したインターフェースを通じてテキスト翻訳機能を提供することです。

主な機能は以下の通りです。

  • API名の正規化と検証: サポートされている翻訳API名を一貫した形式に変換し、不正なAPI名を検出します。

  • 言語ペアの変換: 翻訳モード(例: je for Japanese-English)を標準的な言語コードペア(例: JA, EN)に変換します。

  • 翻訳設定の構成: 翻訳に必要な各種設定(API、モデル、言語、APIキー、温度、最大トークン数など)を統一的に管理する設定オブジェクトを構成します。

  • プロンプトテンプレート処理: AIモデルへのプロンプトに含まれるプレースホルダーやエスケープシーケンスを展開します。

  • 翻訳要件のチェック: テキストが翻訳に適しているか(最小長、マルチバイト文字の存在など)を判断します。

  • 翻訳結果の検証: 翻訳されたテキストが、元のテキストに対して不適切な形式(不適切なヘッダ、過度な長さ)ではないかを確認します。

  • テキストの翻訳: DeepLまたはLiteLLM互換のAIモデルを通じて、指定されたテキストを翻訳または校正します。APIコール間のレートリミットに対応するための遅延機能も含まれます。

このプログラムは、様々な翻訳サービスを統合し、フロントエンド開発者が異なるAPIの実装詳細に煩わされることなく、翻訳機能を容易に組み込めるようにすることで、開発の複雑さを軽減します。

原理

translate_core.py は、複数の翻訳サービスを抽象化し、統一された設定と翻訳ロジックを提供することで動作します。

  1. API正規化とサポートチェック (normalize_api): 設定されたAPI名が内部のエイリアス (API_ALIASES) に基づいて正規化されます。その後、正規化されたAPI名が CANONICAL_APIS (例: openai, gemini, lmstudio, deepl) のいずれかに含まれるかを確認し、サポートされていないAPIの場合は ValueError を発生させます。これにより、翻訳処理の初期段階で適切なAPIが選択されることを保証します。

  2. 言語ペア変換 (language_pair_from_mode): je (Japanese-English), ej (English-Japanese) などの短いモード文字列から、ソース言語とターゲット言語の標準的な2文字コード (JA, EN) のペアを生成します。これは、国際化された翻訳システムの言語指定を簡素化します。

  3. 翻訳設定の構成 (configure_translation_cfg): この関数は、翻訳の実行に必要な全てのパラメータ(APIの種類、使用モデル、ソース/ターゲット言語、APIエンドポイント、APIキー、AIモデルのパラメータ(温度、最大トークン数、推論の労力)など)を単一の設定オブジェクト (cfg) に集約します。これにより、翻訳ロジックと設定が分離され、柔軟な構成が可能になります。

  4. プロンプトテンプレート処理 (process_template): AIモデルに送信するプロンプト文字列内で、\t や \n のようなエスケープシーケンスを展開し、{{ name }} 形式のプレースホルダーを context 辞書の値で置換します。これにより、動的に内容が変化するプロンプトを容易に生成できます。

  5. 翻訳対象テキストの判定 (to_translate, check_multibyte_str): to_translate 関数は、与えられたテキストが実際に翻訳されるべきかどうかの基準を評価します。具体的には、テキストが min_translate_length 以上の長さを持つか、また limit_to_multibyte_str が True の場合にマルチバイト文字(日本語など)を含むかをチェックします。check_multibyte_str は、Unicodeの範囲 $U0800-UFFFF$ を検索することでマルチバイト文字の存在を検出します。

  6. 翻訳結果の品質チェック (check_translation): 翻訳されたテキストが不適切でないかを検証します。

    • 翻訳されたテキストが空でないか、または「3重引用符」やバッククォート3つ(Markdownのコードブロック開始記号)で始まっていないかをチェックします。

    • 元のテキストと翻訳されたテキストの先頭にあるハッシュ記号 (#) やアスタリスク (*) の数を比較し、翻訳によって不自然にヘッダレベルが増加していないかを検証します。

    • 翻訳されたテキストの長さが、元のテキストの長さに対して allowed_translation_length_ratio で指定された倍率を超えていないかをチェックします。これにより、翻訳が過度に膨張することを防ぎます。

  7. 翻訳の実行 (translate, _translate_with_deepl):

    • DeepL API: cfg.api が deepl の場合、_translate_with_deepl 関数が実行されます。この関数は、requests ライブラリを使用してDeepL APIエンドポイントにHTTP POSTリクエストを送信します。リクエストボディには、翻訳対象テキスト、ソース言語、ターゲット言語、および認証用の DeepL-Auth-Key が含まれます。APIキーとエンドポイントが cfg オブジェクトに設定されている必要があります。

    • LiteLLM互換API (OpenAI, Gemini, LM Studio): cfg.api が deepl 以外の場合、tkai_lib_litellm モジュールから提供される query_ai または query_ai_compatible 関数が使用されます。これらの関数は、プロンプトテンプレートによって生成されたプロンプトテキストを、指定されたAIモデルに送信し、翻訳結果を取得します。temperature、max_tokens、reasoning_effort などのAIモデル固有のパラメータも渡されます。

  8. レートリミット対応: translate 関数は、cfg.tsleep_rpm が0より大きい場合、API呼び出しの間に指定された時間 (delay) だけ time.sleep() を実行します。これにより、APIプロバイダのレートリミット超過を防ぎます。

これらの原理により、translate_core.py は多様な翻訳ニーズに対応できる堅牢で柔軟な翻訳基盤を提供します。

必要な非標準ライブラリとインストール方法

translate_core.py の実行には、以下の非標準ライブラリが必要です。

  1. requests: HTTPリクエストを行うためのライブラリです。DeepL APIとの通信に使用されます。

    pip install requests
    
  2. tkai_lib_litellm: このモジュールは、LiteLLM互換のAIモデルへのクエリを行うためのラッパーまたはヘルパーライブラリとして機能します。これはPyPIで直接提供されているパッケージではなく、通常はプロジェクト内で提供されるカスタムモジュールです。

    このモジュール自体は pip install ではインストールされませんが、tkai_lib_litellm が内部的に依存している以下のいずれかのAIクライアントライブラリのインストールが必要になる場合があります。

    • LiteLLM: OpenAI、Gemini、LM Studioなど、複数のLLMプロバイダを統一されたAPIで利用するためのライブラリです。tkai_lib_litellm がこれを利用している可能性が高いです。

      pip install litellm
      
    • OpenAI SDK: OpenAI APIを直接利用する場合。

      pip install openai
      
    • Google Generative AI SDK: Gemini APIを直接利用する場合。

      pip install google-generativeai
      

注意: tkai_lib_litellm モジュールは、translate_core.py と同じディレクトリに配置するか、Pythonのモジュール検索パスからアクセスできるようにする必要があります。上記リストのAIクライアントライブラリは、tkai_lib_litellm の具体的な実装によって必要なものが異なります。

必要な入力ファイル

translate_core.py は、それ自体が直接入力ファイルを受け取るスクリプトではありません。これは他のプログラムからインポートされて使用されるライブラリモジュールです。

その関数は、以下のようなデータをプログラム引数として受け取ります。

  • 翻訳対象テキスト (string): translate 関数に渡される、実際に翻訳または校正される文字列。

  • プロンプトテンプレート (string): AIモデルに送信されるプロンプトのテンプレート文字列。プレースホルダー {{ text }} や {{ additional_prompt }} を含むことができます。

  • 設定オブジェクト (object): configure_translation_cfg 関数によって構成されるオブジェクト。このオブジェクトには、以下の情報が含まれることが期待されます。

    • api (string): 使用する翻訳API(例: "openai", "deepl")。

    • model (string, AIモデルの場合): 使用するAIモデルの識別子(例: "gpt-3.5-turbo", "gemini-pro")。

    • source_lang, target_lang (string): ソース言語およびターゲット言語の2文字コード(例: "JA", "EN")。

    • deepl_api_key (string, DeepLの場合): DeepL APIの認証キー。

    • endpoint (string, DeepLの場合): DeepL APIのエンドポイントURL。

    • temperature (float, AIモデルの場合): AIモデルの出力のランダム性を制御する温度設定。

    • max_tokens (int, AIモデルの場合): AIモデルが生成する最大トークン数。

    • reasoning_effort (int, LM Studioの場合): 推論の労力レベル。

    • min_translate_length (int): 翻訳対象テキストの最小長。

    • allowed_translation_length_ratio (float): 翻訳結果の長さが元のテキストの何倍まで許容されるか。

    • tsleep_rpm (float): API呼び出し間の待機時間(秒)。

これらの設定値は、通常、translate_core.py を利用する上位のスクリプトによって、設定ファイル、環境変数、またはコマンドライン引数から提供されます。

生成される出力ファイル

translate_core.py は、いかなる出力ファイルも生成しません。

このモジュールの translate 関数は、入力されたテキストを翻訳または校正した結果を文字列として返します。出力された文字列は、呼び出し元のプログラムによって、コンソールに表示されたり、ファイルに保存されたり、他の処理に利用されたりします。

コマンドラインでの使用例 (Usage)

translate_core.py はライブラリモジュールであり、直接コマンドラインから実行されることを想定していません。代わりに、他のPythonスクリプトからインポートされ、その関数が呼び出されることで利用されます。

以下に、translate_core.py を利用する架空のスクリプト my_translation_app.py の使用例を示します。

# my_translation_app.py
import argparse
from types import SimpleNamespace
from translate_core import configure_translation_cfg, translate

def main():
    parser = argparse.ArgumentParser(description="テキスト翻訳ツール")
    parser.add_argument("text", help="翻訳するテキスト")
    parser.add_argument("--api", default="openai", help="使用する翻訳API (例: openai, deepl)")
    parser.add_argument("--model", default="gpt-3.5-turbo", help="使用するAIモデル (APIがAIモデルの場合)")
    parser.add_argument("--mode", default="je", help="翻訳モード (je:日→英, ej:英→日など)")
    parser.add_argument("--deepl-api-key", help="DeepL APIキー")
    parser.add_argument("--deepl-endpoint", default="https://api-free.deepl.com/v2/translate", help="DeepL APIエンドポイント")
    parser.add_argument("--temperature", type=float, default=0.7, help="AIモデルの温度")
    args = parser.parse_args()

    # 設定オブジェクトを初期化
    cfg = SimpleNamespace()
    
    # translate_core.py の関数を使って設定を構成
    configure_translation_cfg(
        cfg,
        api=args.api,
        model=args.model,
        mode=args.mode,
        deepl_api_key=args.deepl_api_key,
        endpoint=args.deepl_endpoint,
        temperature=args.temperature,
    )

    # AIモデルへのプロンプト例
    prompt_template = "以下のテキストを{{ target_lang }}に翻訳・校正してください。\n\nテキスト: {{ text }}\n\n{{ additional_prompt }}"

    try:
        translated_text = translate(args.text, prompt_template, cfg)
        print("元のテキスト:", args.text)
        print("翻訳結果:", translated_text)
    except Exception as e:
        print(f"翻訳中にエラーが発生しました: {e}")

if __name__ == "__main__":
    main()

上記の my_translation_app.py をコマンドラインから実行する場合の基本的な構文は以下のようになります。

python my_translation_app.py [翻訳するテキスト] [オプション...]
  • [翻訳するテキスト]: 翻訳したい文字列を直接指定します。

  • [オプション...]: my_translation_app.py が提供する引数(--api, --model, --mode など)を指定します。

コマンドラインでの具体的な使用例

上記で示した架空のスクリプト my_translation_app.py を使用して、translate_core.py が提供する翻訳機能を具体的に利用する例を示します。

例1: OpenAI APIを使用した日本語から英語への翻訳

日本語のテキストをOpenAI API (gpt-3.5-turbo) を使って英語に翻訳します。

python my_translation_app.py "こんにちは、世界!" --api openai --model gpt-3.5-turbo --mode je

実行結果の例:

元のテキスト: こんにちは、世界!
翻訳結果: Hello, world!

例2: DeepL APIを使用した英語から日本語への翻訳

英語のテキストをDeepL APIを使って日本語に翻訳します。DEEPL_API_KEY 環境変数を設定するか、--deepl-api-key 引数でキーを直接渡す必要があります。

python my_translation_app.py "This is a pen." --api deepl --mode ej --deepl-api-key YOUR_DEEPL_API_KEY

実行結果の例:

元のテキスト: This is a pen.
翻訳結果: これはペンです。

例3: LM Studioを使用した英語から日本語への翻訳(温度指定あり)

ローカルのLM Studioで動作するAIモデル(例: local-model)を使って英語を日本語に翻訳します。温度を調整することで、出力の創造性や正確性を制御できます。

python my_translation_app.py "The quick brown fox jumps over the lazy dog." --api lmstudio --model local-model --mode ej --temperature 0.2

実行結果の例:

元のテキスト: The quick brown fox jumps over the lazy dog.
翻訳結果: 素早い茶色のキツネが怠惰な犬を飛び越えます。

これらの例は、translate_core.py が異なる翻訳APIや設定に対して一貫した方法で翻訳機能を提供することを示しています。