translate_url.py Documentation

プログラムの動作

translate_url.py は、指定されたURLからHTMLページを取得し、そのテキストコンテンツを翻訳するPythonプログラムです。主に、ウェブページの多言語化を自動化し、手動での翻訳作業を削減することを目的としています。

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

  • HTMLの取得: 指定されたURLからHTTP GETリクエストを使用してHTMLコンテンツをフェッチします。リダイレクトにも対応し、タイムアウト設定も可能です。

  • 文字コードの検出と強制: 取得したHTMLの文字コードを自動で検出します。また、必要に応じて特定の文字コードを強制的に適用できます。

  • HTMLの解析: BeautifulSoup ライブラリを使用してHTMLドキュメントを解析し、翻訳対象となるテキストノードを特定します。

  • 翻訳APIの選択: 以下の複数の翻訳バックエンドをサポートします。

    • DeepL

    • OpenAI (GPTシリーズなど)

    • Google Gemini

    • LM Studio (ローカルLLMなど)

  • 言語設定: 翻訳元言語 (source-lang) と翻訳先言語 (target-lang) を柔軟に設定できます。

  • LLMパラメータの調整: LLMを利用する場合、モデル名、温度 (temperature)、最大トークン数 (max-tokens)、推論の努力レベル (reasoning-effort)、カスタムプロンプトなどを設定できます。

  • 翻訳のフィルタリング: 最小翻訳長 (min-translate-length) や多バイト文字のみを対象とするオプション (limit-to-multibyte-str) を用いて、翻訳対象となるテキストノードを絞り込むことができます。

  • 出力ファイルの生成: 翻訳されたHTMLコンテンツを新しいファイルとして保存します。出力ファイル名は、元のURLから自動生成されるか、ユーザーが指定できます。

  • 設定ファイルの利用: .env ファイル (translate.env, ai.env) を介してAPIキーやデフォルト設定を管理し、柔軟かつセキュアな運用を可能にします。

このプログラムは、特にウェブコンテンツの国際化や多言語対応が必要なシナリオにおいて、効率的な翻訳ワークフローを提供します。

原理

translate_url.py は、以下の主要な技術とアルゴリズムに基づいて動作します。

  1. HTMLの取得と文字コード処理:

    • requests ライブラリを使用して指定されたURLにHTTP GETリクエストを送信し、HTMLコンテンツを取得します。

    • chardet ライブラリを用いて取得したバイト列から最適な文字コードを自動的に検出します。これにより、多様なウェブサイトのエンコーディングに対応します。

    • ユーザーが --encoding オプションで文字コードを強制することも可能です。検出された文字コードまたは指定された文字コードでレスポンスのテキストをデコードします。

  2. HTMLの解析とテキストノードの抽出:

    • BeautifulSoup を使用して、取得したHTMLテキストをDOMツリーとして解析します。

    • HTMLドキュメントツリーを走査し、翻訳の対象となるプレーンテキストノード(例: <p>これは文章です。</p> の「これは文章です。」の部分)を特定します。不要なスクリプト、スタイル、コメントなどは翻訳対象から除外されます。

  3. 翻訳バックエンドの選択と実行:

    • ユーザーが --api オプションで DeepL、OpenAI、Gemini、LM Studio のいずれかを選択します。

    • DeepL: DeepL APIキーとエンドポイントを使用して、テキストノードをDeepLの翻訳サービスに送信します。

    • LLMs (OpenAI, Gemini, LM Studio): tkai_lib_litellm モジュールを介して litellm などの共通インターフェースを利用し、選択されたLLMに翻訳リクエストを送信します。

      • 翻訳対象のテキストは、--prompt オプションで指定されたプロンプトテンプレート (DEFAULT_PROMPT がデフォルト) に挿入され、LLMに渡されます。

      • DEFAULT_PROMPT は、LLMに対し「正確なプロの翻訳者」として振る舞い、コメントを追加せず、HTMLに近い句読点、記号、固有名詞、短い見出しスタイルを保持するよう指示します。

      • LLMは、temperature (生成されるテキストのランダム性)、max_tokens (生成される最大のトークン数)、reasoning_effort (推論の努力レベル) などのパラメータによって動作を調整されます。

    • 翻訳対象のテキストは、min_translate_length で指定された最小長未満の場合や、limit_to_multibyte_str が設定されている場合に多バイト文字を含まない場合はスキップされることがあります。

  4. 設定管理:

    • read_ai_config 関数を通じて、translate.env および ai.env ファイルから環境変数やAPIキーなどの設定を読み込みます。これにより、機密情報をコードにハードコーディングすることなく、柔軟な設定変更を可能にします。

  5. 出力ファイルの生成:

    • 翻訳されたテキストノードは、元のHTMLドキュメントの対応する位置に挿入され、完全な翻訳済みHTMLドキュメントが再構築されます。

    • 出力ファイルパスが指定されていない場合、元のURLからファイル名が自動的に生成されます(例: _jp.html を _en.html に変更、または _en.html を追加)。

    • 最終的なHTMLコンテンツはUTF-8エンコーディングでディスクに保存されます。

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

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

  • requests: HTTPリクエストを送信してウェブコンテンツを取得するために使用します。

  • chardet: 取得したHTMLの文字コードを自動的に検出するために使用します。

  • beautifulsoup4 (bs4): HTMLドキュメントを解析し、コンテンツを抽出・操作するために使用します。

  • litellm: 複数のLLMプロバイダ(OpenAI, Geminiなど)に統一されたインターフェースでアクセスするために使用します。tkai_lib_litellm モジュールが内部的にこれを活用しています。

  • python-dotenv: .env ファイルから環境変数を読み込むために使用します。tkai_lib_litellm モジュールが内部的にこれを活用しています。

