Esam-jr/QalSync

A localization toolchain for Next.js/React apps, focused on East African languages (Amharic, Afaan Oromo, Tigrinya, and Somali) that generic translation tools handle poorly. # QalSync A developer-first localization toolchain for Next.js and React apps, specialized in East African languages (**Amharic**, **Afaan Oromo**, **Tigrinya**, and **Somali**) that generic translation tools handle poorly. Features deep AST code & data scanning, incremental caching, and a human review workflow with Google Gemini AI. --- ## Project Structure ``` /apps/backend ← Next.js server (API routes + review dashboard) /packages/client ← QalSync CLI (@qalsync/client) & SDK package ``` --- ## Architecture & Workflow 1. **AST & Data Extraction:** Discovers JSX text, UI attributes, JSX expressions, data constants, objects, arrays, and JSON data files (`data/`, `constants/`, `content/`, `app/`, `src/`). 2. **2-Level Caching:** Diffs extracted strings locally against existing `messages/*.json` and remote database cache. 3. **Bring-Your-Own-Key (BYOK) AI:** Only brand-new, untranslated strings are translated via Gemini AI using the developer's free Gemini API key. 4. **Human Review Portal:** Review, edit, and approve translations in the web dashboard at `/review`. --- ## Prerequisites & Setup - Node.js ≥ 18 - A Supabase project (PostgreSQL database & auth) - A free Google AI / Gemini API key ### 1. Server Environment (`apps/backend/.env.local`) ```env # Supabase (server-side API routes) SUPABASE_URL=your-project.supabase.co SUPABASE_ANON_KEY=your-anon-key # Supabase (client-side browser auth) NEXT_PUBLIC_SUPABASE_URL=your-project.supabase.co NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key # Optional: Gemini model override (defaults to gemini-2.5-flash) # GEMINI_MODEL=gemini-2.5-flash ``` ### 2. Database Migrations 1. Go to your Supabase project → **SQL Editor**. 2. Run the migration SQL files found in `apps/backend/supabase/migrations/`. 3. Enable Email Auth in **Supabase Dashboard** → **Authentication** → **Providers** → **Email**. ### 3. Running the Server Locally ```bash # In the workspace root: npm install npm run dev --filt …