Preserve translation formatting in code-block reviews

Author: methane

AGENTS.md

@@ -5,6 +5,7 @@
 - 用語集の `translation_ja` を採用する訳語の基準とし、`pos` と `notes` で品詞や適用する文脈を確認してください。訳語が空欄の項目は、既存訳から用例を探してください。
 - 重要な用語は既存 PO から用例を検索してください。検索対象は `.tx/config` に載っている現行 PO を基本とし、未翻訳・fuzzy・obsolete のエントリーを訳例として採用しないでください。
 - 明示された用語の決定を優先し、文体は対象節の既存訳に合わせてください。
+- 英語の文頭の大文字をそのまま引き継がず、一般概念と識別子を文脈に応じて区別してください。例えば数学的な set は「集合」、Python の型を指す Set objects は「``set`` オブジェクト」とします。識別子の大文字・小文字は実際の綴りに合わせてください。
 - 関数・メソッドの説明では、直前のシグネチャも確認し、一般用語と仮引数名を区別してください。仮引数名は翻訳せず、原文の識別子を保持してください。原文でマークアップされていなくても仮引数名を指す場合は、ダブルバッククォートで囲んでください。
 - 既存訳が食い違う場合は黙って統一せず、レビュー資料に候補と判断理由を記載してください。
 - 参照数を原文に合わせるために `:mod:`、`:class:`、`:func:`、`:meth:`、`:const:` などのコード要素の参照を外す場合は、名前をダブルバッククォートで囲むインラインリテラルにしてください。関数名・メソッド名には `()` を付けてください。
@@ -15,3 +16,5 @@
 - 理由・条件などの説明は、主語と述語の間に挟まず、文頭に置くことを検討してください。
 - 読点は意味のまとまりを区切るために使い、主語の直後に機械的に打たないでください。
 - 読点で読みやすくしようとする前に、語順を見直してください。
+- 翻訳文自体に句点の後で改行を入れてください。長い文では読点の後でも改行し、意味のまとまりを読み取りやすくしてください。改行直後に不要なスペースを残さないでください。
+- reStructuredText のインラインマークアップやコード例の途中は改行せず、コードブロックのインデントや文末の「。 ::」など、構文上必要なまとまりは保持してください。

scripts/po_review.py

@@ -58,44 +58,11 @@ def escape(text):
     return re.sub(r"([\\`*_\[\]<>#|~])", r"\\\1", text.replace("&", "&amp;"))
 
 
-INLINE_RST = re.compile(
-    r"(?<![\\`])(?::[\w.-]+(?::[\w.-]+)*:)?"
-    r"(?P<ticks>`{1,2})(?!`)(?:\\.|[^`\\\n])+(?P=ticks)(?!`)"
-)
-
-
-def inline_text(text):
-    # Preserve the whole reST token in a Markdown code span, including its
-    # role and backticks. This avoids backslash noise in the Markdown source.
-    parts = []
-    start = 0
-    for match in INLINE_RST.finditer(text):
-        parts.append(escape(text[start:match.start()]))
-        token = match.group()
-        fence = "`" * (1 + max(len(run) for run in re.findall(r"`+", token)))
-        parts.append(f"{fence} {token} {fence}")
-        start = match.end()
-    parts.append(escape(text[start:]))
-    result = "".join(parts)
-    # Prevent prose lines from becoming Markdown lists or thematic breaks.
-    return re.sub(r"^(\s*)([-+]|\d+[.)])(?=\s|$)",
-                  lambda match: match[1] + match[2][:-1] + "\\" + match[2][-1], result)
-
-
-def paragraph(text):
-    return "\n".join(
-        "> " + inline_text(line) + ("  " if line else "")
-        for line in text.split("\n")
-    )
-
-
 def field(label, text):