これらのライブラリは pip コマンドでインストールできます。

pip install requests chardet beautifulsoup4 litellm python-dotenv

補足: プログラムがインポートしている tkai_lib_litellm、translate_core、translate_backends は、このプロジェクト固有のモジュールであり、同じディレクトリまたはPythonのパスが通っている場所に配置されている必要があります。これらは pip でインストールする通常のライブラリではありません。

必要な入力ファイル

translate_url.py が動作するために直接的に必要なファイルは以下の通りです。

  1. 翻訳対象のHTMLページ: これはファイルではなく、プログラム引数としてURLで指定されます。プログラムはこのURLからウェブコンテンツをフェッチします。

  2. 設定ファイル (オプション): プログラムの動作をカスタマイズしたり、APIキーなどの機密情報を管理したりするために、以下の .env ファイルを利用できます。

    • translate.env (デフォルト: --config translate.env)

      • このプログラム固有の設定(例:特定の翻訳パラメータのデフォルト値)を記述できます。

    • ai.env (デフォルト: --common-config ai.env)

      • 複数のAI関連ツールで共有される設定、特にAPIキーやデフォルトモデルの情報を記述します。

    ai.env の記述例:

    DEEPL_API_KEY="your_deepl_api_key_here"
    openai_api_key="sk-your_openai_key_here"
    openai_model="gpt-4o"
    google_api_key="your_google_api_key_here"
    google_model="gemini-1.5-pro"
    

    これらのファイルは、プログラムが実行されるディレクトリに存在するか、フルパスで指定する必要があります。

生成される出力ファイル

translate_url.py は、翻訳処理が完了すると単一のHTMLファイルを生成します。

  • ファイル名:

    • --output または -o オプションで出力ファイルパスが指定された場合、そのパスでファイルが保存されます。

    • --output オプションが指定されなかった場合、プログラムは入力URLに基づいて自動的にファイル名を生成します。

      • 例: 元のURLが https://example.com/dir/page_jp.html の場合、デフォルトの出力ファイル名は page_en.html となります(_jp を _en に置換)。

      • 例: 元のURLが https://example.com/dir/document.html の場合、デフォルトの出力ファイル名は document_en.html となります(_en を付加)。

      • 例: 元のURLが https://example.com/ のようにファイル名がない場合、デフォルトの出力ファイル名は index_en.html となります。

  • 内容:

    • 元のHTMLページの構造(タグ、属性、CSSなど)を保持しつつ、翻訳対象となったテキストノードが指定されたターゲット言語に翻訳された状態で含まれます。

    • <body> タグ内のコンテンツだけでなく、<title> タグなどのメタデータも翻訳の対象となり得ます。

  • エンコーディング:

    • 生成されるHTMLファイルは、常に UTF-8 エンコーディングで保存されます。

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

translate_url.py はコマンドラインから実行され、翻訳対象のURLと様々なオプションを引数として受け取ります。

基本構文:

python translate_url.py <URL> [オプション]

