If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/ramjke/Translumo shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 6mo ago
• 11 active contributors
• Apache-2.0 licensed
• CI configured
• ⚠ Slowing — last commit 6mo ago
• ⚠ Concentrated ownership — top contributor handles 68% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live ramjke/Translumo repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ramjke/Translumo.

What it runs against: a local clone of ramjke/Translumo — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in ramjke/Translumo | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 195 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ramjke/Translumo. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ramjke/Translumo.git
#   cd Translumo
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of ramjke/Translumo and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ramjke/Translumo(\\.git)?\\b" \\
  && ok "origin remote is ramjke/Translumo" \\
  || miss "origin remote is not ramjke/Translumo (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/Translumo.Processing/TranslationProcessingService.cs" \\
  && ok "src/Translumo.Processing/TranslationProcessingService.cs" \\
  || miss "missing critical file: src/Translumo.Processing/TranslationProcessingService.cs"
test -f "src/Translumo.OCR/IOCREngine.cs" \\
  && ok "src/Translumo.OCR/IOCREngine.cs" \\
  || miss "missing critical file: src/Translumo.OCR/IOCREngine.cs"
test -f "src/Translumo.Translation/BaseTranslator.cs" \\
  && ok "src/Translumo.Translation/BaseTranslator.cs" \\
  || miss "missing critical file: src/Translumo.Translation/BaseTranslator.cs"
test -f "src/Translumo.Processing/TextProcessing/TextDetectionProvider.cs" \\
  && ok "src/Translumo.Processing/TextProcessing/TextDetectionProvider.cs" \\
  || miss "missing critical file: src/Translumo.Processing/TextProcessing/TextDetectionProvider.cs"
test -f "src/Translumo.Infrastructure/Python/PythonEngineWrapper.cs" \\
  && ok "src/Translumo.Infrastructure/Python/PythonEngineWrapper.cs" \\
  || miss "missing critical file: src/Translumo.Infrastructure/Python/PythonEngineWrapper.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 195 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~165d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/ramjke/Translumo"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Translumo is a real-time screen translator for games and video content that captures on-screen text via OCR and translates it instantly. It combines multiple OCR engines (Windows OCR, Tesseract 5.2, EasyOCR) with a machine learning predictor in src/Translumo.Infrastructure/MachineLearning/MlPredictor.cs to select the highest-confidence recognition result, then pipes it to translation services (DeepL, Google Translate, Yandex, Naver Papago). The core value is low-latency, game-optimized text extraction and translation without modifying game files. Monolithic C# WPF desktop app (Translumo.sln root). Three core project folders: src/Translumo.Infrastructure/ (language descriptors, encryption, Python bridge, ML predictor, dispatcher), src/Translumo.OCR/ (OCR engine abstraction and EasyOCR config), and an unpacked main application layer. Infrastructure provides reusable utilities (LimitedDictionary, AesEncryptionService) and service factories (LanguageDescriptorFactory). OCR is pluggable via IOCREngine interface. Secrets/keys encrypted with AesEncryptionService.

PC gamers playing Japanese/Chinese/Russian games with hardcoded or streamed subtitles, and developers/content creators needing real-time on-screen translation overlays. Users are technically comfortable enough to configure OCR engines and translation API keys, but want minimal manual intervention.

Actively maintained and production-ready: v1.0.2 is the latest stable release with major architecture improvements over 0.9.x versions. The GitHub Actions CI/CD workflow (.github/workflows/PR.check.yml) validates PRs. Single author (ramjke) with consistent commit activity. Code is well-structured across Infrastructure, OCR, and ML modules. Low GitHub stars indicate niche audience, but the tool is feature-complete and battle-tested for real-world gaming scenarios.

