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