主な引数とオプション:

  • <URL>: 翻訳したいHTMLページのURLを指定します。必須引数です。

  • --source-lang <LANG>: 翻訳元の言語コードを指定します(例: JA, EN)。デフォルトは JA です。

  • --target-lang <LANG>: 翻訳先の言語コードを指定します(例: EN, ZH)。デフォルトは EN です。

  • --api <API>: 使用する翻訳APIを選択します。deepl, openai, gemini, lmstudio のいずれかです。デフォルトは deepl です。

  • --model <MODEL_NAME>: openai, gemini, lmstudio を使用する場合のモデル名を指定します(例: gpt-4o, gemini-1.5-flash)。

  • --endpoint <URL>: DeepL APIのエンドポイントURLを指定します。

  • --output <PATH>, -o <PATH>: 翻訳されたHTMLを保存するファイルパスを指定します。指定しない場合、自動生成されます。

  • --config <PATH>: ツール固有の設定を含む.envファイルのパスを指定します。デフォルトは translate.env です。

  • --common-config <PATH>: 共有のAIアカウント設定を含む.envファイルのパスを指定します。デフォルトは ai.env です。

  • --encoding <CHARSET>: サーバーの文字コードを強制します(例: Shift_JIS)。

  • --timeout <SECONDS>: HTTPリクエストのタイムアウト時間を秒単位で指定します。デフォルトは 60.0 秒です。

  • --max-tokens <INT>: LLMが生成する最大トークン数を指定します。

  • --temperature <FLOAT>: LLMの生成におけるランダム性(創造性)を制御します。0.0から2.0の範囲で、低いほど決定的です。

  • --reasoning-effort <LEVEL>: LLMの推論の努力レベルを指定します(例: low, medium, high)。

  • --min-translate-length <INT>: 翻訳するテキストの最小文字数を指定します。この値より短いテキストは翻訳されません。デフォルトは 5 です。

  • --limit-to-multibyte-str: 多バイト文字を含むテキストのみを翻訳対象とします。英語のテキストが誤って翻訳されるのを防ぐのに役立ちます。

  • --all-text: limit-to-multibyte-str の動作を無効にし、すべての言語の対象テキストを翻訳します。

  • --prompt <PROMPT_TEXT>: LLMに渡すカスタムプロンプトを指定します。{{text}} を使用して、翻訳対象テキストのプレースホルダーを挿入できます。

  • --sleep <SECONDS>: 各APIコール後に指定した秒数だけ遅延を入れます。APIレート制限対策に有用です。

  • --overwrite: 出力ファイルがすでに存在する場合でも上書きを許可します。

  • --quiet: 翻訳される個々のテキストノードの出力を抑制します。

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

例1: 日本語のウェブページをDeepLで英語に翻訳し、デフォルト名で出力する

この例では、DeepL APIを使用して日本語のウェブページを英語に翻訳します。出力ファイルは自動的に命名されます。

python translate_url.py "https://ja.wikipedia.org/wiki/%E3%83%91%E3%82%A4%E3%82%BD%E3%83%B3" --source-lang JA --target-lang EN --api deepl

実行結果の説明: 指定された日本語のWikipediaページがDeepLによって英語に翻訳されます。出力ファイル名は、元のURLのパスから派生して Python_en.html のように生成され、現在のディレクトリに保存されます。このファイルには、元のHTML構造を維持しつつ、テキストコンテンツが英語に翻訳された状態のHTMLが含まれます。

例2: OpenAIのGPT-4oモデルを使用してウェブページを翻訳し、カスタム出力ファイル名を指定する

この例では、OpenAI APIの gpt-4o モデルを使ってウェブページを翻訳し、翻訳結果を argparse_ja_to_en.html という名前で保存します。ソース言語とターゲット言語はデフォルト(JAからEN)が使用されます。

python translate_url.py "https://docs.python.org/ja/3/library/argparse.html" --api openai --model gpt-4o -o argparse_ja_to_en.html

実行結果の説明: Pythonの argparse モジュールの日本語ドキュメントがOpenAIの gpt-4o モデルによって英語に翻訳されます。翻訳されたHTMLコンテンツは argparse_ja_to_en.html というファイル名で保存されます。

例3: Geminiモデルでカスタムプロンプトを使用し、多バイト文字のみを翻訳対象とする

この例では、Gemini APIを使用して、多バイト文字(主に日本語など)を含むテキストノードのみを翻訳します。翻訳にはカスタムプロンプトが適用され、特定の翻訳スタイルを指示します。

python translate_url.py "https://www.example.co.jp/news/latest.html" --api gemini --model gemini-1.5-flash --prompt "あなたは日本の文化に精通した翻訳者です。ニュース記事を自然な英語に翻訳してください。" --limit-to-multibyte-str --output news_en.html

実行結果の説明: 日本のウェブサイトのニュースページがGeminiの gemini-1.5-flash モデルによって翻訳されます。--prompt オプションにより、日本の文化に詳しい翻訳者としての役割がモデルに与えられ、より適切な訳文が期待されます。--limit-to-multibyte-str が指定されているため、元々英語であるコンテンツが翻訳対象となるのを防ぎ、効率的な翻訳が行われます。翻訳されたコンテンツは news_en.html として保存されます。