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

translate_backends.py をダウンロード

translate_backends.py
translate_backends.py
  1"""Format-aware translation backends for HTML, Markdown, and reStructuredText.
  2
  3このモジュールは、HTML、Markdown、およびreStructuredTextドキュメントの形式を考慮した翻訳バックエンドを提供します。
  4構造化されたテキストコンテンツ(HTMLタグ、Markdown/RSTの書式、コードブロックなど)を保護しつつ、
  5表示可能なテキストや散文のみを翻訳します。これにより、翻訳後も元のドキュメントの構造と機能が維持されます。
  6
  7:doc:`translate_backends_usage`
  8"""
  9
 10import re
 11
 12from bs4 import BeautifulSoup
 13
 14from translate_core import check_translation, to_translate, translate
 15
 16
 17SKIP_HTML_TAGS = {"script", "style", "noscript", "template", "pre", "code", "kbd", "samp"}
 18PROTECTED_TOKEN = "@@TKPROTECTED_{:03d}@@"
 19
 20
 21def _translate_block(text, prompt, cfg, data, label="text"):
 22    """指定されたテキストブロックを翻訳し、翻訳結果を検証します。
 23
 24    翻訳が必要な長さであるか、多バイト文字の制限を満たすかを確認し、翻訳エンジンを呼び出します。
 25    翻訳が失敗した場合や検証にパスしなかった場合は、元のテキストを返します。
 26    翻訳が成功し検証された場合、オリジナルと翻訳結果は ``data`` リストに追加されます。
 27
 28    :param text: str: 翻訳するテキストブロック。
 29    :param prompt: str: 翻訳プロンプト。
 30    :param cfg: configparser.SectionProxy: 翻訳設定を含む設定オブジェクト。
 31    :param data: list[dict]: 翻訳のオリジナルと結果を ``{"original": ..., "translated": ...}`` 形式で格納するリスト。
 32    :param label: str, optional: ログ出力用のラベル。デフォルトは "text"。
 33    :returns: str: 翻訳された、または元のテキストブロック。
 34    """
 35    if not to_translate(text, cfg.min_translate_length, cfg.limit_to_multibyte_str):
 36        return text
 37    try:
 38        revised = translate(text, prompt, cfg)
 39    except Exception as exc:
 40        print(f"  *** Translation failed for {label}; keeping original: {exc}")
 41        return text
 42    if not check_translation(text, revised, cfg.allowed_translation_length_ratio):
 43        print(f"  *** Translation rejected for {label}; keeping original")
 44        return text
 45    data.append({"original": text, "translated": revised})
 46    return revised
 47
 48
 49def translate_html_document(html, prompt, cfg):
 50    """HTMLドキュメント内の表示可能なテキストを翻訳します。
 51
 52    BeautifulSoupを使用してHTMLを解析し、スクリプト、スタイル、プリフォーマットされたコードなどの
 53    特定のタグ内のコンテンツを除く、すべてのテキストノードを走査します。
 54    各テキストノードは ``_translate_block`` を使用して翻訳されます。
 55    HTMLの構造は維持されます。
 56
 57    :param html: str: 翻訳するHTML文字列。
 58    :param prompt: str: 翻訳プロンプト。
 59    :param cfg: configparser.SectionProxy: 翻訳設定を含む設定オブジェクト。
 60    :returns: tuple[str, list[dict]]: 翻訳されたHTML文字列と、オリジナルおよび翻訳済みテキストのペアのリスト。
 61    """
 62    soup = BeautifulSoup(html, "html.parser")
 63    data = []
 64    for node in soup.find_all(string=True):
 65        parent = node.parent
 66        if parent and parent.name and parent.name.lower() in SKIP_HTML_TAGS:
 67            continue
 68        original = str(node)
 69        revised = _translate_block(original, prompt, cfg, data, "HTML node")
 70        if revised != original:
 71            node.replace_with(revised)
 72    return str(soup), data
 73
 74
 75def _protect_inline(text, patterns):
 76    """テキスト内の特定のインライン要素を保護トークンに置き換えます。
 77
 78    マークアップ言語のコードスニペット、リンク、参照などのインライン要素が
 79    翻訳エンジンによって変更されないように、一時的なプレースホルダー(保護トークン)に置き換えます。
 80
 81    :param text: str: 処理するテキスト。
 82    :param patterns: list[str]: 保護するインライン要素に一致する正規表現パターンのリスト。
 83    :returns: tuple[str, list[tuple[str, str]]]: 保護トークンに置き換えられたテキストと、``(トークン, オリジナルテキスト)`` のペアのリスト。
 84    """
 85    protected = []
 86
 87    def replace(match):
 88        token = PROTECTED_TOKEN.format(len(protected))
 89        protected.append((token, match.group(0)))
 90        return token
 91
 92    for pattern in patterns:
 93        text = re.sub(pattern, replace, text)
 94    return text, protected
 95
 96
 97def _restore_inline(text, protected):
 98    """保護トークンを元のインライン要素に戻します。
 99
100    ``_protect_inline`` で置き換えられた保護トークンを、元のテキストコンテンツに復元します。
101    すべてのトークンがテキスト内に存在しない場合(翻訳によって削除されたなど)はNoneを返します。
102
103    :param text: str: 保護トークンを含むテキスト。
104    :param protected: list[tuple[str, str]]: ``_protect_inline`` から返された ``(トークン, オリジナルテキスト)`` のペアのリスト。
105    :returns: str or None: トークンがすべて復元されたテキスト。復元に失敗した場合はNone。
106    """
107    if any(token not in text for token, _ in protected):
108        return None
109    for token, original in protected:
110        text = text.replace(token, original)
111    return text
112
113
114def _translate_markup_line(line, prompt, cfg, data, patterns, prefix_pattern=None):
115    """マークアップ言語の1行を翻訳し、特定のインライン要素を保護します。
116
117    行末の改行を保持し、行頭の書式(リストマーカーなど)やインライン要素
118    (コードスニペット、リンクなど)を保護しつつ、行の本文を翻訳します。
119    翻訳後、保護トークンを復元し、翻訳の整合性をチェックします。
120    保護されたマークアップが変更された場合や翻訳が不適切な場合は、元の行が返されます。
121
122    :param line: str: 翻訳するマークアップ行。
123    :param prompt: str: 翻訳プロンプト。
124    :param cfg: configparser.SectionProxy: 翻訳設定を含む設定オブジェクト。
125    :param data: list[dict]: 翻訳のオリジナルと結果を ``{"original": ..., "translated": ...}`` 形式で格納するリスト。
126    :param patterns: list[str]: 保護するインライン要素に一致する正規表現パターンのリスト。
127    :param prefix_pattern: str, optional: 行頭の書式を抽出するための正規表現パターン。デフォルトはNone。
128    :returns: str: 翻訳された、または元のマークアップ行。
129    """
130    ending = "\n" if line.endswith("\n") else ""
131    body = line[:-1] if ending else line
132    prefix = ""
133    if prefix_pattern:
134        match = re.match(prefix_pattern, body)
135        if match:
136            prefix, body = match.group(0), body[match.end():]
137    masked, protected = _protect_inline(body, patterns)
138    revised = _translate_block(masked, prompt, cfg, [], "markup line")
139    if revised == masked:
140        return line
141    restored = _restore_inline(revised, protected)
142    if restored is None or not check_translation(body, restored, cfg.allowed_translation_length_ratio):
143        print("  *** Protected markup changed; keeping original line")
144        return line
145    data.append({"original": line.rstrip("\n"), "translated": (prefix + restored)})
146    return prefix + restored + ending
147
148
149MARKDOWN_INLINE = [
150    r"`[^`]*`", r"!?\[[^\]]*\]\([^)]*\)", r"\{[A-Za-z][\w-]*\}",
151    r"<https?://[^>]+>", r"https?://\S+",
152]
153RST_INLINE = [
154    r":\w+(?::\w+)?:`[^`]*`", r"`[^`<>]+\s*<[^>]+>`_?", r"``[^`]*``", r"https?://\S+",
155]
156
157
158def translate_markdown_document(text, prompt, cfg):
159    """Markdownドキュメント内のプロース(散文)を翻訳します。
160
161    Markdownのフロントマター(---で囲まれた部分)、コードフェンス(```または~~~)、
162    インデントされたコードブロック、およびHTMLコメントをスキップし、
163    Markdownのインライン書式を保護しながらテキスト行を翻訳します。
164
165    :param text: str: 翻訳するMarkdown文字列。
166    :param prompt: str: 翻訳プロンプト。
167    :param cfg: configparser.SectionProxy: 翻訳設定を含む設定オブジェクト。
168    :returns: tuple[str, list[dict]]: 翻訳されたMarkdown文字列と、オリジナルおよび翻訳済みテキストのペアのリスト。
169    """
170    lines, data, in_fence = text.splitlines(keepends=True), [], False
171    front_matter = bool(lines and lines[0].strip() == "---")
172    for index, line in enumerate(lines):
173        stripped = line.strip()
174        if front_matter:
175            if index and stripped in {"---", "..."}:
176                front_matter = False
177            continue
178        if re.match(r"^\s*(```|~~~)", line):
179            in_fence = not in_fence
180            continue
181        if (
182            in_fence
183            or re.match(r"^(\s{4}|\t)", line)
184            or re.match(r"^\s*:\w[\w-]*:\s*", line)
185            or stripped.startswith("<!--")
186        ):
187            continue
188        lines[index] = _translate_markup_line(
189            line, prompt, cfg, data, MARKDOWN_INLINE,
190            r"^\s*(?:#{1,6}\s+|[-+*]\s+|\d+[.)]\s+|>\s*)",
191        )
192    return "".join(lines), data
193
194
195def translate_rst_document(text, prompt, cfg):
196    """reStructuredText (RST) ドキュメント内のプロース(散文)を翻訳します。
197
198    Sphinxディレクティブ (例: ``.. note::``)、参照定義 (例: ``.. _label:``)、
199    フィールドリスト、セクションタイトル区切り線、およびリテラルブロックを保護しつつ、
200    RSTのインライン書式を考慮しながらテキスト行を翻訳します。
201
202    :param text: str: 翻訳するreStructuredText文字列。
203    :param prompt: str: 翻訳プロンプト。
204    :param cfg: configparser.SectionProxy: 翻訳設定を含む設定オブジェクト。
205    :returns: tuple[str, list[dict]]: 翻訳されたreStructuredText文字列と、オリジナルおよび翻訳済みテキストのペアのリスト。
206    """
207    lines, data = text.splitlines(keepends=True), []
208    literal_indent = None
209    for index, line in enumerate(lines):
210        stripped = line.strip()
211        indent = len(line) - len(line.lstrip(" "))
212        if literal_indent is not None:
213            if not stripped or indent >= literal_indent:
214                continue
215            literal_indent = None
216        if re.match(r"^\s*\.\.\s+(?:\w|_)+::", line):  # ディレクティブ (例: .. note::)
217            continue
218        if re.match(r"^\s*\.\.\s+_[^:]+:", line) or re.match(r"^\s*:\w[^:]*:\s*", line):  # 参照定義、フィールドリスト
219            continue
220        if re.match(r"^\s*\.\.", line) or re.match(r"^[=\-~^\"`:#*+]+\s*$", line):  # コメント、セクション区切り線
221            continue
222        if stripped.endswith("::"):  # リテラルブロックの開始 (例: ::)
223            lines[index] = _translate_markup_line(line, prompt, cfg, data, RST_INLINE)
224            literal_indent = indent + 1
225            continue
226        lines[index] = _translate_markup_line(
227            line, prompt, cfg, data, RST_INLINE, r"^\s*(?:[-*+]\s+|\d+[.)]\s+|\.\.\s+\w+::\s*)",
228        )
229    return "".join(lines), data