RenLocalizer 🎮✨

Translate any Ren'Py Visual Novel in just a few clicks — without breaking code, formatting, or save files!

Quick Start • Engines • Translation Modes • Why RenLocalizer? • Changelog • Wiki Guide

---

⚡ Quick Start (3 Simple Steps!)

You don't need any programming skills or complex setup to translate your favorite visual novel.

  1. Select Game ────────► 2. Pick Language & Engine ────────► 3. Click Translate & Play!
 (Drop folder / .exe)          (Google, DeepSeek, Local LLM...)          (Launch game & enjoy!)

1. Download & Open: Grab the latest portable version from GitHub Releases and extract it anywhere.
2. Select Game: Click "Browse" (or "EXE") and choose your game's executable or game folder.
3. Pick Language & Translate: Choose your target language, pick an engine (e.g. Google Translate for free & instant, or Local LLM for offline AI), and hit Translate (▶)!

💡 macOS Users: The app is portable. If macOS Gatekeeper says the app is damaged or cannot be opened, open Terminal and run once:

xattr -cr /Applications/RenLocalizer.app

---

🤖 Supported Translation Engines

Pick the engine that best fits your needs — from 100% free cloud translation to private, offline AI models:

Engine	Setup Required	Cost	Best For
🌍 Google Translate	Zero Setup	100% Free	Instant translation, no API keys, built-in 13 mirror rotation.
🪟 Bing / Microsoft Edge	Zero Setup	100% Free	Keyless Microsoft Translator via the Edge web endpoint — independent from Google's rate limits, automatic Google fallback.
🧠 OpenAI (GPT-4o / Mini)	API Key	Paid API	High-accuracy literary translations and nuanced dialogue.
⚡ DeepSeek (V3 / R1)	API Key	Very Low Cost	Outstanding translation quality with OpenAI-compatible API.
💎 Google Gemini	API Key	Free Tier / Paid	High-speed, context-rich translations with large context windows.
🏠 Local LLM (Ollama / LM Studio)	Local App	100% Free	Fully offline, private, uncensored translation (e.g. Llama 3, Qwen 2.5).
📦 Built-in GGUF Runner	Zero Setup	100% Free	Point at a .gguf file and RenLocalizer runs llama.cpp for you — no Ollama or LM Studio install.
🎯 Tencent Hy-MT2	Ollama / LM Studio	100% Free	Specialized translation profile with official model-card sampling recipe.
🐳 LibreTranslate	Self-hosted	Free	Self-hosted local Docker translation service.

---

🎭 Translation Modes (Batch Architecture)

When using AI engines (Cloud API or Local LLM), RenLocalizer offers 3 distinct batching modes:

• 🎭 Scene / Screenplay Mode (Context-Aware — Recommended):
  Presents dialogue lines in a natural theatre screenplay flow with speaker attribution (Alice: "..."). The AI grasps who is speaking to whom, maintaining consistent character tone, gender agreement, and relationship dynamics.
• 📦 Standard Structured Mode (JSON):
  Packages lines into strict key-value pairs ({"id": "text"}). Guarantees zero line drift and high structural integrity. Ideal for menus, settings, and UI strings.
• 📄 Legacy Grouping Mode (XML):
  Wraps texts in <item id="N">...</item> tags. Highly resilient for smaller or older local models (e.g. 3B/7B) that may struggle to format valid JSON.

---

🛡️ Why RenLocalizer?

Translating Ren'Py visual novels with standard translation tools usually crashes the game. Here is why RenLocalizer is different:

• 🔒 SyntaxGuard: Ren'Py codes like {b}, {color=...}, and variables like [player_name] are strictly isolated before translation and safely restored afterwards.
• 🚫 No Duplicate Key Crashes: Automatically tracks existing translations and native IDs, preventing Ren'Py 7.5+ / 8.x duplicate string fatal errors.
• 📦 Deep Binary Scan (.rpyc & .rpa): Extracts hidden strings directly from compiled .rpyc files and unpacks .rpa archives automatically.
• 🌐 Full RTL & BiDi Support: Automatic layout and reading direction (wrtl) handling for Arabic, Persian, Hebrew, and Urdu without altering LTR games.
• ✏️ Translation Editor: Review and hand-fix every line of a game's tl/ folder with search, filters, speaker and context, tag/variable checks and one-line machine suggestions; edits are written back in place and kept by later runs.
• 🧰 Integrated Toolbox: Standalone Ren'Py syntax & indentation linter, automated OpenType font injection, font compatibility scanner, and glossary extractor.
• 🚀 Smart Runtime Hook: Injects a lightweight init -999 python: hook for dynamic on-the-fly string translation and instant language switching in-game.

---

💻 For Power Users & Developers

⌨️ CLI (Command-Line Interface) Mode

RenLocalizer includes a full-featured headless CLI mode powered by rich:

# Quick translation with Google (default)
python run_cli.py "C:\Games\MyVisualNovel\game.exe"

# Translate with DeepSeek to Russian
python run_cli.py "C:\Games\MyVisualNovel\game.exe" -e deepseek -t ru

# Translate with Local LLM (Ollama) with deep scan enabled
python run_cli.py "C:\Games\MyVisualNovel\game.exe" -e local_llm -t de --deep-scan

# Interactive terminal menu mode
python run_cli.py --interactive

🛠️ Running from Source Code

Requires Python 3.10+:

# 1. Clone the repository
git clone https://github.com/Lord0fTurk/RenLocalizer.git
cd RenLocalizer

# 2. Create and activate a virtual environment
python -m venv .venv

# Windows:
.venv\Scripts\activate
# Linux / macOS:
source .venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Launch the application
python run.py

🔬 Technical Specifications & Protection Pipeline

• Placeholder Protection Modes:
  • Google (Token Mode): Unicode mathematical brackets ⟦RLPH{hex}_{N}⟧ (treated as invariant punctuation by Google Translate).
  • AI/LLM (XML & Token Modes): <ph id="N">...</ph> and __PH_N__ wrappers preventing subword tokenizer fragmentation.
  • 6-Stage Restoration: Unicode brackets ➔ bracket-stripped ➔ transliteration repair ➔ generic recovery ➔ wrapper pair ➔ tag repair.
• Integrity Validation: If an AI model hallucinate or leaks tags, the string is flagged as corrupted and safely reverted to original text to prevent game crashes.
• Runtime Hook: zzz_renlocalizer_runtime.rpy features an $O(1)$ dictionary lookup, MRU cache (500 entries), and screen harvesting.

---

🤝 Contributing & Community

Contributions, bug reports, and feature requests are very welcome!

• 🐛 Report a Bug: Open an issue on GitHub Issues
• 📖 Documentation: Visit the Wiki Guide
• 💖 Support Development: Join us on Patreon
• 📜 License: Released under the GNU General Public License v3.0

---

📦 Third-Party Components

RenLocalizer builds on the work of these open-source projects:

Project	License	Used for
llama.cpp	MIT	Built-in GGUF runner — the official llama-server build is downloaded on request (verified by SHA256) and managed by RenLocalizer; it is not bundled with the release.
PyQt6 / Qt	GPL-3.0 / LGPL-3.0	Desktop interface (QML)
Lucide	ISC	Interface icons — a subset of the Lucide icon font ships in src/gui/qml/fonts/ together with its license (LUCIDE_LICENSE.txt).
unrpa	GPL-3.0	.rpa archive extraction
rpycdec	MIT	Complementary .rpyc decompilation
rich	MIT	CLI interface

Translation engines are used through their public endpoints or official SDKs (Google Translate, Microsoft Translator via the Edge endpoint, DeepL, LibreTranslate, OpenAI, Google Gemini, DeepSeek).