Single maintainer (ramjke) is the primary risk for long-term sustainability. External dependencies on Windows OCR API, Tesseract binaries, and cloud translation services (DeepL, Google) mean outages cascade. The src/Translumo.Infrastructure/Python/PythonEngineWrapper.cs wraps Python for ML operations, adding Python runtime as a hard dependency. No test files visible in the top 60, suggesting limited test coverage for critical OCR/ML selection logic. Breaking API changes between 0.9.x and 1.0.x may affect users with custom configurations.

Version 1.0.2 is current stable (released and downloadable). Focus areas inferred from file structure: OCR accuracy via multi-engine scoring (MlPredictor), integration of modern Windows OCR alongside legacy Tesseract/EasyOCR, and translator flexibility (four provider support). Issue templates exist for bugs and feature requests. No visible open PRs or active development branches in the metadata, suggesting release is stable or in quiet maintenance mode.

Clone the repo, open Translumo.sln in Visual Studio 2019+, restore NuGet packages, and build. Binaries (Tesseract, EasyOCR weights) are extracted via binaries_extract.bat before first run. No npm/dotnet CLI mentioned; assume standard Visual Studio workflow: File > Open Solution > Build > Run Translumo.exe from bin folder.

Daily commands:

1. Clone: git clone https://github.com/ramjke/Translumo.git. 2. Open Translumo.sln in Visual Studio. 3. Restore NuGet packages. 4. Run binaries_extract.bat in repo root to unpack OCR engines. 5. Build solution (F7). 6. Run bin/Release/Translumo.exe or press F5 in Visual Studio. Configure translation API keys in settings on first launch.

• src/Translumo.Processing/TranslationProcessingService.cs — Core orchestrator that coordinates screen capture, text detection, translation, and TTS—the main request loop every contributor must understand
• src/Translumo.OCR/IOCREngine.cs — Abstract interface for all OCR engines (Tesseract, EasyOCR, WindowsOCR); critical abstraction point for text detection
• src/Translumo.Translation/BaseTranslator.cs — Base class for all translation providers (DeepL, Google); defines the contract for translation engines
• src/Translumo.Processing/TextProcessing/TextDetectionProvider.cs — Handles text detection coordination, caching, and validation; bridges OCR engines with translation pipeline
• src/Translumo.Infrastructure/Python/PythonEngineWrapper.cs — Wraps Python runtime integration for EasyOCR and Silero TTS; critical for dynamic ML model loading
• src/Translumo.TTS/Engines/ITTSEngine.cs — Abstract interface for text-to-speech engines (Windows, Silero, None); defines audio synthesis contract
• src/Translumo.Infrastructure/Constants/DispatcherActions.cs — Central dispatcher for all application commands (start/stop translation, change settings); foundation of async control flow

Add a New OCR Engine

1. Create a new class implementing IOCREngine in src/Translumo.OCR/ (src/Translumo.OCR/IOCREngine.cs)
2. Implement Detect(Bitmap image, Language language) and Configure(OcrConfiguration config) methods (src/Translumo.OCR/[YourNewEngine]/YourOCREngine.cs)
3. Add configuration class extending OcrGeneralConfiguration (src/Translumo.OCR/Configuration/OcrGeneralConfiguration.cs)
4. Register in OcrEnginesFactory.CreateEngine() switch statement (src/Translumo.OCR/OcrEnginesFactory.cs)
5. Update OcrConfiguration.cs to include your engine type enum (src/Translumo.OCR/Configuration/OcrConfiguration.cs)

Add a New Translation Service

1. Create a new class extending BaseTranslator in src/Translumo.Translation/ (src/Translumo.Translation/BaseTranslator.cs)
2. Implement Translate(string text, Language from, Language to) and GetLanguageCode(Language lang) methods (src/Translumo.Translation/[YourService]/YourTranslator.cs)
3. Add request/response models for your API (src/Translumo.Translation/[YourService]/YourRequest.cs)
4. Update TranslationConfiguration.cs to add your translator enum and API key field (src/Translumo.Translation/Configuration/TranslationConfiguration.cs)
5. Register factory method in main container (check how GoogleContainer and DeeplContainer are structured) (src/Translumo.Translation/Google/GoogleContainer.cs)

