translation_review: Add ODT and PDF export; fast default

Default to a single translate API call per unit; add --with-review for
the two-step review flow.
Support --generate pdf,odt, CLI api-key/base-url
overrides, and run options in summary.txt. Integrate ODT export via
translateodt translation_overrides.

Author: holybiber

config.example.ini

@@ -89,8 +89,8 @@ deeplapikey = MySecretDeepLAPIKey
 [translationreview]
 # Which mediawiki environment do we read from? 4training, test or local (see family.py)
 site = 4training
-# OpenAI API configuration (read-only tool, no wiki writes)
-openai_api_key = sk-...
+# OpenAI-compatible API configuration (read-only tool, no wiki writes)
+api_key = sk-...
 model = gpt-4o
 # Optional: custom API base URL (leave unset for OpenAI default)
 # base_url = https://api.openai.com/v1
@@ -107,5 +107,5 @@ source_site = test
 destination_site = local
 # The username for the destination site
 destination_username = CorrectBot
-# Example call for transfer: 
-# python3 transfer.py "A_Daily_Prayer" "fr" 
+# Example call for transfer:
+# python3 transfer.py "A_Daily_Prayer" "fr"

pywikitools/test/test_translationreview.py

@@ -12,8 +12,8 @@
 )
 from pywikitools.translationreview.openai_client import TIMEOUT_SENTINEL
 from pywikitools.translationreview.prompts import (
-    build_best_translation_prompt,
     build_review_prompt,
+    build_translate_prompt,
     language_name,
 )
 
@@ -25,7 +25,7 @@ def make_config(temp_dir: str) -> ConfigParser:
             "Paths": {"temp": temp_dir},
             "translationreview": {
                 "site": "4training",
-                "openai_api_key": "test-key",
+                "api_key": "test-key",
                 "model": "gpt-4o",
                 "reference_language": "de",
                 "request_delay": "0",
@@ -74,8 +74,8 @@ def test_review_prompt_contains_all_texts(self):
         self.assertIn("teyze", prompt)
         self.assertIn("do NOT provide a final improved translation", prompt)
 
-    def test_best_translation_prompt_includes_review(self):
-        prompt = build_best_translation_prompt(
+    def test_translate_after_review_prompt_includes_review_and_guidelines(self):
+        prompt = build_translate_prompt(
             language_code="tr",
             english="Pray for others",
             reference="Betet für andere",
@@ -84,6 +84,19 @@ def test_best_translation_prompt_includes_review(self):
         )
         self.assertIn("ONLY the best improved translation", prompt)
         self.assertIn("The translation is good but could be more natural.", prompt)
+        self.assertIn("teyze", prompt)
+
+    def test_translate_prompt(self):
+        prompt = build_translate_prompt(
+            language_code="tr",
+            english="Pray for others",
+            reference="Betet für andere",
+            target="Başkaları için dua et",
+        )
+        self.assertIn("ONLY the best improved translation", prompt)
+        self.assertIn("Pray for others", prompt)
+        self.assertIn("teyze", prompt)
+        self.assertNotIn("do NOT provide a final improved translation", prompt)
 
     def test_default_guidelines_for_unknown_language(self):
         prompt = build_review_prompt(
@@ -140,6 +153,56 @@ def test_model_cli_override(
         mock_openai_cls.assert_called_once()
         self.assertEqual(mock_openai_cls.call_args.kwargs["model"], "gpt-4.1")
 
+    @patch("pywikitools.translationreview.bot.OpenAIClient")
+    @patch("pywikitools.translationreview.bot.ForTrainingLib")
+    @patch("pywikitools.translationreview.bot.Family")
+    def test_api_key_cli_override(
+        self, mock_family, mock_fortraininglib_cls, mock_openai_cls
+    ):
+        TranslationReviewBot(self.config, api_key="cli-key")
+        mock_openai_cls.assert_called_once()
+        self.assertEqual(mock_openai_cls.call_args.kwargs["api_key"], "cli-key")
+
+    @patch("pywikitools.translationreview.bot.OpenAIClient")
+    @patch("pywikitools.translationreview.bot.ForTrainingLib")
+    @patch("pywikitools.translationreview.bot.Family")
+    def test_base_url_cli_override(
+        self, mock_family, mock_fortraininglib_cls, mock_openai_cls
+    ):
+        TranslationReviewBot(
+            self.config,
+            base_url="https://openrouter.ai/api/v1",
+        )
+        mock_openai_cls.assert_called_once()
+        self.assertEqual(
+            mock_openai_cls.call_args.kwargs["base_url"],
+            "https://openrouter.ai/api/v1",
+        )
+
+    @patch("pywikitools.translationreview.bot.OpenAIClient")
+    @patch("pywikitools.translationreview.bot.ForTrainingLib")
+    @patch("pywikitools.translationreview.bot.Family")
+    def test_missing_api_key_raises(
+        self, mock_family, mock_fortraininglib_cls, mock_openai_cls
+    ):
+        config = make_config(self.temp_dir)
+        config.remove_option("translationreview", "api_key")
+        with self.assertRaisesRegex(RuntimeError, "Missing API key"):
+            TranslationReviewBot(config)
+        mock_openai_cls.assert_not_called()
+
+    @patch("pywikitools.translationreview.bot.OpenAIClient")
+    @patch("pywikitools.translationreview.bot.ForTrainingLib")
+    @patch("pywikitools.translationreview.bot.Family")
+    def test_api_key_cli_works_without_config_key(
+        self, mock_family, mock_fortraininglib_cls, mock_openai_cls
+    ):
+        config = make_config(self.temp_dir)
+        config.remove_option("translationreview", "api_key")
+        TranslationReviewBot(config, api_key="cli-only-key")
+        mock_openai_cls.assert_called_once()
+        self.assertEqual(mock_openai_cls.call_args.kwargs["api_key"], "cli-only-key")
+
     @patch("pywikitools.translationreview.bot.OpenAIClient")
     @patch("pywikitools.translationreview.bot.ForTrainingLib")
     @patch("pywikitools.translationreview.bot.Family")
@@ -164,13 +227,13 @@ def test_default_output_dir_includes_model_and_date(
             "translation_review/Forgiving_Step_by_Step_tr_openai-gpt-4o_",
             out_dir,
         )
-        date_part = out_dir.rstrip("/").rsplit("_", 1)[-1]
-        self.assertRegex(date_part, r"^\d{4}-\d{2}-\d{2}$")
+        date_part = out_dir.rstrip("/").split("openai-gpt-4o_")[-1]
+        self.assertRegex(date_part, r"^\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}$")
 
     @patch("pywikitools.translationreview.bot.OpenAIClient")
     @patch("pywikitools.translationreview.bot.ForTrainingLib")
     @patch("pywikitools.translationreview.bot.Family")
-    def test_run_processes_units_with_two_api_calls(
+    def test_run_default_one_api_call_per_unit(
         self, mock_family, mock_fortraininglib_cls, mock_openai_cls
     ):
         target_units = [
@@ -194,36 +257,134 @@ def test_run_processes_units_with_two_api_calls(
         mock_client = MagicMock()
         mock_openai_cls.return_value = mock_client
         mock_client.complete.side_effect = [
-            "Review for unit 1",
             "Improved translation 1",
-            "Review for unit 2",
             "Improved translation 2",
         ]
 
         bot = TranslationReviewBot(self.config)
-        summary = bot.run("Test", "tr", output_dir=self.temp_dir)
+        summary = bot.run(
+            "Test",
+            "tr",
+            output_dir=self.temp_dir,
+            run_options={"loglevel": "warning", "with_review": "no"},
+        )
 
         self.assertEqual(summary.processed, 2)
         self.assertEqual(summary.skipped, 0)
         self.assertEqual(summary.failed, 0)
-        self.assertEqual(mock_client.complete.call_count, 4)
+        self.assertFalse(summary.with_review)
+        self.assertEqual(mock_client.complete.call_count, 2)
 
         review_path = os.path.join(self.temp_dir, "review_report.md")
         best_path = os.path.join(self.temp_dir, "best_translations.wiki")
         summary_path = os.path.join(self.temp_dir, "summary.txt")
 
-        with open(review_path, encoding="utf-8") as handle:
-            review_content = handle.read()
+        self.assertFalse(os.path.isfile(review_path))
         with open(best_path, encoding="utf-8") as handle:
             best_content = handle.read()
         with open(summary_path, encoding="utf-8") as handle:
             summary_content = handle.read()
 
-        self.assertIn("## Prayer/1", review_content)
-        self.assertIn("Review for unit 1", review_content)
         self.assertIn("=== Prayer/1 ===", best_content)
         self.assertIn("Improved translation 1", best_content)
         self.assertIn("Processed: 2", summary_content)
+        self.assertIn("with_review: no", summary_content)
+        self.assertIn("loglevel: warning", summary_content)
+        self.assertIn("model: gpt-4o", summary_content)
+
+    @patch("pywikitools.translationreview.bot.OpenAIClient")
+    @patch("pywikitools.translationreview.bot.ForTrainingLib")
+    @patch("pywikitools.translationreview.bot.Family")
+    def test_run_with_review_two_api_calls_per_unit(
+        self, mock_family, mock_fortraininglib_cls, mock_openai_cls
+    ):
+        target_units = [
+            TranslationUnit(
+                "Prayer/1", "tr", "Pray for others", "Başkaları için dua et"
+            ),
+            TranslationUnit("Prayer/2", "tr", "Trust God", "Tanrı'ya güven"),
+        ]
+        reference_units = [
+            TranslationUnit("Prayer/1", "de", "Pray for others", "Betet für andere"),
+            TranslationUnit("Prayer/2", "de", "Trust God", "Vertraut Gott"),
+        ]
+
+        mock_lib = MagicMock()
+        mock_fortraininglib_cls.return_value = mock_lib
+        mock_lib.get_translation_units.side_effect = [
+            TranslatedPage("Test", "tr", target_units),
+            TranslatedPage("Test", "de", reference_units),
+        ]
+
+        mock_client = MagicMock()
+        mock_openai_cls.return_value = mock_client
+        mock_client.complete.side_effect = [
+            "Review for unit 1",
+            "Improved translation 1",
+            "Review for unit 2",
+            "Improved translation 2",
+        ]
+
+        bot = TranslationReviewBot(self.config)
+        summary = bot.run("Test", "tr", output_dir=self.temp_dir, with_review=True)
+
+        self.assertEqual(summary.processed, 2)
+        self.assertTrue(summary.with_review)
+        self.assertEqual(mock_client.complete.call_count, 4)
+
+        review_path = os.path.join(self.temp_dir, "review_report.md")
+        with open(review_path, encoding="utf-8") as handle:
+            review_content = handle.read()
+
+        self.assertIn("## Prayer/1", review_content)
+        self.assertIn("Review for unit 1", review_content)
+
+    @patch("pywikitools.translationreview.odt_export.export_suggested_odt")
+    @patch("pywikitools.translationreview.pdf_report.build_pdf_report")
+    @patch("pywikitools.translationreview.bot.OpenAIClient")
+    @patch("pywikitools.translationreview.bot.ForTrainingLib")
+    @patch("pywikitools.translationreview.bot.Family")
+    def test_run_generate_pdf_and_odt(
+        self,
+        mock_family,
+        mock_fortraininglib_cls,
+        mock_openai_cls,
+        mock_build_pdf_report,
+        mock_export_suggested_odt,
+    ):
+        target_units = [
+            TranslationUnit(
+                "Prayer/1", "tr", "Pray for others", "Başkaları için dua et"
+            ),
+        ]
+        reference_units = [
+            TranslationUnit("Prayer/1", "de", "Pray for others", "Betet für andere"),
+        ]
+
+        mock_lib = MagicMock()
+        mock_fortraininglib_cls.return_value = mock_lib
+        mock_lib.get_translation_units.side_effect = [
+            TranslatedPage("Test", "tr", target_units),
+            TranslatedPage("Test", "de", reference_units),
+        ]
+
+        mock_client = MagicMock()
+        mock_openai_cls.return_value = mock_client
+        mock_client.complete.side_effect = [
+            "Improved translation 1",
+        ]
+        mock_export_suggested_odt.return_value = os.path.join(
+            self.temp_dir, "gpt-4o_suggested.odt"
+        )
+
+        bot = TranslationReviewBot(self.config, model="gpt-4o")
+        bot.run("Test", "tr", output_dir=self.temp_dir, generate={"pdf", "odt"})
+
+        mock_build_pdf_report.assert_called_once()
+        self.assertFalse(
+            mock_build_pdf_report.call_args.kwargs.get("include_review", True)
+        )
+        mock_export_suggested_odt.assert_called_once()
 
     @patch("pywikitools.translationreview.bot.OpenAIClient")
     @patch("pywikitools.translationreview.bot.ForTrainingLib")
@@ -258,7 +419,7 @@ def test_run_logs_analysis_and_best_translation(
         with self.assertLogs(
             "pywikitools.translationreview", level=logging.INFO
         ) as log_context:
-            bot.run("Test", "tr", output_dir=self.temp_dir)
+            bot.run("Test", "tr", output_dir=self.temp_dir, with_review=True)
 
         messages = [record.getMessage() for record in log_context.records]
         info_messages = [
@@ -305,7 +466,6 @@ def test_skips_units_without_reference(
         mock_client = MagicMock()
         mock_openai_cls.return_value = mock_client
         mock_client.complete.side_effect = [
-            "Review for unit 1",
             "Improved translation 1",
         ]
 
@@ -315,7 +475,7 @@ def test_skips_units_without_reference(
         self.assertEqual(summary.processed, 1)
         self.assertEqual(summary.skipped, 1)
         self.assertIn("Prayer/2", summary.skipped_units)
-        self.assertEqual(mock_client.complete.call_count, 2)
+        self.assertEqual(mock_client.complete.call_count, 1)
 
     @patch("pywikitools.translationreview.bot.OpenAIClient")
     @patch("pywikitools.translationreview.bot.ForTrainingLib")
@@ -343,13 +503,13 @@ def test_limit_and_unit_filter(
 
         mock_client = MagicMock()
         mock_openai_cls.return_value = mock_client
-        mock_client.complete.side_effect = ["Review", "Best"]
+        mock_client.complete.side_effect = ["Best"]
 
         bot = TranslationReviewBot(self.config)
         summary = bot.run("Test", "tr", unit_id="Prayer/2", output_dir=self.temp_dir)
 
         self.assertEqual(summary.processed, 1)
-        self.assertEqual(mock_client.complete.call_count, 2)
+        self.assertEqual(mock_client.complete.call_count, 1)
 
         with open(
             os.path.join(self.temp_dir, "best_translations.wiki"), encoding="utf-8"
@@ -392,16 +552,14 @@ def test_run_marks_timeout_as_failed_and_writes_reports(
         self.assertEqual(summary.failed_units, ["Prayer/1"])
         mock_client.complete.assert_called_once()
 
-        with open(
-            os.path.join(self.temp_dir, "review_report.md"), encoding="utf-8"
-        ) as handle:
-            review_content = handle.read()
+        self.assertFalse(
+            os.path.isfile(os.path.join(self.temp_dir, "review_report.md"))
+        )
         with open(
             os.path.join(self.temp_dir, "best_translations.wiki"), encoding="utf-8"
         ) as handle:
             best_content = handle.read()
 
-        self.assertIn("TIMEOUT", review_content)
         self.assertIn("=== Prayer/1 ===", best_content)
         self.assertIn("TIMEOUT", best_content)
 
@@ -432,7 +590,7 @@ def test_run_marks_partial_timeout_as_failed(
         mock_client.complete.side_effect = ["Review for unit 1", TIMEOUT_SENTINEL]
 
         bot = TranslationReviewBot(self.config)
-        summary = bot.run("Test", "tr", output_dir=self.temp_dir)
+        summary = bot.run("Test", "tr", output_dir=self.temp_dir, with_review=True)
 
         self.assertEqual(summary.processed, 0)
         self.assertEqual(summary.failed, 1)