-    # Keep indentation and alignment in code examples, while allowing prose
-    # to wrap naturally in the Markdown viewer.
-    if text.startswith((">>> ", ".. code-block::", ".. code::")):
-        fence = "`" * max(3, 1 + max((len(run) for run in re.findall(r"`+", text)), default=0))
-        return f"**{label}**\n\n{fence}text\n{text}\n{fence}\n"
-    return f"**{label}**\n\n{paragraph(text)}\n"
+    # Preserve PO text verbatim, including line breaks and reST markup.
+    # Embedded backticks must not be able to close the Markdown fence.
+    fence = "`" * max(3, 1 + max((len(run) for run in re.findall(r"`+", text)), default=0))
+    return f"**{label}**\n\n{fence}rst\n{text}\n{fence}\n"
 
 
 def translation(entry):

tests/test_po_review.py

@@ -46,8 +46,8 @@ def test_plural_fuzzy_and_empty_translations(self):
                            msgstr_plural={0: "ファイル", 1: ""})
         text = po_review.render_entry("test.po", old, new, 1, "test.po")
         self.assertIn("Many files", text)
-        self.assertIn(r"msgstr\[1\]: 複数のファイル", text)
-        self.assertIn(r"msgstr\[1\]: （未翻訳）", text)
+        self.assertIn("msgstr[1]: 複数のファイル", text)
+        self.assertIn("msgstr[1]: （未翻訳）", text)
         self.assertIn("fuzzy（要確認） → 未翻訳", text)
         new.msgstr_plural[1] = old.msgstr_plural[1]
         self.assertNotEqual(po_review.signature(old), po_review.signature(new))
@@ -63,17 +63,18 @@ def test_new_removed_and_obsolete_entries(self):
 
     def test_markdown_and_html_are_literal(self):
         text = ':func:`open` <tag> [link](url) **bold**\n\n```\nnext'
-        result = po_review.paragraph(text)
-        self.assertIn(r"`` :func:`open` `` \<tag\> \[link\](url) \*\*bold\*\*", result)
-        self.assertIn("> \n> \\`\\`\\`", result)
-        self.assertEqual("> &amp;copy;  ", po_review.paragraph("&copy;"))
+        self.assertEqual(
+            "**変更後**\n\n````rst\n" + text + "\n````\n",
+            po_review.field("変更後", text),
+        )
+        self.assertEqual("**訳文**\n\n```rst\n&copy;\n```\n",
+                         po_review.field("訳文", "&copy;"))
 
     def test_rst_roles_and_literals_do_not_need_backslash_escapes(self):
         text = ':ref:`tut-object` と :py:class:`表示名 <module.Class>`、``a_b``。'
-        result = po_review.paragraph(text)
+        result = po_review.field("訳文", text)
         self.assertEqual(
-            '> `` :ref:`tut-object` `` と `` :py:class:`表示名 <module.Class>` ``、'
-            '``` ``a_b`` ```。  ', result,
+            '**訳文**\n\n```rst\n' + text + '\n```\n', result,
         )
         self.assertNotIn("\\", result)
         self.assertEqual("../../tutorial/classes.rst:422 (source)",
@@ -82,7 +83,19 @@ def test_rst_roles_and_literals_do_not_need_backslash_escapes(self):
     def test_code_examples_keep_indentation_and_cannot_close_fence(self):
         code = '>>> if True:\n...     print("````")\n````'
         result = po_review.field("原文", code)
-        self.assertIn("`````text\n" + code + "\n`````", result)
+        self.assertIn("`````rst\n" + code + "\n`````", result)
+
+    def test_prose_line_breaks_and_spaces_are_preserved(self):
+        for text in (
+            '一文目です。 続く長い文、さらに続きます。',
+            '一文目です。\n続く長い文、\nさらに続きます。 ::\n',
+            '  先頭の空白。\n末尾の空白。 ',
+        ):
+            with self.subTest(text=text):
+                self.assertEqual(
+                    '**訳文**\n\n```rst\n' + text + '\n```\n',
+                    po_review.field("訳文", text),
+                )
 
 
 class GitReportTests(unittest.TestCase):