Add a New TTS Engine

1. Create a new class implementing ITTSEngine in src/Translumo.TTS/Engines/ (src/Translumo.TTS/Engines/ITTSEngine.cs)
2. Implement Speak(string text, Language language) async method (src/Translumo.TTS/Engines/YourTTSEngine.cs)
3. Add configuration if needed (extend TtsConfiguration) (src/Translumo.TTS/TtsConfiguration.cs)
4. Register in TtsFactory.CreateEngine() switch statement (src/Translumo.TTS/TtsFactory.cs)

Add a New Language Support

1. Add language enum value to Languages.cs (src/Translumo.Infrastructure/Language/Languages.cs)
2. Decorate with [LanguageCode] attribute specifying language codes for each OCR/translation/TTS engine (src/Translumo.Infrastructure/Language/LanguageCodeAttribute.cs)
3. Register language descriptor in LanguageDescriptorFactory (src/Translumo.Infrastructure/Language/LanguageDescriptorFactory.cs)
4. Verify all translator engines support the language code in their GetLanguageCode() methods (src/Translumo.Translation/BaseTranslator.cs)

1. Python runtime required: PythonEngineWrapper expects a Python installation in PATH or configured in Global.cs; missing Python crashes the ML predictor even if OCR succeeds. 2. Tesseract language packs: Tesseract requires separate language data files (*.traineddata) in a specific folder; misconfiguration silently falls back to inferior results. 3. EasyOCR model download: First use of EasyOCR downloads multi-GB models lazily; expect long hangs on first run with EasyOCR enabled. 4. Translation API quota limits: DeepL/Google/Yandex have rate limits and paid tiers; app may silently degrade or fail without warning when limits hit. 5. Windows OCR availability: Windows OCR is only available on Windows 10/11 with language packs installed; code must gracefully degrade on older Windows. 6. Encryption key hardcoding: AesEncryptionService likely uses a hardcoded key visible in source; encryption is for obfuscation, not true security.

• Ensemble OCR (Multi-Engine Scoring) — Translumo's core innovation: running multiple OCR engines in parallel and using ML to pick the best result. Understanding this ensemble pattern is critical to modifying MlPredictor.cs and adding new engines.
• OCR (Optical Character Recognition) — The entire product depends on OCR accuracy. You'll need to understand how engines like Tesseract and EasyOCR differ (traditional heuristics vs. deep learning) to debug recognition failures.
• Language Code Standards (ISO 639-1 / BCP 47) — LanguageCodeAttribute and Languages.cs use language codes to map user selections to OCR engine configs and translator APIs. Mismatches here cause silent failures.
• AES Encryption (Symmetric Cryptography) — AesEncryptionService protects translation API keys at rest. Understanding AES modes and key derivation is important when auditing credential storage.
• Python/C# Interop (P/Invoke and Foreign Function Interfaces) — PythonEngineWrapper bridges C# and Python for ML inference. Understanding marshaling, process lifetimes, and error propagation across language boundaries is essential for debugging ML failures.
• Limited/Circular Buffer Data Structures — LimitedDictionary and LimitedQueue implement bounded caches to reduce memory footprint during real-time screen capture. Understanding eviction policies helps optimize performance.
• REST API Integration & Rate Limiting — Translumo calls DeepL, Google, Yandex, and Naver APIs. Understanding API quotas, auth token formats, and fallback strategies is crucial for supporting multiple translators.

