技術ドキュメント: translate_backends.py

プログラムの動作

translate_backends.py は、HTML、Markdown、および reStructuredText (RST) ドキュメント内の可視テキストコンテンツを、そのドキュメントの構造とフォーマットを維持しながら翻訳するためのPythonモジュールです。

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

  • フォーマット保持: HTMLタグ、Markdownのコードブロックやリンク、RSTのディレクティブやロールといった特定の構文要素を識別し、翻訳プロセスから保護します。これにより、翻訳によってドキュメントの構造が破損するのを防ぎます。

  • 選択的翻訳: プログラミングコード、スタイルシート、スクリプト、メタデータなど、翻訳すべきではない部分を自動的にスキップします。

  • 翻訳の健全性チェック: 翻訳されたテキストが元のテキストと比べて極端に長すぎたり短すぎたりしないかをチェックし、不適切な翻訳が適用されるのを防ぎます。

  • インライン要素の保護: 翻訳中に括弧、アスタリスクなどのインライン書式要素が誤って変更されないよう、一時的なトークンに置き換えて保護し、翻訳後に元に戻します。

このプログラムは、構造化されたドキュメントの国際化において、手動での編集を減らし、フォーマットの一貫性を保つという課題を解決します。

原理

translate_backends.py は、translate_core モジュールと連携して動作し、各ドキュメント形式の特性に応じた解析と翻訳を適用します。

  1. 共通翻訳ロジック (_translate_block 関数):

    • 任意のテキストブロックに対して翻訳を試みます。

    • translate_core.to_translate を使用して、テキストが翻訳の対象となる最小長やマルチバイト文字列の要件を満たしているかを確認します。

    • translate_core.translate を呼び出して実際の翻訳を行います。

    • 翻訳が成功した後、translate_core.check_translation を使用して、翻訳されたテキストが元のテキストと比較して許容される長さの比率内にあるかを確認します。これにより、翻訳の品質が低い、またはフォーマットを破壊するような翻訳が拒否されます。

    • 翻訳の履歴は data リストに追加され、元のテキストと翻訳されたテキストのペアが記録されます。

    • 翻訳が失敗した、またはチェックに合格しなかった場合は、元のテキストが返されます。

  2. HTMLドキュメントの翻訳 (translate_html_document 関数):

    • BeautifulSoup ライブラリを使用してHTML文字列を解析します。

    • HTMLツリー内のすべてのテキストノードを検索します。

    • SKIP_HTML_TAGS (例: script, style, pre, code など) に含まれる親タグを持つノードは翻訳から除外されます。

    • 各テキストノードのコンテンツは _translate_block を使用して翻訳され、翻訳されたテキストで元のノードが置き換えられます。

  3. インライン要素の保護と復元 (_protect_inline, _restore_inline 関数):

    • _protect_inline は、正規表現パターンにマッチするインライン要素(例: Markdownのリンクやコードスニペット)を一時的な保護トークン (@@TKPROTECTED_XXX@@) に置き換えます。これにより、翻訳プロセス中にこれらの要素が変更されるのを防ぎます。

    • 保護された要素は、元の文字列とそのトークンのペアとしてリストに格納されます。

    • _restore_inline は、翻訳が完了したテキスト内の保護トークンを、元のインライン要素に戻します。翻訳されたテキスト内にトークンが見つからない場合(翻訳によってトークンが破壊された場合)は None を返し、不正な変更を検出します。

  4. マークアップ行の翻訳 (_translate_markup_line 関数):

    • MarkdownやRSTのような行指向のマークアップ言語の翻訳に特化した関数です。

    • 行末の改行文字を保存します。

    • prefix_pattern が指定されている場合、行頭のマークアップ(リストの記号、見出しのハッシュなど)を抽出し、翻訳対象から除外します。

    • 行本体に対して _protect_inline を適用し、インライン要素を保護します。

    • マスクされた(インライン要素がトークンに置き換えられた)テキストを _translate_block で翻訳します。

    • 翻訳後、_restore_inline でインライン要素を復元します。

    • 復元が失敗した場合や、翻訳の健全性チェックに合格しなかった場合は、元の行が保持されます。

  5. Markdownドキュメントの翻訳 (translate_markdown_document 関数):

    • テキストを各行に分割して処理します。

    • YAMLフロントマター、コードフェンス (``` または ~~~)、インデントされたコードブロック、HTMLコメント、定義リストのような行は翻訳からスキップされます。

    • MARKDOWN_INLINE に定義されたパターン(例: バッククォートで囲まれたコード、リンク、画像、URL)と、見出し、リスト、ブロッククォートなどの行頭プレフィックスを考慮して _translate_markup_line を呼び出します。

  6. reStructuredText (RST) ドキュメントの翻訳 (translate_rst_document 関数):

    • テキストを各行に分割して処理します。

    • Sphinxディレクティブ (.. ::)、明示的なハイパーリンク (.. _label:)、特定のインラインロール (:role:), セクションタイトル区切り線 (例: ===, ---) はスキップされます。

    • :: で終わる行は、それに続くリテラルブロックの開始を示し、そのインデントレベルを追跡して、リテラルブロック内の行をスキップします。

    • RST_INLINE に定義されたパターン(例: ロール、ハイパーリンク、リテラルテキスト)と、リスト、ディレクティブなどの行頭プレフィックスを考慮して _translate_markup_line を呼び出します。

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

このプログラムは、以下の非標準ライブラリに依存しています。

  • BeautifulSoup4 (bs4): HTMLドキュメントの解析に使用されます。

インストール方法:

pip install beautifulsoup4

また、このプログラムは translate_core.py モジュールに依存しています。このモジュールは、翻訳ロジックと設定管理を提供します。translate_backends.py と同じディレクトリに配置するか、Pythonのモジュールパスが通っている場所に配置する必要があります。

必要な入力ファイル

このプログラムは、ファイルパスを直接入力として受け取るようには設計されていません。代わりに、以下の形式のテキストコンテンツを文字列として受け取ります。

  • HTML文字列: translate_html_document 関数に渡されるHTML形式のテキスト。

  • Markdown文字列: translate_markdown_document 関数に渡されるMarkdown形式のテキスト。

  • reStructuredText (RST) 文字列: translate_rst_document 関数に渡されるRST形式のテキスト。

これらの入力文字列は、翻訳対象の言語コンテンツを含んでいる必要があります。

生成される出力ファイル

translate_backends.py は、直接ファイルを出力することはありません。 各翻訳関数は、以下の要素を含むタプルを返します。

  1. 翻訳されたドキュメントの文字列: 翻訳後のHTML、Markdown、またはRST形式のテキストコンテンツ。

  2. 翻訳履歴のリスト: 翻訳された各テキストブロックのオリジナルと翻訳後のテキストを格納する辞書のリスト。 例:

    [
        {"original": "Original text block 1.", "translated": "Translated text block 1."},
        {"original": "Original text block 2.", "translated": "Translated text block 2."},
        # ...
    ]
    

このリストは、翻訳のログ、品質検証、または追加の処理に利用できます。

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

translate_backends.py は、直接コマンドラインから実行されることを想定していません。if __name__ == "__main__": ブロックがないため、他のPythonスクリプトからモジュールとしてインポートされ、その中の関数が呼び出されることを意図しています。

このモジュールを使用するには、translate_core から設定オブジェクトとプロンプトを準備する必要があります。

# main_translator.py (例)

from translate_backends import (
    translate_html_document,
    translate_markdown_document,
    translate_rst_document,
)
from translate_core import Config, TranslationPrompt # translate_core モジュールから取得

# 翻訳設定の準備
# (Configオブジェクトは translate_core モジュールの設定クラスから生成されます)
cfg = Config(
    api_key="YOUR_API_KEY",
    model="gpt-4",
    source_lang="en",
    target_lang="ja",
    # その他の設定...
)

# 翻訳プロンプトの準備
# (TranslationPromptオブジェクトは translate_core モジュールのプロンプトクラスから生成されます)
prompt = TranslationPrompt(
    system_message="You are a helpful translator.",
    user_message_template="Translate the following text from {source_lang} to {target_lang}:\n\n{text}",
)

# HTMLドキュメントの翻訳
html_input = """
<html>
<head><title>Hello World</title></head>
<body>
    <h1>Welcome</h1>
    <p>This is a paragraph of text to be translated.</p>
    <pre><code>print("Hello")</code></pre>
</body>
</html>
"""
translated_html, html_data = translate_html_document(html_input, prompt, cfg)
print("--- Translated HTML ---")
print(translated_html)
print("--- HTML Translation Data ---")
print(html_data)

# Markdownドキュメントの翻訳
markdown_input = """
---
title: My Document
author: John Doe
---

# Introduction

This is some **important** text.

```python
def hello():
    print("World")
  • Item 1

  • Item 2

Link to Google """ translated_markdown, markdown_data = translate_markdown_document(markdown_input, prompt, cfg) print("\n--- Translated Markdown ---") print(translated_markdown) print("--- Markdown Translation Data ---") print(markdown_data)

reStructuredTextドキュメントの翻訳

rst_input = """ My Document

This is a paragraph in RST.

.. note:: This is a note directive.

A literal code block::

print("RST example")
another line
  • List item one

  • List item two

External Link <https://www.example.com>_ """ translated_rst, rst_data = translate_rst_document(rst_input, prompt, cfg) print("\n--- Translated RST ---") print(translated_rst) print("--- RST Translation Data ---") print(rst_data)


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

前述の通り、`translate_backends.py` は他のスクリプトからインポートして使用されるモジュールです。そのため、具体的なコマンドライン実行は、そのモジュールをインポートする上位のスクリプトによって制御されます。

上記「コマンドラインでの使用例 (Usage)」で示した `main_translator.py` を作成した場合の実行例を以下に示します。

**`main_translator.py` の実行:**

```bash
python main_translator.py

想定される実行結果 (翻訳の具体的な内容は、translate_core の実装と翻訳APIの応答に依存します):

--- Translated HTML ---
<html>
<head><title>こんにちは世界</title></head>
<body>
    <h1>ようこそ</h1>
    <p>これは翻訳されるテキストの段落です。</p>
    <pre><code>print("Hello")</code></pre>
</body>
</html>
--- HTML Translation Data ---
[{'original': 'Hello World', 'translated': 'こんにちは世界'}, {'original': 'Welcome', 'translated': 'ようこそ'}, {'original': 'This is a paragraph of text to be translated.', 'translated': 'これは翻訳されるテキストの段落です。'}]

--- Translated Markdown ---
---
title: My Document
author: John Doe
---

# はじめに

これは**重要な**テキストです。

```python
def hello():
    print("World")
  • 項目1

  • 項目2

Googleへのリンク --- Markdown Translation Data --- [{'original': 'Introduction', 'translated': 'はじめに'}, {'original': 'This is some important text.', 'translated': 'これは重要なテキストです。'}, {'original': 'Item 1', 'translated': '項目1'}, {'original': 'Item 2', 'translated': '項目2'}]

--- Translated RST --- 私のドキュメント

これはRSTの段落です。

.. note:: これはメモディレクティブです。

リテラルコードブロック::

print("RST example")
another line
  • リスト項目1

  • リスト項目2

外部リンク <https://www.example.com>_ --- RST Translation Data --- [{'original': 'My Document', 'translated': '私のドキュメント'}, {'original': 'This is a paragraph in RST.', 'translated': 'これはRSTの段落です。'}, {'original': 'List item one', 'translated': 'リスト項目1'}, {'original': 'List item two', 'translated': 'リスト項目2'}]

(注:翻訳APIの動作によっては、出力される翻訳テキストや、`_translate_markup_line` の `check_translation` によるスキップ判定が異なり、上記の結果とは異なる場合があります。)