@hkonda/loco-translate 1.0.0

package/README.md

@@ -0,0 +1,284 @@
+<p align="center">
+  <img src="assets/loco_animated.svg" alt="Loco Logo" width="500" />
+</p>
+
+# Loco
+
+Open-source translation engine for any website or app. Drop in a single `<script>` tag, manage translations from a dashboard, and let AI handle the heavy lifting.
+
+Two integration modes: **Server Mode** (live API-driven) and **File Mode** (static JSON, zero server dependency).
+
+---
+
+## Getting Started (First-Time Setup)
+
+### 1. Install & Start the Dashboard
+
+```bash
+git clone https://github.mieweb.com/hkonda/loco.git
+cd loco
+npm install
+npm run dev
+```
+
+This starts two processes:
+- **Vite dev server** on port `6100` (dashboard + proxy)
+- **Fastify API** on port `6101` (backend)
+
+On startup the terminal prints your working URLs:
+
+```
+  🌐 Loco Translation Manager
+
+  Dashboard : http://<your-ip>:6100/loco/dashboard/
+  CDN script: http://<your-ip>:6100/loco/cdn/loco.js
+  API key   : <auto-generated>
+
+  Paste into any page:
+
+  <script src="http://<your-ip>:6100/loco/cdn/loco.js"></script>
+  <script>Loco.init({ apiUrl: 'http://<your-ip>:6100/loco', apiKey: '<your-key>' });</script>
+```
+
+Open the **Dashboard** URL in your browser. You should see the Translation Manager with Pending / Approved / Trash tabs.
+
+### 2. Add the CDN Snippet to Your Page
+
+Copy the snippet from the terminal output (or from **Dashboard → Settings → CDN Script Snippet**) and paste it into any HTML page you want to translate. When that page loads in a browser, Loco automatically discovers text nodes and sends them to the dashboard as "Pending" items.
+
+### 3. Install the Chrome Extension (Optional)
+
+The Chrome extension adds a side panel for in-context translation editing on any page running the Loco snippet.
+
+1. Open Chrome and go to `chrome://extensions/`
+2. Enable **Developer mode** (toggle in the top-right corner)
+3. Click **Load unpacked**
+4. Select the `chrome-extension/` folder inside this repo
+5. The **Loco Translation Editor** extension should appear in your extensions list
+
+#### Configure the Extension
+
+1. Click the Loco extension icon in the Chrome toolbar → **Options** (or right-click → Extension options)
+2. Fill in the two fields:
+   - **API Base URL** — the same base URL from the snippet, e.g. `http://<your-ip>:6100/loco`
+   - **API Key** — the API key from **Dashboard → Settings**
+3. Click **Save Settings**, then **Test Connection** to verify it works
+4. Navigate to any page running the Loco snippet, then click the extension icon to open the side panel
+
+### 4. Test Pages
+
+Several test pages are included and served during development:
+
+| Page | URL |
+|---|---|
+| Server Mode Test | `http://<your-ip>:6100/loco/dashboard/test-server-mode.html` |
+| File Mode Test | `http://<your-ip>:6100/loco/dashboard/test-file-mode.html` |
+| Pattern Test | `http://<your-ip>:6100/loco/dashboard/test-patterns.html` |
+| Basic Test | `http://<your-ip>:6100/loco/dashboard/test-page.html` |
+
+Open any server-mode test page — text nodes should appear in the dashboard under **Pending** within a few seconds.
+
+### 5. Configure BlueHive AI (for AI Translations)
+
+To use AI-powered translations, you need a BlueHive API key:
+
+1. Go to **Dashboard → Settings**
+2. Under **BlueHive API Key**, paste your key (starts with `BHSK-...`)
+3. Click **Save**
+
+If you don't have a key, sign up at [bluehive.com](https://bluehive.com) and generate one from your developer account.
+
+### 6. Translation Workflow
+
+1. **Pending** — Newly discovered text appears here. Review and approve items you want to translate.
+2. **Approved** — Approved phrases are ready for translation. Use **AI Translate** to batch-translate with BlueHive, or edit translations manually.
+3. **Export** — From the Approved tab, click **Export JSON** to download a translation file for File Mode.
+4. **Apply** — On any page with the Loco snippet, call `Loco.apply('zh-CN')` in the browser console to see translations live.
+
+---
+
+## Self-Hosting (Production)
+
+### Prerequisites
+
+- Node.js 20+
+- npm
+- Linux server with systemd (for production deployment)
+
+### Build & Run
+
+```bash
+git clone https://github.mieweb.com/hkonda/loco.git
+cd loco
+npm install
+npm run build
+npm start
+```
+
+Dashboard available at `http://<your-ip>:6101/dashboard/`
+
+An API key is auto-generated on first run — find it in the dashboard under Settings.
+
+To enable AI translations, add your BlueHive API key in the dashboard under **Settings > BlueHive API Key**.
+
+### Deploy with systemd
+
+The included `deploy.sh` handles everything:
+
+```bash
+chmod +x deploy.sh
+
+./deploy.sh install    # Build + install systemd service + start
+./deploy.sh stop       # Stop service
+./deploy.sh start      # Start service
+./deploy.sh restart    # Restart service
+./deploy.sh status     # Show status + recent logs
+./deploy.sh logs       # Tail live logs
+./deploy.sh uninstall  # Stop + remove service
+```
+
+After `install`, the script prints your dashboard URL and CDN script URL.
+
+---
+
+## Using Loco in Your App
+
+### Server Mode
+
+Server mode connects your site to a running Loco instance. It automatically discovers text on the page, sends it to the server for management, and applies translations in real-time.
+
+```html
+<script src="https://your-loco-server.com/cdn/loco.js"></script>
+<script>
+  Loco.init({
+    apiUrl: 'https://your-loco-server.com',
+    apiKey: 'YOUR_API_KEY'
+  });
+
+  // Apply a language
+  Loco.apply('fr');
+</script>
+```
+
+**What happens:**
+
+1. `loco.js` scans the DOM and extracts all translatable text nodes
+2. Text nodes are sent to the Loco server and appear in the dashboard as "pending"
+3. You approve phrases, add languages, and translate (manually or with AI) in the dashboard
+4. `Loco.apply('fr')` fetches approved translations from the server and swaps text in the DOM
+5. A `MutationObserver` watches for new DOM nodes and registers them automatically
+
+### File Mode
+
+File mode uses a static JSON file — no server connection needed. Export the JSON from the dashboard or create it by hand.
+
+```html
+<script src="/path/to/loco.js"></script>
+<script>
+  Loco.init({ file: '/translations.json' });
+
+  // Apply a language
+  Loco.apply('zh-CN');
+
+  // Optional: render a floating language switcher widget
+  Loco.widget({ position: 'bottom-right' });
+</script>
+```
+
+**Translation JSON format:**
+
+```json
+{
+  "languages": ["fr", "zh-CN"],
+  "translations": {
+    "fr": {
+      "Hello": "Bonjour",
+      "Sign up": "S'inscrire",
+      "Welcome back, {{var:0}}": "Bon retour, {{var:0}}"
+    },
+    "zh-CN": {
+      "Hello": "你好",
+      "Sign up": "注册",
+      "Welcome back, {{var:0}}": "欢迎回来，{{var:0}}"
+    }
+  }
+}
+```
+
+You can export this file from the dashboard at any time (Translations → Export JSON).
+
+### Client API
+
+```javascript
+Loco.init(config)          // Initialize (server mode or file mode)
+Loco.apply('fr')           // Apply translations for a language → Promise
+Loco.restore()             // Revert all text to original
+Loco.rescan()              // Re-scan DOM for new text nodes
+Loco.widget({ position })  // Render language switcher ('bottom-right', 'bottom-left', 'top-right', 'top-left')
+Loco.textnodes()           // Get all discovered text nodes
+Loco.stopScan()            // Pause MutationObserver
+Loco.startScan()           // Resume MutationObserver
+```
+
+### Variable Handling
+
+Loco automatically detects dynamic values in text and preserves them across translations:
+
+```
+Original:  "You have 5 new messages"
+Key:       "You have {{var:0}} new messages"
+French:    "Vous avez {{var:0}} nouveaux messages"
+Rendered:  "Vous avez 5 nouveaux messages"
+```
+
+---
+
+## Architecture
+
+```mermaid
+flowchart TB
+    subgraph Your Website or App
+        A[loco.js Client Script]
+    end
+
+    subgraph Loco Server
+        B[Fastify API]
+        C[SQLite Database]
+        D[AI Translation Jobs]
+        E[Dashboard SPA]
+    end
+
+    subgraph External
+        F[BlueHive AI API]
+    end
+
+    A -->|Register text nodes & screenshots| B
+    A -->|Fetch translations| B
+    B <--> C
+    E -->|Manage phrases & languages & prompts| B
+    B -->|Queue translation jobs| D
+    D -->|Send text & context| F
+    F -->|Return translations| D
+    D -->|Store results| C
+```
+
+### How It Works
+
+1. **Discover** — The client script scans your page, extracts text nodes (respecting blocked/inline tag rules), and sends them to the server along with page context and screenshots
+2. **Manage** — In the dashboard, review pending phrases, approve them, add target languages, and configure AI prompt templates
+3. **Translate** — Run AI translation jobs that use page screenshots and context for accurate results, or edit translations manually
+4. **Deliver** — The client fetches approved translations and swaps DOM text in real-time. Or export a static JSON file for file mode
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Client Script | Vanilla JavaScript (no dependencies) |
+| Dashboard | Svelte 4 + Tailwind CSS |
+| Server | Fastify + Node.js |
+| Database | SQLite (better-sqlite3, WAL mode) |
+| Build Tool | Vite |
+| AI | BlueHive API |
+| Deployment | systemd + deploy.sh |

package/bin/loco.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// Loco Translation Manager — CLI entry point
+// Usage: npx loco-translate  OR  loco  (if installed globally)
+
+import '../dist-server/index.js';