• UB-Mannheim/tesseract — Official Tesseract OCR repository; Translumo bundles v5.2 as a legacy recognition engine.
• JaidedAI/EasyOCR — EasyOCR Python library that Translumo wraps via PythonEngineWrapper for modern deep-learning-based text recognition.
• deepseeker/deepl-py — DeepL's official Python client; Translumo likely uses HTTP bindings to the same API for translation.
• ramjke/Lookupper — Sister project by the same author—on-screen dictionary for language learning with similar screen-capture and overlay architecture.
• ScreenToLayers/Screen2Vec — Alternative open-source screen translation tool; good reference for competing approaches to real-time gaming translation.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for OCR engine abstraction layer

The repo has three OCR implementations (WindowsOCR, Tesseract, EasyOCR) in src/Translumo.OCR but no visible test project. Given the critical nature of OCR accuracy and the abstraction through IOCREngine interface, unit tests for OcrEnginesFactory.cs, ImageHelper.cs, and the preprocessing pipeline in TesseractOCREngineWIthPreprocess.cs and WinOCREngineWithPreprocess.cs would ensure consistency across engine implementations and catch regressions during OCR pipeline changes.

• [ ] Create src/Translumo.OCR.Tests project with xUnit or NUnit
• [ ] Add tests for OcrEnginesFactory.cs covering engine instantiation for all three providers
• [ ] Add tests for ImageHelper.cs image preprocessing edge cases (invalid inputs, format conversions)
• [ ] Add tests comparing preprocessing output consistency between TesseractOCREngineWIthPreprocess and WinOCREngineWithPreprocess
• [ ] Add tests for OcrConfiguration and OcrGeneralConfiguration validation

Add GitHub Actions workflow for binary extraction and artifact management

The repo contains binaries_extract.bat but no CI/CD pipeline to automate this process. A workflow would ensure consistent binary extraction across PRs, validate the extraction script doesn't break, and publish extracted binaries as artifacts. This prevents manual setup friction for contributors and ensures the build process is reproducible.

• [ ] Create .github/workflows/binaries-extract.yml
• [ ] Add workflow step to run binaries_extract.bat on Windows runner
• [ ] Add validation step to verify expected binary output files exist with non-zero size
• [ ] Configure workflow to upload extracted binaries as GitHub Actions artifacts
• [ ] Add workflow to PR.check.yml to run binaries extraction as part of standard PR validation

Implement comprehensive logging/telemetry for Python integration layer

The Python integration (src/Translumo.Infrastructure/Python/) handles PythonEngineWrapper, PythonCommand, and PythonProvider but lacks visible logging infrastructure. Given Python is a critical dependency for OCR engines (EasyOCR, ML models), adding structured logging would help diagnose environment issues, Python initialization failures, and command execution errors. This is especially valuable for PythonAccessException scenarios.

• [ ] Add ILogger dependency injection to PythonEngineWrapper.cs, PythonProvider.cs, and PythonCommand.cs
• [ ] Add logging at key lifecycle points: Python initialization, command execution start/end, error conditions
• [ ] Add logging to PythonAccessException scenarios to capture Python version, installation path, and error details
• [ ] Add configuration option in Global.cs to set Python logging verbosity level
• [ ] Update PythonProvider.cs to log which Python version was detected and from which location

• Add unit tests for src/Translumo.Infrastructure/Collections/LimitedDictionary.cs and LimitedQueue.cs—these are utility classes with no visible test files, making it easy to verify eviction policies and thread-safety without understanding the full OCR pipeline.: Low risk, improves code quality, isolated scope.
• Document configuration options for OcrConfiguration.cs and OcrGeneralConfiguration.cs in a CONFIG.md file—currently unclear which settings control timeout, confidence thresholds, or engine selection order. Map each property to user-facing UI controls.: High value for users, no code changes required, leverages existing config classes.
• Add support for a new language (e.g., Thai, Arabic) by extending src/Translumo.Infrastructure/Language/Languages.cs with language descriptors and testing it against one OCR engine (e.g., Windows OCR). Update LanguageCodeAttribute if needed for the new language code.: Bounded scope, follows existing patterns, demonstrates multi-language architecture without touching ML or encryption logic.

