Emebala Documentation

01 Overview & Philosophy

In ancient Sumer around 2000 BCE, translators bridging diverse dialects, cuneiform clay tablets, and trade languages were revered as Eme-bala (literally: "those who turn language to bridge worlds"). Modern digital tools, however, have increasingly compromised individual liberty by routing confidential communications and literary manuscripts through remote corporate cloud servers.

Team Sunplaza engineered the Emebala ecosystem to restore absolute sovereignty to the reader and writer: C++20 powers the ultra-low-latency Windows desktop flagship (Emebala Chat), and every application executes its AI models directly on your own hardware.

• Emebala Chat (C++20 Desktop Flagship): Native Win32 / Direct2D client powered by an embedded llama.cpp runtime executing quantized GGUF weights (Hy-MT2-1.8B-Q8_0.gguf). Intercepts input buffers in any application to replace what you typed in-place, accompanied by double-Ctrl+C drag-to-translate and zero-latency Windows Speech Platform audio.
• Emebala Reader (In Development): Windows reading sanctuary for EPUB and PDF with on-device translation powered by the HY-MT1.5-1.8B GGUF model. Every page is processed locally, and nothing leaves your computer.

02 Quickstart Installation

Both Emebala Chat and Emebala Reader are distributed as self-contained standalone Windows applications. Emebala Chat installs like a standard Windows application: your configuration file (%LOCALAPPDATA%\Emebalachat\config.json) and the shared AI model (%LOCALAPPDATA%\Emebala\Common\models\) live in your own user profile, and no account, sign-in, or telemetry of any kind is required.

Obtain the latest setup binary from the GitHub release distribution:

Get-FileHash .\Emebalachat_Setup_0.10.2.exe -Algorithm SHA256

03 System Requirements

04 In-Place Send-and-Replace Mechanics

In Emebalachat/src/hook.hpp, Emebala Chat implements a revolutionary keystroke replacement workflow: you simply type naturally in your native tongue inside Slack, Discord, WeChat, Teams, WhatsApp, or any browser input, and press the key you normally press to send messages.

05 Floating Rosetta Badge & Drag Gestures

Emebala Chat renders a lightweight hardware-accelerated Direct2D badge widget directly on the screen (Emebalachat/src/ui/badge.cpp):

• Single Left-Click: Toggles engine between Active and Paused translation state.
• Double-Click: Instantly swaps source and target translation direction (e.g. English ↔ Korean).
• Click & Drag: Freely repositions the floating status pill anywhere across single or multi-monitor desktop setups. Coordinates persist in badge_x and badge_y.
• Double Ctrl + C Trigger ("double_ctrl_c"): Highlighting any text on screen and pressing Ctrl+C twice quickly summons the Floating Translation Tooltip right at your cursor.

06 Windows Speech Platform (Chat TTS)

In Emebala Chat (src/sound.cpp), speech synthesis is powered directly by the native Windows Speech Platform (Windows 내장 언어팩) through the ISpVoice COM interface and WinRT Windows.Media.SpeechSynthesis.

07 Low-Level Keyboard Hook Safety Model

Emebala Chat's keyboard hook architecture (src/hook.cpp) was engineered under stringent safety constraints:

• LowLevelHooksTimeout Prevention (REQ-R06): The hook callback performs zero blocking I/O, zero network calls, and zero model inference on the hook thread. Heavy workloads are dispatched asynchronously to a dedicated pipeline worker thread (src/worker.cpp).
• Zero Cloud Clipboard Leakage: When capturing and restoring text selections, the Windows flag CanIncludeInClipboardHistory = 0 is applied, preventing transient translation strings from polluting Windows 10/11 cloud clipboard synchronization history.
• Zero Telemetry Logging: Keystrokes that are not the intercepted action keys are never logged, buffered, or stored to disk.

08 Emebala Reader: Reading Experience

Emebala Reader, currently in active development, delivers a Windows sanctuary for long-form literature and scholarship:

• EPUB & PDF Import: Open standard EPUB and PDF books in a focused, distraction-free reading environment.
• Continuous-Scroll Reading: The current build presents books in a fast continuous scroll, optimized for skimming, reference reading, and long chapters.
• On-Device Translation: Page translation runs through the HY-MT1.5-1.8B GGUF model entirely on your own hardware — no page, paragraph, or note ever leaves your computer.

09 Hy-MT2 33 World Languages Specification

The core translation engine supports 33 World Languages (1,056 bidirectional translation pairs) organized across five major geographical and linguistic families:

10 5 Regional Dialects & Indigenous Heritages

Beyond the 33 major world languages, Emebala safeguards 5 regional dialects and indigenous tongues often neglected by commercial translation cloud providers:

11 On-Device Inference Architecture (GGUF)

Emebala tailors its neural execution layer to the operational demands of each application:

Emebala Chat embeds llama.cpp directly via CMake FetchContent. It executes quantized GGUF weights (models/Hy-MT2-1.8B-Q8_0.gguf) with hardware acceleration:

• Zero Dynamic Allocations during Translation: The context and KV cache are pinned in memory for instantaneous keystroke response (~40ms).
• WinHTTP Cloud Fallback Client (src/google_translate.cpp): When cloud_fallback_enabled: true is explicitly configured by the user, Chat includes a native WinHTTP client for fallback translation. When false (default), zero external traffic is ever permitted.

