dsh-screen-translator

Readme

# 🌐 DSH Screen Translator

[![GitHub License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![DSH Compatibility](https://img.shields.io/badge/dsh->=0.1.2-green.svg)](https://github.com/deepseek-ai/deepseek-harness)
[![Topic](https://img.shields.io/badge/topic-dsh--plugin-orange.svg)](https://github.com/topics/dsh-plugin)

> **Universal on-screen translator for DeepSeek Harness Web UI.**  
> Translates UI text, menus, sidebars, Settings, MCP Connectors, nested iframes, and Shadow DOM elements across **45+ languages** in real time without external API keys or rate limits.

---

## 📖 English | [中文说明](./README_ZH.md)

---

## ✨ Features

- **🌍 45+ Languages Supported** — Instant real-time translation for English, Simplified & Traditional Chinese, Japanese, Korean, Spanish, French, German, Russian, Arabic, and more.
- **⚡ Multi-Endpoint Google Engine** — Automatic failover between `dict-chrome-ex`, `clients5`, `single-at`, and `web-at` APIs to completely prevent `429 Too Many Requests` rate limiting.
- **🔍 Full-Spectrum DOM Coverage**:
  - Visible text nodes and SVG typography (`<text>`, `<tspan>`).
  - Interactive attributes (`placeholder`, `title`, `alt`, `aria-label`, `aria-placeholder`).
  - Open Shadow DOM roots and web components.
  - Same-origin and nested iframes (MCP panels, modals, dialogs).
- **🚀 High Performance & Zero-Lag**:
  - **Dual-Tier Cache** (In-Memory LRU + LocalStorage persistence) — Instant `0ms` rendering for previously translated phrases.
  - **Smart Debounced MutationObserver** — Only newly inserted or altered DOM elements are processed.
  - **Sentence Boundary Splitting** — Natural splitting at punctuation boundaries (`。`, `！`, `？`, `.`, `!`, `?`) preserves contextual readability.
  - **Loop Prevention** — Strict self-exclusion tags (`[data-no-translate]`, code blocks, syntax highlighters) prevent infinite loops.
- **🎛️ Clean Native UI Integration**:
  - Integrated into **Settings → General** with matching native theme tokens.
  - One-click translation actions directly inside assistant conversation turns.
  - Granular controls: **Enable/Disable**, **Target Language selector**, **Translate now**, and **Clear cache**.

---

## 📦 Installation

### Method 1: Via DSH Plugin Manager (Recommended)

In your terminal or DSH session:

```bash
dsh plugin add mustakimabdullah25-tech/dsh-screen-translator
```

### Method 2: Manual Installation from Source

Clone the repository into your DSH plugins directory:

```bash
cd "path/to/dsh-workspace/plugins"
git clone https://github.com/mustakimabdullah25-tech/dsh-screen-translator.git
```

Then install the bundle into your profile:

```bash
dsh plugin add ./plugins/dsh-screen-translator
```

---

## ⚙️ Configuration & Usage

Once installed and enabled:

1. Open **Settings** → **General**.
2. Locate the **Screen Translator (Auto-Translate Everywhere)** section.
3. Choose your preferred **Target Language** from the dropdown.
4. Toggle **Enabled** to start automatic screen translation.
5. Hit **Translate now** to force-translate the entire visible viewport immediately, or **Clear cache** to wipe stored translations.

---

## 🛠️ Architecture

```
┌────────────────────────────────────────────────────────┐
│                   DSH Web Runtime                      │
│                                                        │
│  ┌───────────────────────┐   ┌───────────────────────┐ │
│  │   MutationObserver    │   │      TreeWalker       │ │
│  │ (Watches new DOM/SVG) │   │ (Scans DOM/Shadow/IFR)│ │
│  └───────────┬───────────┘   └───────────┬───────────┘ │
│              │                           │             │
│              ▼                           ▼             │
│       ┌────────────────────────────────────────┐       │
│       │        Language & Token Filter         │       │
│       │  (Filters Code, Math, Regex, Excludes) │       │
│       └──────────────────┬─────────────────────┘       │
│                          │                             │
│                          ▼                             │
│       ┌────────────────────────────────────────┐       │
│       │    Dual Cache (Memory LRU + Storage)   │ ──► Hit (0ms)
│       └──────────────────┬─────────────────────┘       │
│                          │ Miss                        │
│                          ▼                             │
│       ┌────────────────────────────────────────┐       │
│       │      Multi-Endpoint Network Engine     │       │
│       │   (Chrome-Ex ➔ Clients5 ➔ Single-At)   │       │
│       └────────────────────────────────────────┘       │
└────────────────────────────────────────────────────────┘
```

---

## 📁 Repository Structure

```
dsh-screen-translator/
├── client.js          # Client bundle: DOM translation engine, cache & settings UI
├── index.js           # Host entry point (Cordis apply hook)
├── cordis.patch.yml   # Cordis composition patch configuration
├── package.json       # Bundle metadata and plugin contract
├── README.md          # English documentation
├── README_ZH.md       # Chinese documentation
└── LICENSE            # MIT License
```

---

## 🤝 Contributing

Contributions, issues, and feature requests are welcome!  
Feel free to open an issue or submit a pull request on [GitHub](https://github.com/mustakimabdullah25-tech/dsh-screen-translator).

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).