i18n-dashboard 0.12.1 → 0.13.0

package/README.md

@@ -1,779 +1,96 @@
-# i18n-dashboard
+# Vue i18n Dashboard
 
-> A full-featured web dashboard to manage [vue-i18n](https://vue-i18n.intlify.dev/) translation keys. Run it alongside your project, manage all your translations in one place, and consume them via a ready-to-use API.
+Stop editing JSON files manually.
 
-[![npm version](https://img.shields.io/npm/v/i18n-dashboard)](https://www.npmjs.com/package/i18n-dashboard)
-[![license](https://img.shields.io/npm/l/i18n-dashboard)](./LICENSE)
-[![node](https://img.shields.io/node/v/i18n-dashboard)](https://nodejs.org/)
+Manage your Vue i18n translations in a real-time dashboard — with two possible workflows:
+- Local (per project)
+- Server (multi-project platform)
 
 ---
 
-## Features
-
-### Core
-- **Multi-project** — manage multiple Vue.js projects from one dashboard, each with its own languages, keys, and settings
-- **Translation editor** — inline editing per language, keyboard shortcuts (`Ctrl+Enter` to save, `Esc` to cancel)
-- **Plural forms** — dedicated plural editor supporting 2-form (EN/DE), 3-form (FR/ES), 4-form (Slavic), or custom rules
-- **Key linking** — insert `@:key` linked references with optional modifiers (`.lower`, `.upper`, `.capitalize`) via a searchable modal picker
-- **Escape helpers** — quick-insert toolbar for vue-i18n special characters (`{'@'}`, `{'{'}`, `\\{`, etc.)
-- **Translation history** — every change (manual, sync, auto-translate) is tracked; restore any previous version
-- **Inline auto-translate** — Google Translate per key (free tier, no API key required)
-- **Batch auto-translate** — translate all missing keys for an entire language at once
-- **Review workflow** — `Draft → Reviewed → Approved` status pipeline with role-based access control
-- **Dashboard widgets** — customizable overview: coverage, total keys, unused keys, recent activity, per-language progress
-
-### Languages
-- **BCP 47 support** — full regional codes: `fr-CA`, `en-GB`, `pt-BR`, `zh-CN`, `sr-Latn`, etc. (170+ locales)
-- **Fallback chains** — configure explicit fallbacks per language (`fr-CA → fr → en`); automatic BCP 47 parent resolution
-- **Auto-detect** — scan or sync automatically detects locale files and creates the corresponding languages
-- **Default language** — designate one language as the source for auto-translate
-
-### Scan & Sync
-- **Source scan (local)** — browse your file system with the built-in folder picker, detect all `$t()`, `t()`, `<i18n-t>`, `v-t`, and `<i18n>` block usages across `.vue`, `.ts`, `.js` files
-- **Source scan (git)** — provide a git repository URL (+ optional branch and access token); the dashboard clones the repo, scans source files, and imports locale files in one step
-- **Sync (local)** — import existing `.json` locale files from a local path into the database
-- **Sync (git)** — clone the configured git repository and import locale JSON files; only fills missing or empty translations — never overwrites existing values
-- **Unused key detection** — keys not found in source files are automatically flagged
-- **Conflict-safe import** — sync and scan never overwrite a translation that already has a value in the database
-
-### Advanced Formats
-*(enable per project in Settings)*
-- **Number formats** — configure `$n(value, 'currency')` presets using `Intl.NumberFormat` with live preview
-- **Datetime formats** — configure `$d(date, 'short')` presets using `Intl.DateTimeFormat` with live preview
-- **Custom modifiers** — define `@.modifier:key` transform functions with a built-in test runner
-- **Snippet generator** — generates a ready-to-paste `createI18n()` configuration block
-
-### Projects
-- **3-step creation wizard** — Source → Info → Languages: add a local path or git repo, auto-detect project name, locales folder and existing languages, then pick languages with the built-in BCP 47 picker
-- **Auto-detect on creation** — reads `package.json` for the project name and scans the locale folder to pre-fill languages; works with both local paths and git repos
-- **Auto-scan on creation** — a scan is automatically triggered after project creation so keys are immediately available
-- **Git repository per project** — configure a git URL, branch, and optional access token; used for scan and sync operations without requiring a local clone
-- **Inline settings** — edit project name, root path, git repo, locales folder, key separator, color, and description directly from the project settings page
-- **Folder browser** — navigate your file system visually to pick the project root path
-- **Project snapshot** — export a complete backup (config + languages + all keys + translations) as a single JSON file, import it on any other instance (merge or replace mode)
-
-### Users & Authentication
-- **Role-based access** — `Super Admin`, `Admin`, `Moderator`, `Translator` — per-project assignments
-- **User search when adding to a project** — search existing users by name or email, select one and choose their role directly; or switch to the creation form for a brand new account
-- **User activity profile** — view translation statistics per user with a configurable time period (last 24h, 7d, 30d, 1 year, or since account creation)
-- **Onboarding wizard** — guided setup on first launch
-- **Multi-language UI** — the dashboard interface itself is translatable
-
-### Technical
-- **Multi-database** — SQLite (default, zero config), PostgreSQL, MySQL/MariaDB
-- **Auto-migration** — schema is created and updated automatically on startup
-- **REST API** — full API for all operations, consume locale JSON from your Vue app
-- **CORS auto-detection** — multiple app URLs per project; all are checked for CORS on `/locale/[lang].json`
-- **Global loading overlay** — a full-page loading screen prevents interaction before data is ready, including on direct page load (F5) for any route
-- **Dark mode** — system preference + manual toggle
-- **Cypress E2E test suite** — full test coverage across all pages (auth, dashboard, projects, translations, languages, users, review, settings); CI-ready with GitHub Actions
-- **GitHub Actions CI** — E2E tests run automatically on every push to `develop` and `main`; Cypress screenshots uploaded as artifacts on failure
-- **Vitest unit test suite** — 344 unit tests covering all composables, services, and server utilities; runs in under 2 minutes with zero infrastructure required
-- **Dual CI pipelines** — unit tests (`unit.yml`) and E2E tests (`e2e.yml`) run in parallel on every push; any regression blocks the pipeline
-- **`src/` layout** — all source files live under `src/` (components, composables, pages, server, services, etc.) for a clean project root
----
+## 🚨 The Problem
 
-## Requirements
+Working with vue-i18n can be painful:
 
-- **Node.js** >= 18
-- **npm** >= 9
+- Editing JSON files manually
+- No real-time feedback
+- Difficult collaboration
+- No centralized management across projects
 
 ---
 
-## Installation
+## 💥 The Solution
 
-### As a dev dependency (recommended — per project)
+Vue i18n Dashboard gives you:
 
-```bash
-npm install i18n-dashboard --save-dev
-```
+- A local tool for your project
+- OR a full translation management platform
 
-### Globally (use across multiple projects)
-
-```bash
-npm install -g i18n-dashboard
-```
+No migration. No vendor lock-in. Works with vue-i18n.
 
 ---
 
-## Quick Start
-
-### 1 — Initialize
-
-Run the interactive setup wizard from your project root:
+## ⚡ Quick Start
 
 ```bash
-npx i18n-dashboard init
-```
-
-This creates an `i18n-dashboard.config.js` file at the root of your project.
-
-### 2 — Start
+npm install i18n-dashboard --save-dev
+or
+npm install -g i18n-dashboard --save-dev
 
-```bash
+npx i18n-dashboard init
 npx i18n-dashboard start
 ```
 
-Open **http://localhost:3333** in your browser.
-
-The onboarding wizard will guide you through:
-1. Creating an administrator account
-2. Selecting the dashboard UI language
-3. Configuring your first project
-
-### 3 — Import existing locale files (optional)
-
-If you already have `.json` locale files, import them into the database:
-
-```bash
-npx i18n-dashboard sync
-```
-
-> The dashboard must be running for this command to work.
-
-### 4 — Use the API in your Vue app
-
-```js
-// src/i18n.js
-import { createI18n } from 'vue-i18n'
-
-export const i18n = createI18n({
-  locale: 'en',
-  fallbackLocale: 'en',
-  messages: {
-    en: await fetch('http://localhost:3333/locale/en.json').then(r => r.json()),
-    fr: await fetch('http://localhost:3333/locale/fr.json').then(r => r.json()),
-  },
-})
-```
-
-### 5 — Add a script to your package.json
-
-```json
-{
-  "scripts": {
-    "dev": "vite",
-    "i18n": "i18n-dashboard start"
-  }
-}
-```
-
----
-
-## Configuration
-
-### i18n-dashboard.config.js
-
-```js
-// i18n-dashboard.config.js
-export default {
-  // Port the dashboard will run on
-  port: 3333,
-
-  // Key separator for nested keys ('home.title' uses '.')
-  keySeparator: '.',
-
-  // URL path pattern for serving locale JSON files
-  apiPath: '/locale/[lang].json',
-
-  // Root path of your Vue project (absolute or relative)
-  projectRoot: './',
-
-  // Database configuration
-  database: {
-    // Options: 'better-sqlite3' (default), 'pg', 'mysql2'
-    client: 'better-sqlite3',
-
-    // SQLite: path to the .db file
-    connection: './i18n-dashboard.db',
-
-    // PostgreSQL / MySQL: use a connection object instead:
-    // connection: {
-    //   host: 'localhost',
-    //   port: 5432,
-    //   user: 'myuser',
-    //   password: 'mypassword',
-    //   database: 'i18n_dashboard',
-    // },
-  },
-
-  // Google Translate API key (optional — free tier works without a key)
-  // googleTranslate: {
-  //   apiKey: process.env.GOOGLE_TRANSLATE_API_KEY,
-  // },
-}
-```
-
-### Environment variables
-
-All options can be passed as environment variables (useful for CI/CD and Docker):
-
-| Variable | Description | Default |
-|---|---|---|
-| `I18N_PORT` | Server port | `3333` |
-| `I18N_DB_CLIENT` | DB driver (`better-sqlite3` / `pg` / `mysql2`) | `better-sqlite3` |
-| `I18N_DB_CONNECTION` | SQLite file path | `./i18n-dashboard.db` |
-| `I18N_DB_HOST` | PostgreSQL/MySQL host | `localhost` |
-| `I18N_DB_PORT` | PostgreSQL/MySQL port | `5432` |
-| `I18N_DB_USER` | Database user | — |
-| `I18N_DB_PASSWORD` | Database password | — |
-| `I18N_DB_NAME` | Database name | `i18n_dashboard` |
-| `I18N_KEY_SEPARATOR` | Key separator | `.` |
-| `I18N_API_PATH` | Locale API path pattern | `/locale/[lang].json` |
-| `I18N_PROJECT_ROOT` | Project root path | `process.cwd()` |
-| `I18N_LOCALES_PATH` | Locales folder (relative to root) | `src/locales` |
-| `GOOGLE_TRANSLATE_API_KEY` | Google Translate API key | — |
-| `SESSION_SECRET` | Session encryption secret | *(default, change in prod)* |
-| `SMTP_HOST` | SMTP server for email | — |
-| `DASHBOARD_URL` | Public URL of the dashboard | `http://localhost:3333` |
-
----
-
-## CLI Commands
-
-```
-i18n-dashboard <command> [options]
-
-Commands:
-  start     Start the dashboard server
-  stop      Stop a running detached dashboard
-  build     Build for production
-  init      Run the interactive setup wizard
-  sync      Import locale JSON files into the database
-
-Options for start:
-  -p, --port <port>   Server port (default: 3333)
-  --detach            Run in the background (writes PID file)
-
-Global options:
-  -V, --version       Show version
-  -h, --help          Show help
-```
-
-### Background mode
-
-```bash
-# Start in background
-npx i18n-dashboard start --detach
-
-# Stop the background process
-npx i18n-dashboard stop
-```
-
----
-
-## Interface
-
-### Dashboard
-
-Customizable widget grid. Available widgets:
-- **Total keys** — overall key count
-- **Coverage** — global translation coverage percentage
-- **Languages** — number of configured languages
-- **Unused keys** — keys not found in source code
-- **Language coverage** — per-language progress bars
-- **Recent activity** — latest translation edits
-- **Review queue** — translations awaiting approval
-- **Projects** — quick project overview
-
-Click **Edit** to add, remove, or rearrange widgets.
-
-### Translations
-
-The main translation table with:
-- Search by key name (real-time)
-- Filter by language and status (`All`, `Draft`, `Reviewed`, `Approved`, `Missing`, `Unused`)
-- Status badge per language
-- Auto-translate per key (Google Translate)
-- Batch auto-translate for an entire language
-
-Click any key to open its **detail page**:
-- Edit each language with the full toolbar (params, escape helpers, plural editor, linked key picker)
-- View translation history with one-click restore
-- See which source files reference this key (after scan)
-
-#### Plural editor
-
-Switch any translation to plural mode to get a template-based form:
-
-| Template | Languages | Example |
-|---|---|---|
-| 2 forms — standard | English, German, Dutch… | `car \| cars` |
-| 3 forms — zero/one/many | French, Spanish, Italian… | `no cars \| {count} car \| {count} cars` |
-| 4 forms — Slavic | Russian, Polish, Ukrainian… | `0 машин \| {n} машина \| {n} машины \| {n} машин` |
-| Custom | Any | Define your own forms |
-
-The `{count}` and `{n}` parameters are always available implicitly.
-
-### Languages
-
-- Add languages from 170+ BCP 47 locale codes (`fr`, `fr-CA`, `en-GB`, `zh-CN`, `sr-Latn`…)
-- Type any custom BCP 47 code if it's not in the list
-- Set a default language (source for auto-translate)
-- Configure fallback chains:
-  - **Automatic** — `fr-CA → fr` (BCP 47 parent)
-  - **Manual** — pick any other configured language
-  - **None** — no fallback
-- The API resolves the fallback chain transparently and merges translations
-
-### Scan
-
-Click **Scan project** in the sidebar or on any project card to open the scan modal.
-
-**Local mode** — browse your file system with the folder picker and scan `.vue`, `.ts`, `.js` files for:
-- `$t('key')`, `$tc()`, `$te()`, `$tm()`
-- `t('key')` via `useI18n()`
-- `<i18n-t keypath="key">`
-- `v-t="'key'"`
-- `<i18n>` SFC blocks
-
-**Git mode** — enter a git repository URL (and optionally a branch and access token); the scanner clones the repo (shallow, depth 1), scans all source files, and also imports locale JSON files to populate missing translations in one step. Useful for CI environments or when you don't have a local checkout.
-
-> Required token permission: **Contents → Read** (GitHub fine-grained PAT) or **repo** scope (classic PAT).
-
-Results displayed inline: keys found, new keys, unused keys, files scanned, languages added, translations imported.
-
-### Settings
-
-Per-project settings (editable inline):
-- **Project name, root path, locales folder, key separator, color, description**
-- **App URLs** — one URL per line; all are accepted for CORS on `/locale/[lang].json`, the first is used for URL-based scan/sync
-- **Git repository** — URL, branch, and access token for Git scan mode (token stored in DB, never exposed in the UI after save)
-- **Advanced features** — enable/disable Number formats, Datetime formats, Custom modifiers pages
-- **Scanner** — configure excluded directories
-- **Google Translate** — optional API key
-- **Export** — download locale JSON files per language or all at once
-- **Snapshot** — export/import a full project backup
-
-### Number Formats *(requires enable in Settings)*
-
-Configure `$n(value, 'formatName')` presets:
-- Group by locale
-- Style: `decimal`, `currency`, `percent`, `unit`
-- Currency / unit selection
-- Live `Intl.NumberFormat` preview
-
-### Datetime Formats *(requires enable in Settings)*
-
-Configure `$d(date, 'formatName')` presets:
-- Shortcut styles: `dateStyle` / `timeStyle`
-- Individual fields: `year`, `month`, `day`, `hour`, `minute`, `second`, `weekday`, `era`, `timeZone`
-- Live `Intl.DateTimeFormat` preview
-
-### Modifiers *(requires enable in Settings)*
-
-Define custom `@.modifier:key` transform functions:
-- Write JS function body
-- Live test runner
-- Quick templates: `snakeCase`, `camelCase`, `kebabCase`, `titleCase`
-
-### Snippet generator
-
-Available on all format pages — generates a ready-to-paste `createI18n()` configuration including all your number formats, datetime formats, and custom modifiers.
-
-### Project Snapshot
-
-Export a complete project backup:
-
-```json
-{
-  "version": 1,
-  "exportedAt": "2026-01-01T00:00:00.000Z",
-  "project": { "name": "My App", "locales_path": "src/locales", "key_separator": "." },
-  "languages": [{ "code": "en", "name": "English", "is_default": true }],
-  "keys": [
-    {
-      "key": "home.title",
-      "description": "Homepage title",
-      "translations": {
-        "en": { "value": "Welcome", "status": "approved" },
-        "fr": { "value": "Bienvenue", "status": "reviewed" }
-      }
-    }
-  ]
-}
-```
-
-Import modes:
-- **Merge** — add/update keys without touching existing ones
-- **Replace** — delete everything and reimport clean
-
----
-
-## vue-i18n Integration
-
-### Basic (load all on startup)
-
-```js
-// src/i18n.js
-import { createI18n } from 'vue-i18n'
-
-const DASHBOARD = 'http://localhost:3333'
-
-export const i18n = createI18n({
-  locale: 'en',
-  fallbackLocale: 'en',
-  messages: {
-    en: await fetch(`${DASHBOARD}/locale/en.json`).then(r => r.json()),
-    fr: await fetch(`${DASHBOARD}/locale/fr.json`).then(r => r.json()),
-  },
-})
-```
-
-### With lazy loading
-
-```js
-import { createI18n } from 'vue-i18n'
-
-const DASHBOARD = 'http://localhost:3333'
-
-export const i18n = createI18n({ locale: 'en', fallbackLocale: 'en', messages: {} })
-
-export async function setLocale(locale) {
-  if (!i18n.global.availableLocales.includes(locale)) {
-    const messages = await fetch(`${DASHBOARD}/locale/${locale}.json`).then(r => r.json())
-    i18n.global.setLocaleMessage(locale, messages)
-  }
-  i18n.global.locale.value = locale
-}
-```
-
-### With BCP 47 fallbacks
-
-The API automatically resolves fallback chains. If `fr-CA` isn't fully translated, missing keys fall back to `fr`, then to the next configured fallback:
-
-```
-GET /locale/fr-CA.json   →  merges fr + fr-CA (fr-CA takes precedence)
-X-I18n-Fallback-Chain: fr-CA → fr
-```
-
-No configuration needed on the client side.
-
-### For production
-
-Export locale files into your project and include them in your build:
-
-```bash
-curl http://localhost:3333/locale/en.json -o src/locales/en.json
-curl http://localhost:3333/locale/fr.json -o src/locales/fr.json
-```
-
-Or deploy the dashboard on an internal server and keep using the API.
+👉 Open http://localhost:3333
 
 ---
 
-## Database
+## 🧠 Two Ways to Use It
 
-### SQLite (default — zero config)
+### 🟢 Local Mode
 
-```js
-database: {
-  client: 'better-sqlite3',
-  connection: './i18n-dashboard.db',
-}
-```
-
-The `.db` file is created automatically. No setup needed.
+- Run inside your project
+- Sync keys from your code
+- Export JSON files
 
-### PostgreSQL
-
-```bash
-npm install pg
-```
-
-```js
-database: {
-  client: 'pg',
-  connection: {
-    host: 'localhost',
-    port: 5432,
-    user: 'myuser',
-    password: 'mypassword',
-    database: 'i18n_dashboard',
-  },
-}
-```
-
-### MySQL / MariaDB
-
-```bash
-npm install mysql2
-```
-
-```js
-database: {
-  client: 'mysql2',
-  connection: {
-    host: 'localhost',
-    port: 3306,
-    user: 'myuser',
-    password: 'mypassword',
-    database: 'i18n_dashboard',
-  },
-}
-```
-
-### Schema
-
-Tables are created and migrated automatically on startup:
-
-```
-projects          — multi-project support
-languages         — per-project language list (BCP 47 codes, fallback_code)
-translation_keys  — key registry (key, description, is_unused, usages)
-translations      — values per key per language (value, status)
-translation_history — full edit history (old_value, new_value, changed_by)
-key_usages        — source file references (file_path, line_number, function)
-settings          — global settings (scan_exclude, google_translate_api_key)
-users             — dashboard users (name, email, role, bcrypt password)
-project_number_formats   — Intl.NumberFormat presets
-project_datetime_formats — Intl.DateTimeFormat presets
-project_modifiers        — custom @.modifier functions
-```
+👉 Best for simple setups
 
 ---
 
-## REST API
-
-All endpoints require a `project_id` parameter.
-
-### Locale export (main endpoint for vue-i18n)
-
-```http
-GET /locale/:lang.json?project_id=1
-```
-
-Returns nested JSON with all translations for the given language. Resolves fallback chains automatically.
-
-**Response headers:**
-- `X-I18n-Fallback-Chain: fr-CA → fr` — debug the resolved chain
-
-### Projects
-
-```http
-GET    /api/projects
-POST   /api/projects
-PUT    /api/projects/:id
-DELETE /api/projects/:id
-```
-
-### Languages
-
-```http
-GET    /api/languages?project_id=1
-POST   /api/languages
-PUT    /api/languages/:id
-DELETE /api/languages/:code?project_id=1
-```
-
-### Translation keys
-
-```http
-GET    /api/keys?project_id=1&search=&lang=&status=&page=1&limit=50
-GET    /api/keys/:id
-POST   /api/keys
-PATCH  /api/keys/:id
-DELETE /api/keys/:id
-```
-
-### Translations
-
-```http
-POST /api/translations          # Save a translation value
-POST /api/translations/status   # Update status only
-POST /api/translations/batch-translate   # Auto-translate all missing for a language
-```
-
-### Scan & Sync
-
-```http
-POST /api/scan     # body: { project_id, mode: 'local'|'git', root_path?, git_url?, git_branch?, git_token? }
-POST /api/sync     # body: { project_id }  — uses project's configured git repo or local path
-POST /api/projects/detect  # body: { root_path?, git_url?, git_branch?, git_token? }
-GET  /api/projects/check-name?name=&exclude_id=   # Availability check
-```
-
-### Project Snapshot
-
-```http
-GET  /api/project-snapshot?project_id=1         # Export
-POST /api/project-snapshot                       # Import
-     body: { snapshot, project_id?, mode: 'merge'|'replace' }
-```
-
-### Advanced formats
-
-```http
-GET  /api/formats/number?project_id=1
-POST /api/formats/number
-PUT  /api/formats/number/:id
-DELETE /api/formats/number/:id
-
-GET  /api/formats/datetime?project_id=1
-POST /api/formats/datetime
-PUT  /api/formats/datetime/:id
-DELETE /api/formats/datetime/:id
-
-GET  /api/formats/modifiers?project_id=1
-POST /api/formats/modifiers
-PUT  /api/formats/modifiers/:id
-DELETE /api/formats/modifiers/:id
+### 🔵 Server Mode
 
-GET  /api/formats/snippet?project_id=1   # Generate createI18n() config snippet
-```
-
-### Users
-
-```http
-GET  /api/users                           # All users (super admin / global admin)
-GET  /api/users?project_id=1              # Members of a project
-GET  /api/users?exclude_project_id=1      # Users not yet in a project (for the add picker)
-POST /api/users                           # Create user
-PUT  /api/users/:id                       # Update user (name, is_active, role)
-PUT  /api/users/:id/roles                 # Bulk-update role assignments across projects
-DELETE /api/users/:id?project_id=1        # Remove user from project (or globally if super admin)
-GET  /api/users/:id/profile?period=30d    # Full user profile with activity stats
-```
-
-### Settings
-
-```http
-GET  /api/settings
-POST /api/settings
-```
-
-### File system browser
+- Central dashboard for multiple projects
+- API-based (no JSON handling)
+- Git sync
 
-```http
-GET /api/fs/browse?path=/some/path   # List subdirectories; defaults to home dir
-```
+👉 Best for teams & scaling
 
 ---
 
-## User Roles
+## 🎯 Why this tool?
 
-| Role | Permissions |
-|---|---|
-| **Super Admin** | Full access to all projects, users, and global settings |
-| **Admin** | Full access to assigned projects |
-| **Moderator** | Edit translations, approve/reject in review queue |
-| **Translator** | Edit translations, mark as reviewed (cannot approve) |
+- Works with vue-i18n (no migration)
+- Self-hosted (no lock-in)
+- Multi-project support
+- Git-friendly workflow
+- Developer-first experience
 
 ---
 
-## Recommended Workflows
-
-### New project from scratch
-
-```bash
-# 1. Install
-npm install i18n-dashboard --save-dev
-
-# 2. Initialize
-npx i18n-dashboard init
+## 📘 Documentation
 
-# 3. Start
-npx i18n-dashboard start
-
-# 4. In the UI:
-#    - Add languages (Languages tab)
-#    - Add translation keys (Translations tab)
-#    - Use the API in your Vue app
-```
-
-### Migrate from existing JSON files
-
-```bash
-# 1. Install and initialize
-npm install i18n-dashboard --save-dev
-npx i18n-dashboard init
-
-# 2. Start
-npx i18n-dashboard start
-
-# 3. Sync your existing locale files
-npx i18n-dashboard sync
-
-# 4. All keys and translations are now in the database
-```
-
-### Team workflow with review
-
-1. **Translators** edit keys → status: `Draft`
-2. **Translators** mark ready → status: `Reviewed`
-3. **Moderators/Admins** approve → status: `Approved`
-4. Only `Approved` translations are exported (or all, depending on your needs)
-
-### Move between environments (local → production)
-
-```bash
-# On local machine: export snapshot
-# Dashboard UI → Settings → Snapshot → Export
-
-# On production server: import snapshot
-# Dashboard UI → Settings → Snapshot → Import (Merge or Replace mode)
-```
-
----
-
-## Stack
-
-| Technology | Version | Role |
-|---|---|---|
-| [Nuxt 3](https://nuxt.com/) | 3.21+ | Full-stack framework (Nitro backend + Vue 3 frontend) |
-| [Nuxt UI](https://ui.nuxt.com/) | 3.3+ | UI components (Tailwind CSS v4 + Reka UI) |
-| [Knex.js](https://knexjs.org/) | 3.x | Multi-database abstraction |
-| [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) | 11.x | SQLite driver |
-| [@vitalets/google-translate-api](https://github.com/vitalets/google-translate-api) | 9.x | Google Translate (free tier) |
-| [Commander.js](https://github.com/tj/commander.js) | 13.x | CLI |
-| [bcryptjs](https://github.com/dcodeIO/bcrypt.js) | 2.x | Password hashing |
-| [Cypress](https://www.cypress.io/) | 13.x | E2E test suite |
-| [Vitest](https://vitest.dev/) | 4.x | Unit test suite (composables, services, server utils) |
----
-
-## Contributing
-
-Contributions are welcome. Please open an issue before submitting a pull request for significant changes.
-
-```bash
-git clone https://github.com/arnaudprioul/i18n-dashboard.git
-cd i18n-dashboard
-npm install
-
-# Register the project git hooks (one-time, per clone)
-git config core.hooksPath .githooks
-```
-
-### Commit message convention
-
-Every push to `main` must include at least one commit message with a version bump indicator:
-
-| Indicator | Bump | Example |
-|---|---|---|
-| `[patch]` | `0.3.8 → 0.3.9` | `fix: correct typo in error message [patch]` |
-| `[minor]` | `0.3.8 → 0.4.0` | `feat: add git scan mode [minor]` |
-| `[major]` | `0.3.8 → 1.0.0` | `feat!: breaking API change [major]` |
-
-The pre-push hook will block the push if:
-- No `[major]`, `[minor]`, or `[patch]` indicator is found in the commits
-- `README.md` has not been updated
-
-If both checks pass, the CI automatically bumps `package.json`, creates the git tag, and triggers the npm publish workflow.
+- See USAGE.md for workflows
+- See DOCUMENTATION.md for full technical details
 
 ---
 
-## Support
-
-If this project saved you time, consider buying me a coffee ☕
+## 💬 Feedback
 
-[![Donate with PayPal](https://img.shields.io/badge/Donate-PayPal-blue?logo=paypal)](https://www.paypal.com/paypalme/arnaudprioul)
+Looking for feedback 👀  
+Open an issue or discussion!
 
 ---
 
-## License
-
-[MIT](./LICENSE)
-
----
+## 📄 License
 
-Made with ❤️ by [arnaudprioul](https://github.com/arnaudprioul)
+MIT

package/bin/cli.mjs

@@ -100,7 +100,7 @@ program
         const port = env.I18N_PORT || '3333'
         const host = env.I18N_HOST || 'localhost'
 
-        console.log(`\n🌐 Starting vue-i18n-dashboard on http://${host}:${port}`)
+        console.log(`\n🌐 Starting i18n-dashboard on http://${host}:${port}`)
         console.log(`📁 Project root: ${env.I18N_PROJECT_ROOT}\n`)
 
         const outputDir = resolve(packageRoot, '.output')
@@ -115,7 +115,10 @@ program
                 detached: options.detach || false,
             })
         } else {
-            proc = spawn('npx', ['nuxt', 'dev', '--port', port, '--host', host], {
+            // Use the nuxt binary bundled with the package so it works whether
+            // i18n-dashboard is installed locally (node_modules/.bin) or globally.
+            const nuxtBin = resolve(packageRoot, 'node_modules/.bin/nuxt')
+            proc = spawn(nuxtBin, ['dev', '--port', port, '--host', host], {
                 env,
                 stdio: options.detach ? 'ignore' : 'inherit',
                 cwd: packageRoot,
@@ -130,7 +133,7 @@ program
         if (options.detach) {
             proc.unref()
             console.log(`✅ Dashboard started in background (PID: ${proc.pid})`)
-            console.log(`   Stop it with: vue-i18n-dashboard stop\n`)
+            console.log(`   Stop it with: i18n-dashboard stop\n`)
         } else {
             proc.on('exit', (code) => {
                 if (existsSync(pidFile)) unlinkSync(pidFile)
@@ -195,8 +198,9 @@ program
     .command('build')
     .description('Build the dashboard for production (run once after install)')
     .action(async () => {
-        console.log('\n🔨 Building vue-i18n-dashboard for production...\n')
-        const proc = spawn('npx', ['nuxt', 'build'], {
+        console.log('\n🔨 Building i18n-dashboard for production...\n')
+        const nuxtBin = resolve(packageRoot, 'node_modules/.bin/nuxt')
+        const proc = spawn(nuxtBin, ['build'], {
             env: process.env,
             stdio: 'inherit',
             cwd: packageRoot,
@@ -204,7 +208,7 @@ program
         proc.on('exit', (code) => {
             if (code === 0) {
                 console.log('\n✅ Build complete!')
-                console.log('   Run "vue-i18n-dashboard start" to launch the dashboard.\n')
+                console.log('   Run "i18n-dashboard start" to launch the dashboard.\n')
             } else {
                 console.error('\n❌ Build failed.\n')
             }
@@ -222,7 +226,7 @@ program
         const rl = createInterface({ input: process.stdin, output: process.stdout })
         const question = (q) => new Promise((resolve) => rl.question(q, resolve))
 
-        console.log('\nvue-i18n-dashboard — Initialisation\n')
+        console.log('\ni18n-dashboard — Initialisation\n')
 
         const dbClient = options.db || await question('Base de données [sqlite3/postgresql/mysql] (défaut: sqlite3): ') || 'sqlite3'
         const localesPath = await question('Dossier des locales (défaut: src/locales): ') || 'src/locales'
@@ -298,7 +302,7 @@ export default {
         writeFileSync(resolve(process.cwd(), 'i18n-dashboard.config.js'), configContent)
 
         console.log('\n✅ Fichier de configuration créé : i18n-dashboard.config.js')
-        console.log('   Lancez le dashboard avec : vue-i18n-dashboard start\n')
+        console.log('   Lancez le dashboard avec : i18n-dashboard start\n')
 
         rl.close()
     })
@@ -332,7 +336,7 @@ program
             const data = await res.json()
             console.log(`✅ Sync done: ${data.added} ajoutées · ${data.updated} mises à jour · ${data.total} total\n`)
         } catch (e) {
-            console.error('Could not connect to dashboard. Is it running?\n  vue-i18n-dashboard start\n')
+            console.error('Could not connect to dashboard. Is it running?\n  i18n-dashboard start\n')
         }
     })
 

package/nuxt.config.ts

@@ -1,4 +1,16 @@
 // https://nuxt.com/docs/api/configuration/nuxt-config
+
+// Warn at build/start time if SESSION_SECRET is still the insecure default.
+// A weak, publicly known secret allows anyone to forge session tokens.
+const DEFAULT_SECRET = 'i18n-dashboard-default-secret-change-me-in-production!!'
+if (!process.env.SESSION_SECRET || process.env.SESSION_SECRET === DEFAULT_SECRET) {
+  console.warn(
+    '\n⚠️  [i18n-dashboard] SESSION_SECRET is not set or is using the default value.\n' +
+    '   Set a strong random secret in your environment:\n' +
+    '   SESSION_SECRET=$(openssl rand -hex 32)\n',
+  )
+}
+
 export default defineNuxtConfig({
   compatibilityDate: '2025-01-01',
   devtools: { enabled: false },
@@ -27,8 +39,8 @@ export default defineNuxtConfig({
     // Only set when the CLI passes I18N_PROJECT_ROOT explicitly (not defaulted)
     projectRoot: process.env.I18N_PROJECT_ROOT || '',
     localesPath: process.env.I18N_LOCALES_PATH || 'src/locales',
-    // Auth
-    sessionSecret: process.env.SESSION_SECRET || 'i18n-dashboard-default-secret-change-me-in-production!!',
+    // Auth — set SESSION_SECRET to a strong random value in production
+    sessionSecret: process.env.SESSION_SECRET || DEFAULT_SECRET,
     // Email (SMTP) — optional
     smtpHost: process.env.SMTP_HOST || '',
     smtpPort: process.env.SMTP_PORT || '587',
@@ -57,6 +69,26 @@ export default defineNuxtConfig({
         dir: './src/assets/locales',
       },
     ],
+    // ── Security headers ─────────────────────────────────────────────────────
+    // Applied to every response from the Nitro server.
+    routeRules: {
+      '/**': {
+        headers: {
+          // Prevent the dashboard from being embedded in iframes (clickjacking)
+          'X-Frame-Options': 'DENY',
+          // Stop browsers from MIME-sniffing away from the declared content-type
+          'X-Content-Type-Options': 'nosniff',
+          // Disable legacy XSS auditor (modern browsers use CSP instead)
+          'X-XSS-Protection': '0',
+          // Remove the server fingerprint
+          'Server': '',
+          // Don't leak the referrer when navigating to external sites
+          'Referrer-Policy': 'strict-origin-when-cross-origin',
+          // Restrict powerful browser features
+          'Permissions-Policy': 'camera=(), microphone=(), geolocation=()',
+        },
+      },
+    },
   },
 
   typescript: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18n-dashboard",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "A web dashboard to manage vue-i18n translation keys with database persistence",
   "type": "module",
   "bin": {

package/src/server/api/db-config.post.ts

@@ -44,7 +44,10 @@ export default defineEventHandler(async (event) => {
     }
   } catch (e: any) {
     await testDb.destroy().catch(() => {})
-    throw createError({ statusCode: 400, message: 'Connection failed: ' + (e.message || String(e)) })
+    // Log the full error server-side only — never expose DB host, port,
+    // credentials hints, or driver internals to the client.
+    console.error('[i18n-dashboard] DB connection test failed:', e.message)
+    throw createError({ statusCode: 400, message: 'Database connection failed. Please check your settings.' })
   }
   await testDb.destroy()
 

package/src/server/api/fs/browse.get.ts

@@ -2,14 +2,28 @@ import { readdirSync, statSync, existsSync } from 'fs'
 import { resolve, join, dirname, sep } from 'path'
 import { homedir } from 'os'
 
+// Allowed root anchors — browsing is limited to the user's home directory and
+// any filesystem root. This prevents authenticated users from enumerating
+// arbitrary paths outside their working area (e.g. /etc, /proc, /var/...).
+function isAllowedPath(absolutePath: string): boolean {
+  const home = homedir()
+  // Allow: anything under home, filesystem roots (/  or C:\), and /tmp
+  const allowedRoots = [home, sep, resolve('/tmp')]
+  return allowedRoots.some(root => absolutePath === root || absolutePath.startsWith(root + sep))
+}
+
 export default defineEventHandler(async (event) => {
   const query = getQuery(event)
   const rawPath = query.path && String(query.path).trim() ? String(query.path).trim() : homedir()
 
   const absolutePath = resolve(rawPath)
 
+  if (!isAllowedPath(absolutePath)) {
+    throw createError({ statusCode: 403, message: 'Access to this path is not allowed.' })
+  }
+
   if (!existsSync(absolutePath)) {
-    throw createError({ statusCode: 404, message: `Path not found: ${absolutePath}` })
+    throw createError({ statusCode: 404, message: 'Path not found.' })
   }
 
   const stat = statSync(absolutePath)

package/src/server/api/scan.post.ts

@@ -1,7 +1,7 @@
 import { resolve, extname, basename } from 'path'
 import { mkdtempSync, rmSync, readdirSync, readFileSync, existsSync } from 'fs'
 import { tmpdir } from 'os'
-import { execSync } from 'child_process'
+import { spawnSync } from 'child_process'
 import { getDb } from '../db/index'
 import { scanProject, detectLanguages } from '../utils/scanner.uti'
 
@@ -30,11 +30,21 @@ export default defineEventHandler(async (event) => {
         parsed.password = gitToken
         cloneUrl = parsed.toString()
       }
-      const branchArgs = gitBranch ? `--branch ${gitBranch} ` : ''
-      execSync(`git clone --depth 1 ${branchArgs}-- "${cloneUrl}" "${tmpDir}"`, { timeout: 60_000, stdio: 'pipe' })
+      // Use spawnSync with an argument array — never concatenate user-supplied
+      // branch names into a shell string (command injection risk).
+      const gitArgs = ['clone', '--depth', '1']
+      if (gitBranch) gitArgs.push('--branch', gitBranch)
+      gitArgs.push('--', cloneUrl, tmpDir)
+      const gitResult = spawnSync('git', gitArgs, { timeout: 60_000, stdio: 'pipe' })
+      if (gitResult.status !== 0) {
+        throw new Error(gitResult.stderr?.toString().trim() || 'git clone failed')
+      }
     } catch (e: any) {
       rmSync(tmpDir, { recursive: true, force: true })
-      throw createError({ statusCode: 400, message: `Git clone failed: ${e.message ?? 'unknown error'}` })
+      // Log the full error server-side; return a generic message to the client
+      // to avoid leaking git URL, token hints, or server paths.
+      console.error('[i18n-dashboard] git clone error:', e.message)
+      throw createError({ statusCode: 400, message: 'Git clone failed. Check the URL, branch, and access token.' })
     }
 
     try {

package/src/server/api/sync.post.ts

@@ -1,7 +1,7 @@
 import { resolve, extname, basename } from 'path'
 import { readdirSync, readFileSync, existsSync, mkdtempSync, rmSync } from 'fs'
 import { tmpdir } from 'os'
-import { execSync } from 'child_process'
+import { spawnSync } from 'child_process'
 import { getDb } from '../db/index'
 
 function flattenObject(obj: Record<string, any>, separator: string, prefix = ''): Record<string, string> {
@@ -119,8 +119,15 @@ export default defineEventHandler(async (event) => {
         parsed.password = gitRepo.token
         cloneUrl = parsed.toString()
       }
-      const branchArgs = gitRepo.branch ? `--branch ${gitRepo.branch} ` : ''
-      execSync(`git clone --depth 1 ${branchArgs}-- "${cloneUrl}" "${tmpDir}"`, { timeout: 60_000, stdio: 'pipe' })
+      // Use spawnSync with an argument array — never concatenate user-supplied
+      // branch names into a shell string (command injection risk).
+      const gitArgs = ['clone', '--depth', '1']
+      if (gitRepo.branch) gitArgs.push('--branch', gitRepo.branch)
+      gitArgs.push('--', cloneUrl, tmpDir)
+      const gitResult = spawnSync('git', gitArgs, { timeout: 60_000, stdio: 'pipe' })
+      if (gitResult.status !== 0) {
+        throw new Error(gitResult.stderr?.toString().trim() || 'git clone failed')
+      }
 
       const localesDirPath = resolve(tmpDir, project.locales_path || 'src/locales')
       const { added, skipped, files } = await syncFromDir(db, Number(project_id), localesDirPath, separator)
@@ -128,7 +135,8 @@ export default defineEventHandler(async (event) => {
       const total = await db('translation_keys').where({ project_id: Number(project_id) }).count('* as count').first()
       return { added, skipped, updated: 0, total: Number((total as any)?.count || 0), files }
     } catch (e: any) {
-      throw createError({ statusCode: 400, message: `Git sync failed: ${e.message ?? 'unknown'}` })
+      console.error('[i18n-dashboard] git sync error:', e.message)
+      throw createError({ statusCode: 400, message: 'Git sync failed. Check the URL, branch, and access token.' })
     } finally {
       rmSync(tmpDir, { recursive: true, force: true })
     }

package/src/server/api/translations/bulk-status.post.ts

@@ -16,9 +16,17 @@ export default defineEventHandler(async (event) => {
   }
 
   const db = getDb()
-  await db('translations')
-    .whereIn('id', ids)
-    .update({ status, updated_at: db.fn.now() })
+  if (status === TRANSLATION_STATUS.APPROVED) {
+    // Freeze approved_value for each translation individually so we capture
+    // its current working value at approval time.
+    await db('translations')
+      .whereIn('id', ids)
+      .update({ status, approved_value: db.ref('value'), updated_at: db.fn.now() })
+  } else {
+    await db('translations')
+      .whereIn('id', ids)
+      .update({ status, updated_at: db.fn.now() })
+  }
 
   return { updated: ids.length }
 })

package/src/server/api/translations/status.post.ts

@@ -22,9 +22,16 @@ export default defineEventHandler(async (event) => {
     throw createError({ statusCode: 404, message: 'Translation not found' })
   }
 
+  const updates: Record<string, any> = { status, updated_at: db.fn.now() }
+  // Freeze the approved value so the locale API can serve it even if the
+  // translation is later edited back to draft.
+  if (status === TRANSLATION_STATUS.APPROVED) {
+    updates.approved_value = existing.value
+  }
+
   await db('translations')
     .where({ id: existing.id })
-    .update({ status, updated_at: db.fn.now() })
+    .update(updates)
 
   return db('translations').where({ id: existing.id }).first()
 })

package/src/server/api/users/index.post.ts

@@ -1,4 +1,5 @@
 import bcrypt from 'bcryptjs'
+import { randomBytes } from 'crypto'
 import { getDb } from '../../db/index'
 import { getUserRole, canManageUsers } from '../../utils/auth.util'
 import { sendEmail, inviteEmailHtml } from '../../utils/mailer.util'
@@ -6,7 +7,8 @@ import { useRuntimeConfig } from '#imports'
 
 function generateTempPassword(): string {
   const chars = 'ABCDEFGHJKMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz23456789'
-  return Array.from({ length: 12 }, () => chars[Math.floor(Math.random() * chars.length)]).join('')
+  const bytes = randomBytes(12)
+  return Array.from(bytes, (b) => chars[b % chars.length]).join('')
 }
 
 export default defineEventHandler(async (event) => {
@@ -85,5 +87,8 @@ export default defineEventHandler(async (event) => {
     console.warn('[i18n-dashboard] Email non envoyé:', e.message)
   }
 
-  return { id: userId, email: email.toLowerCase().trim(), name, tempPassword }
+  // Never return the temporary password in the API response — it was already
+  // sent via email. Returning it here would expose it in browser DevTools,
+  // proxy logs, and any API monitoring tool.
+  return { id: userId, email: email.toLowerCase().trim(), name }
 })

package/src/server/consts/commons.const.ts

@@ -7,5 +7,15 @@ export const PUBLIC_ROUTES = [
 	'/api/setup',
 	'/api/ui-locale',
 	'/api/config',
+	// '/api/db-config' is intentionally NOT public — it can reconfigure and
+	// reset the entire database. It is accessible only during the onboarding
+	// wizard (before any user exists) via the auth middleware's setup-mode
+	// bypass, and requires super_admin authentication at all other times.
+]
+
+// Routes accessible without authentication only while onboarding is incomplete
+// (no users in the database yet). Once a super admin exists, these routes
+// require a valid session.
+export const SETUP_ONLY_ROUTES = [
 	'/api/db-config',
 ]

package/src/server/db/index.ts

@@ -1018,6 +1018,19 @@ export async function initDb(): Promise<void> {
     t.text('git_repos').nullable(),
   )
 
+  // ── migration: approved_value column on translations ────────────────────
+  // Stores the last approved value independently from the working `value`.
+  // The locale JSON endpoint serves this column so that in-progress drafts
+  // are never exposed to end-users; only explicitly approved content is published.
+  await addColumnIfMissing(db, 'translations', 'approved_value', (t) =>
+    t.text('approved_value').nullable(),
+  )
+  // Backfill: seed approved_value for translations that are already approved
+  await db('translations')
+    .where('status', 'approved')
+    .whereNull('approved_value')
+    .update({ approved_value: db.ref('value') })
+
   // ── refresh_tokens ────────────────────────────────────────────────────────
   const hasRefreshTokens = await db.schema.hasTable('refresh_tokens')
   if (!hasRefreshTokens) {

package/src/server/middleware/auth.ts

@@ -2,7 +2,7 @@ import { useSession } from 'h3'
 
 import { getDb } from '../db/index'
 import { sessionConfig } from '../utils/auth.util'
-import { PUBLIC_ROUTES } from '../consts/commons.const'
+import { PUBLIC_ROUTES, SETUP_ONLY_ROUTES } from '../consts/commons.const'
 
 export default defineEventHandler(async (event) => {
 	const path = event.path || ''
@@ -10,9 +10,20 @@ export default defineEventHandler(async (event) => {
 	// Only protect API routes
 	if (!path.startsWith('/api/')) return
 
-	// Allow public endpoints
+	// Allow fully public endpoints (no auth ever required)
 	if (PUBLIC_ROUTES.includes(path)) return
 
+	// Setup-only routes: allowed without auth ONLY while no user exists yet
+	// (i.e. onboarding is not yet complete). Once any user is created they
+	// require a valid super_admin session.
+	if (SETUP_ONLY_ROUTES.includes(path)) {
+		const db = getDb()
+		const userCount = await db('users').count('* as count').first()
+		const count = Number((userCount as any)?.count ?? 0)
+		if (count === 0) return // still in onboarding — allow through
+		// Onboarding complete: fall through to normal session check below
+	}
+
 	// Check session
 	const session = await useSession(event, sessionConfig())
 	const userId = (session.data as any).userId
@@ -28,5 +39,10 @@ export default defineEventHandler(async (event) => {
 		throw createError({ statusCode: 401, message: 'Session invalide' })
 	}
 
+	// Extra guard for setup-only routes: require super_admin once users exist
+	if (SETUP_ONLY_ROUTES.includes(path) && !user.is_super_admin) {
+		throw createError({ statusCode: 403, message: 'Accès réservé au super administrateur' })
+	}
+
 	event.context.user = user
 })

package/src/server/routes/locale/[lang].get.ts

@@ -76,13 +76,16 @@ async function loadTranslations(
   projectId: number,
   langCode: string,
 ): Promise<Record<string, string>> {
+  // Only serve the `approved_value` — the value frozen at last approval.
+  // Translations that have never been approved (approved_value IS NULL) are
+  // intentionally excluded so that drafts/reviews never leak to end-users.
   const rows = await db('translations as t')
     .join('translation_keys as k', 't.key_id', 'k.id')
     .where('t.language_code', langCode)
     .where('k.project_id', projectId)
-    .whereNotNull('t.value')
-    .where('t.value', '!=', '')
-    .select('k.key', 't.value')
+    .whereNotNull('t.approved_value')
+    .where('t.approved_value', '!=', '')
+    .select('k.key', 't.approved_value as value')
 
   const flat: Record<string, string> = {}
   for (const row of rows) flat[row.key] = row.value