Emebala Reader is a Windows application in active development. Its translation engine runs entirely on your own hardware:

• HY-MT1.5-1.8B GGUF (hy-mt1.5-1.8b.gguf): The quantized Tencent HY-MT1.5 translation model executes fully offline — no page, paragraph, or reading note ever leaves your computer.

12 Zero-Telemetry Verification Protocol

Verify Emebala's zero-cloud guarantee using your preferred network monitoring tool (Wireshark, Fiddler, or Windows Resource Monitor):

Get-NetTCPConnection | Where-Object { (Get-Process -Id $_.OwningProcess -ErrorAction SilentlyContinue).ProcessName -like "*Emebala*" }

The output is completely empty. No outbound socket connects, no telemetry pings, and no background analytics ever leave your device.

13 Global Hotkeys & Keyboard Shortcuts Matrix

The definitive shortcuts verified directly against Emebalachat/src/hook.hpp and src/config.hpp:

14 Emebala Chat config.json Schema

The canonical configuration file is %LOCALAPPDATA%\Emebalachat\config.json (on first launch, missing keys fall back to compiled-in defaults, and a legacy config found next to the executable is migrated once). Below is the verbatim default template shipped in the v0.10.2 repository (config.example.json, 25 keys):

{
  "ui_language": "auto",
  "engine_type": "auto",
  "model_path": "models/Hy-MT2-1.8B-Q8_0.gguf",
  "source_language": "Auto Detect",
  "target_language": "English",
  "auto_send": false,
  "sound_enabled": true,
  "drag_to_translate": true,
  "cloud_fallback_enabled": false,
  "engine_host": { "enabled": true, "spawn": true, "idle_exit_ms": 600000 },
  "openai": { "base_url": "", "model": "", "api_key_dpapi": "", "api_key_sha256": "", "http_consent_given": false },
  "_openai_doc": "OpenAI Compatible cloud engine (engine_type: \"openai\"). base_url/model are user-supplied; api_key_dpapi is the Windows-encrypted (DPAPI) API key and api_key_sha256 its integrity digest - both are written by the in-app settings dialog, never enter the key by hand in cleartext. http_consent_given records the explicit consent the app requires before sending your key to a plaintext http:// endpoint. The app serializes this block unconditionally, so an untouched round trip writes it back as the empty defaults above.",
  "diag_log_enabled": false,
  "_diag_log_enabled_doc": "MASTER switch for the diagnostic log file. Default false: the app never creates a log file (privacy-by-default release posture). Set true (and restart) to write logs to %LOCALAPPDATA%\\Emebalachat\\logs\\ for debugging; the whole logs folder is capped at 200MB (oldest files pruned at startup). Only enable while actively troubleshooting.",
  "diag_log_content": false,
  "_diag_log_content_doc": "Only has an effect when diag_log_enabled is true. Logs are shape-only by default (key codes, window class, lengths, timings). Set true to ALSO record user content: typed characters, foreground window titles, captured text and translation output. Privacy decision: only enable while actively troubleshooting, and restart the app after changing this value.",
  "privacy_notice_shown": false,
  "_privacy_notice_shown_doc": "One-shot privacy notice record (app-managed). Set false (or delete the key) to see the first-run privacy popup again on the next start: the popup is blocking and no translation is served until it is dismissed. The app sets this to true before showing the popup, so it appears exactly once per install; full privacy details live in README.md.",
  "drag_hotkey": "double_ctrl_c",
  "hotkey_toggle": "F9",
  "hotkey_lang": "Ctrl+F9",
  "hotkey_mode": "Ctrl+Shift+Enter",
  "_hotkeys_doc": "hotkey_toggle/lang/mode accept 'Mod+Key' (Ctrl/Shift/Alt/Win + F1-F24, Enter, Esc, Tab, Space, arrows, A-Z, 0-9). Invalid values fall back to defaults. drag_hotkey supports only 'double_ctrl_c'. Overlapping combos fire one action in order: toggle > lang > mode.",
  "user_model_id": "",
  "_user_model_id_doc": "Registry id of the .gguf model you registered yourself (tray > Translation engine > User-selected (.gguf)); engine_type \"user_gguf\" serves it through the shared engine host. Written by the app; leave empty unless you know the registered id.",
  "temperature": 0.0,
  "top_p": 0.6,
  "top_k": 20,
  "repetition_penalty": 1.05,
  "badge_x": -1,
  "badge_y": -1
}

15 Troubleshooting & Frequently Asked Questions

Windows User Interface Privilege Isolation (UIPI) restricts standard user applications from sending synthetic keyboard events to elevated processes. If you wish to translate inside elevated terminals, run Emebala Chat as Administrator.

Navigate to Windows Settings > Time & Language > Speech > Manage Voices > Add voices. Install your preferred language pack. Emebala Chat's COM enumerator detects new voices immediately without requiring a restart.

Exit the application via the system tray, then uninstall it from Windows Settings > Apps. The uninstaller removes the program along with your per-user configuration (%LOCALAPPDATA%\Emebalachat\). The shared AI model and engine under %LOCALAPPDATA%\Emebala\Common\ are preserved while any other Emebala app remains installed; when you remove the last one, the uninstaller asks before deleting them.