Improve error messages in `replace_multiline_code_block`

scripts/doc_parsing_utils.py

@@ -567,27 +567,35 @@ def replace_multiline_code_block(
     block_a: MultilineCodeBlockInfo, block_b: MultilineCodeBlockInfo
 ) -> list[str]:
     """
-    Replace multiline code block a with block b leaving comments intact.
+    Replace multiline code block `a` with block `b` leaving comments intact.
 
     Syntax of comments depends on the language of the code block.
     Raises ValueError if the blocks are not compatible (different languages or different number of lines).
     """
 
+    start_line = block_a["start_line_no"]
+    end_line_no = start_line + len(block_a["content"]) - 1
+
     if block_a["lang"] != block_b["lang"]:
         raise ValueError(
-            "Code block has different language than the original block "
+            f"Code block (lines {start_line}-{end_line_no}) "
+            "has different language than the original block "
             f"('{block_a['lang']}' vs '{block_b['lang']}')"
         )
     if len(block_a["content"]) != len(block_b["content"]):
         raise ValueError(
-            "Code block has different number of lines than the original block "
+            f"Code block (lines {start_line}-{end_line_no}) "
+            "has different number of lines than the original block "
             f"({len(block_a['content'])} vs {len(block_b['content'])})"
         )
 
     block_language = block_a["lang"].lower()
     if block_language in {"mermaid"}:
         if block_a != block_b:
-            print("Skipping mermaid code block replacement. This should be checked manually.")
+            print(
+                f"Skipping mermaid code block replacement (lines {start_line}-{end_line_no}). "
+                "This should be checked manually."
+            )
         return block_a["content"].copy()  # We don't handle mermaid code blocks for now
 
     code_block: list[str] = []

scripts/tests/test_translation_fixer/test_code_blocks/test_code_blocks_lines_number_mismatch.py

@@ -28,7 +28,7 @@ def test_gt(runner: CliRunner, root_dir: Path, copy_test_files):
     assert fixed_content == expected_content  # Translated doc remains unchanged
     assert "Error processing docs/lang/docs/doc.md" in result.output
     assert (
-        "Code block has different number of lines than the original block (5 vs 4)"
+        "Code block (lines 14-18) has different number of lines than the original block (5 vs 4)"
     ) in result.output
 
 
@@ -50,5 +50,5 @@ def test_lt(runner: CliRunner, root_dir: Path, copy_test_files):
     assert fixed_content == expected_content  # Translated doc remains unchanged
     assert "Error processing docs/lang/docs/doc.md" in result.output
     assert (
-        "Code block has different number of lines than the original block (3 vs 4)"
+        "Code block (lines 16-18) has different number of lines than the original block (3 vs 4)"
     ) in result.output

scripts/tests/test_translation_fixer/test_code_blocks/test_code_blocks_mermaid.py

@@ -23,18 +23,24 @@ def test_translated(runner: CliRunner, root_dir: Path, copy_test_files):
     assert result.exit_code == 0, result.output
 
     fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text()
-    expected_content = Path(f"{data_path}/translated_doc_mermaid_translated.md").read_text()
+    expected_content = Path(
+        f"{data_path}/translated_doc_mermaid_translated.md"
+    ).read_text()
 
     assert fixed_content == expected_content  # Translated doc remains unchanged
     assert (
-        "Skipping mermaid code block replacement. This should be checked manually."
+        "Skipping mermaid code block replacement (lines 41-44). This should be checked manually."
     ) in result.output
 
 
-
 @pytest.mark.parametrize(
     "copy_test_files",
-    [(f"{data_path}/en_doc.md", f"{data_path}/translated_doc_mermaid_not_translated.md")],
+    [
+        (
+            f"{data_path}/en_doc.md",
+            f"{data_path}/translated_doc_mermaid_not_translated.md",
+        )
+    ],
     indirect=True,
 )
 def test_not_translated(runner: CliRunner, root_dir: Path, copy_test_files):
@@ -45,9 +51,9 @@ def test_not_translated(runner: CliRunner, root_dir: Path, copy_test_files):
     assert result.exit_code == 0, result.output
 
     fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text()
-    expected_content = Path(f"{data_path}/translated_doc_mermaid_not_translated.md").read_text()
+    expected_content = Path(
+        f"{data_path}/translated_doc_mermaid_not_translated.md"
+    ).read_text()
 
     assert fixed_content == expected_content  # Translated doc remains unchanged
-    assert (
-        "Skipping mermaid code block replacement. This should be checked manually."
-    ) not in result.output
+    assert ("Skipping mermaid code block replacement") not in result.output

scripts/tests/test_translation_fixer/test_code_blocks/test_code_blocks_wrong_lang_code.py

@@ -23,16 +23,17 @@ def test_wrong_lang_code_1(runner: CliRunner, root_dir: Path, copy_test_files):
     assert result.exit_code == 1, result.output
 
     fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text()
-    expected_content = Path(f"{data_path}/translated_doc_wrong_lang_code.md").read_text()
+    expected_content = Path(
+        f"{data_path}/translated_doc_wrong_lang_code.md"
+    ).read_text()
 
     assert fixed_content == expected_content  # Translated doc remains unchanged
     assert "Error processing docs/lang/docs/doc.md" in result.output
     assert (
-        "Code block has different language than the original block ('yaml' vs 'toml')"
+        "Code block (lines 16-19) has different language than the original block ('yaml' vs 'toml')"
     ) in result.output
 
 
-
 @pytest.mark.parametrize(
     "copy_test_files",
     [(f"{data_path}/en_doc.md", f"{data_path}/translated_doc_wrong_lang_code_2.md")],
@@ -46,10 +47,12 @@ def test_wrong_lang_code_2(runner: CliRunner, root_dir: Path, copy_test_files):
     assert result.exit_code == 1, result.output
 
     fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text()
-    expected_content = Path(f"{data_path}/translated_doc_wrong_lang_code_2.md").read_text()
+    expected_content = Path(
+        f"{data_path}/translated_doc_wrong_lang_code_2.md"
+    ).read_text()
 
     assert fixed_content == expected_content  # Translated doc remains unchanged
     assert "Error processing docs/lang/docs/doc.md" in result.output
     assert (
-        "Code block has different language than the original block ('' vs 'toml')"
+        "Code block (lines 16-19) has different language than the original block ('' vs 'toml')"
     ) in result.output