Feature: translation cache

docs/source/translation.rst

@@ -13,6 +13,41 @@ Limitations
 - If probes or detectors fail to load, you need may need to choose a smaller local translation model or utilize a remote service.
 - Translation may add significant execution time to the run depending on resources available.
 
+Translation Caching
+------------------
+
+Garak implements a translation caching system to improve performance and reduce API costs when using translation services. The caching mechanism automatically stores and retrieves translation results to avoid redundant API calls.
+
+**How it works:**
+
+- Each translation pair (source language → target language) gets its own cache file
+- Cache files are stored in JSON format under the cache directory: ``{cache_dir}/translation/translation_cache_{source_lang}_{target_lang}_{model_type}_{model_name}.json``
+- Translation results are keyed by MD5 hash of the input text for efficient storage and retrieval
+- Cache files persist between runs, allowing translations to be reused across multiple garak sessions
+
+**Benefits:**
+
+- **Performance**: Significantly reduces translation time for repeated text
+- **Cost savings**: Reduces API calls to paid services like DeepL, Google Cloud Translation, and NVIDIA Riva
+- **Reliability**: Provides fallback for offline scenarios when cached translations are available
+- **Consistency**: Ensures identical translations for the same input text across different runs
+
+**Cache management:**
+
+- Cache files are automatically created when translations are performed
+- Corrupted cache files are handled gracefully with fallback to empty cache
+- Cache files can be manually deleted to force fresh translations
+- Cache directory location follows garak's standard cache configuration
+
+**Supported for all translation services:**
+
+- Local translation models (Hugging Face)
+- DeepL API
+- NVIDIA Riva API  
+- Google Cloud Translation API
+
+The caching system is transparent to users and requires no additional configuration. It automatically activates when translation services are used.
+
 Supported translation services
 ------------------------------
 

garak/langproviders/base.py

@@ -10,8 +10,13 @@
 import unicodedata
 import string
 import logging
+import json
+import hashlib
+import os
+from pathlib import Path
 from garak.resources.api import nltk
 from langdetect import detect, DetectorFactory, LangDetectException
+from garak import _config
 
 _intialized_words = False
 
@@ -128,14 +133,94 @@ def is_meaning_string(text: str) -> bool:
 # To be `Configurable` the root object must meet the standard type search criteria
 # { langproviders:
 #     "local": { # model_type
-#       "language": "<from>-<to>"
+#       "language": "<from>,<to>"
 #       "name": "model/name" # model_name
 #       "hf_args": {} # or any other translator specific values for the model_type
 #     }
 # }
 from garak.configurable import Configurable
 
 
+class TranslationCache:
+    def __init__(self, provider: "LangProvider"):
+        if not hasattr(provider, "model_type"):
+            return None  # providers without a model_type do not have a cache
+
+        self.source_lang = provider.source_lang
+        self.target_lang = provider.target_lang
+        self.model_type = provider.model_type
+        self.model_name = "default"
+        if hasattr(provider, "model_name"):
+            self.model_name = provider.model_name
+
+        cache_dir = _config.transient.cache_dir / "translation"
+        cache_dir.mkdir(mode=0o740, parents=True, exist_ok=True)
+        cache_filename = f"translation_cache_{self.source_lang}_{self.target_lang}_{self.model_type}_{self.model_name.replace('/', '_')}.json"
+        self.cache_file = cache_dir / cache_filename
+        logging.info(f"Cache file: {self.cache_file}")
+        self._cache = self._load_cache()
+
+    def _load_cache(self) -> dict:
+        if self.cache_file.exists():
+            try:
+                with open(self.cache_file, "r", encoding="utf-8") as f:
+                    return json.load(f)
+            except (json.JSONDecodeError, IOError) as e:
+                logging.warning(f"Failed to load translation cache: {e}")
+                return {}
+        return {}
+
+    def _save_cache(self):
+        try:
+            with open(self.cache_file, "w", encoding="utf-8") as f:
+                json.dump(self._cache, f, ensure_ascii=False, indent=2)
+        except IOError as e:
+            logging.warning(f"Failed to save translation cache: {e}")
+
+    def get_cache_key(self, text: str) -> str:
+        return hashlib.md5(text.encode("utf-8"), usedforsecurity=False).hexdigest()
+
+    def get(self, text: str) -> str | None:
+        cache_key = self.get_cache_key(text)
+        cache_entry = self._cache.get(cache_key)
+        if cache_entry and isinstance(cache_entry, dict):
+            return cache_entry.get("translation")
+        elif isinstance(cache_entry, str):
+            # Backward compatibility with old format
+            return cache_entry
+        return None
+
+    def set(self, text: str, translation: str):
+        cache_key = self.get_cache_key(text)
+        self._cache[cache_key] = {
+            "original": text,
+            "translation": translation,
+            "source_lang": self.source_lang,
+            "target_lang": self.target_lang,
+            "model_type": self.model_type,
+            "model_name": self.model_name,
+        }
+        self._save_cache()
+
+    def get_cache_entry(self, text: str) -> dict | None:
+        """Get full cache entry including original text and metadata."""
+        cache_key = self.get_cache_key(text)
+        cache_entry = self._cache.get(cache_key)
+        if cache_entry and isinstance(cache_entry, dict):
+            return cache_entry
+        elif isinstance(cache_entry, str):
+            # Backward compatibility with old format
+            return {
+                "original": text,
+                "translation": cache_entry,
+                "source_lang": self.source_lang,
+                "target_lang": self.target_lang,
+                "model_type": self.model_type,
+                "model_name": self.model_name,
+            }
+        return None
+
+
 class LangProvider(Configurable):
     """Base class for objects that provision language"""
 