• High · Python Engine Integration - Code Injection Risk — src/Translumo.Infrastructure/Python/PythonEngineWrapper.cs, src/Translumo.Infrastructure/Python/PythonProvider.cs, src/Translumo.Infrastructure/Python/PythonCommand.cs. The codebase integrates with Python through PythonEngineWrapper and PythonProvider. Without proper input validation and sandboxing, there is a risk of arbitrary code execution if user-controlled input is passed to Python commands. The PythonCommand class may be vulnerable to command injection attacks. Fix: Implement strict input validation and sanitization for all Python commands. Use parameterized/escaped commands rather than string concatenation. Consider running Python in a sandboxed environment with restricted permissions. Validate that PythonCommand properly escapes arguments.
• High · Encryption Service - Potential Weak Key Management — src/Translumo.Infrastructure/Encryption/AesEncryptionService.cs. AesEncryptionService is implemented for handling sensitive data encryption. Without visibility into the key storage mechanism, key derivation, and initialization vector (IV) handling, there are potential risks of weak encryption, hardcoded keys, or insecure key storage. Fix: Verify that: 1) Encryption keys are not hardcoded, 2) Keys are stored securely (e.g., Windows Data Protection, Azure Key Vault), 3) Random IVs are generated for each encryption operation, 4) Proper PBKDF2 or similar is used for key derivation, 5) Authentication tags are used (AES-GCM preferred over AES-CBC).
• Medium · OCR Engine External Dependencies — src/Translumo.OCR/EasyOCR/EasyOCREngine.cs, src/Translumo.OCR/Tesseract/TesseractOCREngine.cs, src/Translumo.OCR/WindowsOCR/WindowsOCREngine.cs. Multiple OCR engines are integrated (EasyOCR, Tesseract, WindowsOCR). These engines may rely on external Python libraries or system dependencies that could have unpatched vulnerabilities. The EasyOCR particularly depends on Python ML libraries which may not be regularly updated. Fix: Maintain an inventory of all OCR dependencies and their versions. Implement regular vulnerability scanning using tools like OWASP Dependency-Check or Snyk. Pin dependency versions and regularly review for security updates. Consider using containerization to isolate these dependencies.
• Medium · Limited Input Validation in Text Processing — src/Translumo.Processing/TextProcessing/TextDetectionProvider.cs, src/Translumo.Processing/TextProcessing/TextTokenizer.cs, src/Translumo.Processing/TextProcessing/TextValidityPredictor.cs. TextProcessing pipeline processes OCR output and user input without clearly visible validation. The TextDetectionProvider, TextTokenizer, and related classes may process untrusted input from screen captures without sufficient validation, potentially leading to unexpected behavior or denial of service. Fix: Implement comprehensive input validation for all text processing operations. Set maximum limits on text length, complexity, and processing time. Validate regex patterns in RegexStorage.cs to prevent ReDoS (Regular Expression Denial of Service) attacks.
• Medium · Regex DoS Potential in RegexStorage — src/Translumo.Infrastructure/Constants/RegexStorage.cs. RegexStorage.cs contains regex patterns used throughout the application. Complex or poorly constructed regex patterns can be exploited for Regular Expression Denial of Service (ReDoS) attacks, causing performance degradation or application hangs. Fix: Review all regex patterns for potential ReDoS vulnerabilities. Use regex analysis tools to identify problematic patterns. Implement regex timeout mechanisms. Consider using simpler string matching where possible instead of complex regex patterns.
• Medium · No Visible Rate Limiting on Processing — src/Translumo.Processing/TranslationProcessingService.cs. The TranslationProcessingService processes screen content continuously without visible rate limiting or throttling mechanisms. This could be exploited for resource exhaustion or denial of service attacks. Fix: Implement rate limiting and throttling mechanisms for text processing operations. Add resource usage monitoring and circuit breakers. Implement queue size limits to prevent memory exhaustion.
• Low · Unencrypted — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.