@@ -147,6 +232,9 @@ def __init__(self, config_root: dict = {}) -> None:
 
         self._validate_env_var()
 
+        # Use TranslationCache for caching
+        self.cache = TranslationCache(self)
+
         self._load_langprovider()
 
     def _load_langprovider(self):
@@ -155,6 +243,16 @@ def _load_langprovider(self):
     def _translate(self, text: str) -> str:
         raise NotImplementedError
 
+    def _translate_with_cache(self, text: str) -> str:
+        """Translate text with caching support."""
+        cached_translation = self.cache.get(text)
+        if cached_translation is not None:
+            logging.debug(f"Using cached translation for text: {text[:50]}...")
+            return cached_translation
+        translation = self._translate_impl(text)
+        self.cache.set(text, translation)
+        return translation
+
     def _get_response(self, input_text: str):
         translated_lines = []
 
@@ -189,7 +287,7 @@ def _short_sentence_translate(self, line: str) -> str:
         if needs_translation:
             cleaned_line = self._clean_line(line)
             if cleaned_line:
-                translated_line = self._translate(cleaned_line)
+                translated_line = self._translate_with_cache(cleaned_line)
                 translated_lines.append(translated_line)
 
         return translated_lines
@@ -202,7 +300,7 @@ def _long_sentence_translate(self, line: str) -> str:
             if self._should_skip_line(cleaned_sentence):
                 translated_lines.append(cleaned_sentence)
                 continue
-            translated_line = self._translate(cleaned_sentence)
+            translated_line = self._translate_with_cache(cleaned_sentence)
             translated_lines.append(translated_line)
 
         return translated_lines

garak/langproviders/local.py

@@ -19,6 +19,7 @@ def _load_langprovider(self):
         pass
 
     def _translate(self, text: str) -> str:
+        # Use _translate_with_cache to enable caching
         return text
 
     def get_text(
@@ -110,6 +111,11 @@ def _load_langprovider(self):
             self.tokenizer = MarianTokenizer.from_pretrained(model_name)
 
     def _translate(self, text: str) -> str:
+        # Use _translate_with_cache to enable caching
+        return self._translate_with_cache(text)
+
+    def _translate_impl(self, text: str) -> str:
+        """Actual translation implementation without caching."""
         if "m2m100" in self.model_name:
             self.tokenizer.src_lang = self.source_lang
 

garak/langproviders/remote.py

@@ -91,6 +91,11 @@ def _load_langprovider(self):
 
     # TODO: consider adding a backoff here and determining if a connection needs to be re-established
     def _translate(self, text: str) -> str:
+        # Use _translate_with_cache to enable caching
+        return self._translate_with_cache(text)
+
+    def _translate_impl(self, text: str) -> str:
+        """Actual translation implementation without caching."""
         try:
             if self.client is None:
                 self._load_langprovider()
@@ -152,6 +157,11 @@ def _load_langprovider(self):
             self._tested = True
 
     def _translate(self, text: str) -> str:
+        # Use _translate_with_cache to enable caching
+        return self._translate_with_cache(text)
+
+    def _translate_impl(self, text: str) -> str:
+        """Actual translation implementation without caching."""
         try:
             return self.client.translate_text(
                 text, source_lang=self._source_lang, target_lang=self._target_lang
@@ -230,6 +240,11 @@ def _load_langprovider(self):
             self._tested = True
 
     def _translate(self, text: str) -> str:
+        # Use _translate_with_cache to enable caching
+        return self._translate_with_cache(text)
+
+    def _translate_impl(self, text: str) -> str:
+        """Actual translation implementation without caching."""
         retry = 5
         while retry > 0:
             try: