shallok 0.0.0-stage → 0.1.0

package/skills/localize-app/references/versioning.md

@@ -0,0 +1,57 @@
+# Per-Key Versioning & Context Reference
+
+## Canonical Source Catalog (`localization_base/`)
+The canonical catalog is the single source of truth for all active and obsolete keys, including their cryptographic content hashes and version counters.
+
+### Structure of a Canonical Entry
+```json
+{
+  "checkout.pay_now": {
+    "key": "checkout.pay_now",
+    "content": "Pay now",
+    "context": "Primary action button on checkout screen to trigger payment modal",
+    "relative_file_path": "src/components/checkout.tsx",
+    "occurrences": [
+      {
+        "relative_file_path": "src/components/checkout.tsx",
+        "line": 42,
+        "column": 12
+      }
+    ],
+    "last_updated_at": "2026-10-19T10:00:00.000Z",
+    "key_version": 1,
+    "content_hash": "sha256:...",
+    "status": "active"
+  }
+}
+```
+
+## Context Enrichment by AI Agents
+1. When strings are extracted via `localize extract`, the CLI provides baseline AST context (e.g. `JSX text in <button> (in App <button>)`).
+2. The AI Agent analyzes the source code, component hierarchy, and user flow, and enriches the `context` with semantic clarity:
+   - CLI method: `localize context set <key> "<semantic_description>"`
+   - Direct edit: Update `"context"` in `localization_base/<source_locale>.json`.
+3. **Preservation Guarantee**:
+   Shallok's reconciliation algorithm (`reconcileCanonicalCatalog`) checks if a key already has an enriched context. Unless the source code introduces an explicit inline comment (`{/* context: ... */}`), the AI agent's enriched context is **strictly preserved** across all future extractions and will not be overwritten by generic AST node descriptions.
+
+## Reconciliation & Versioning Rules
+1. **New Key**: Initialized at `key_version = 1`, `status = "active"`.
+2. **Unchanged Content & Context**: `key_version` and `last_updated_at` remain unchanged.
+3. **Modified Source Content**: `key_version` increments by 1; `last_updated_at` is updated.
+4. **File Move / Occurrence Change**: Path and occurrence lines are updated; `key_version` does NOT increment.
+5. **Key Removed from Source**: Marked `status = "obsolete"`; preserved in catalog for historical retention.
+6. **Key Reintroduced**: Reactivated as `"active"`.
+
+## Stale Detection in Locale Catalogs
+In `messages/<locale>.json`, each entry records:
+```json
+{
+  "checkout.pay_now": {
+    "value": "ಈಗ ಪಾವತಿಸಿ",
+    "source_version": 1,
+    "translated_at": "2026-10-19T10:05:00.000Z",
+    "status": "translated"
+  }
+}
+```
+A translation is **stale** when `entry.source_version < canonicalEntry.key_version`. Stale entries retain their existing translated value for reference until the AI agent updates them.

package/skills/nextjs-localization-and-translation-i18n/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: nextjs-localization-and-translation-i18n
+description: Next.js-specific localization and translation workflow using next-intl and Shallok CLI (shallok). Covers App Router and Pages Router, Server and Client Components, routing middleware, context enrichment, direct agent translation without external API keys, runtime bundle compilation, and validation.
+---
+
+# Next.js Localization & Translation Skill (`next-intl`)
+
+Use this skill when asked to add, configure, update, or audit localization in **Next.js applications** (Next.js 13, 14, 15+ App Router or Pages Router).
+
+## Two Ways Developers Use Shallok
+
+1. **Via CLI (`npx shallok init`)**: The developer runs `npx shallok init` in their project. Shallok initializes the catalogs, installs `shallok` into `devDependencies`, and adds this skill directly into `.agents/skills/` and `skills/`.
+2. **Direct Skill Installation**: The developer installs or links this skill into their AI coding agent and directly asks: *"Add localization to this application"* or *"Translate into Kannada and Hindi"*.
+
+---
+
+## Agent Step 0: Verify & Install Shallok CLI
+
+**Before executing any localization commands, you (the AI Agent) MUST verify that `shallok` is available:**
+
+1. Check `package.json` for `"shallok"` in `devDependencies` or run:
+   ```bash
+   npx shallok --version
+   ```
+2. **If `shallok` is NOT installed, install it immediately** using the project's package manager:
+   - If `pnpm-lock.yaml` exists: `pnpm add -D shallok`
+   - If `yarn.lock` exists: `yarn add -D shallok`
+   - If `bun.lockb` / `bun.lock` exists: `bun add -d shallok`
+   - Otherwise: `npm install -D shallok`
+   *(Alternatively, run commands directly via `npx shallok <command>`)*
+
+---
+
+## Architecture & Agent Role
+
+Shallok pairs a deterministic AST CLI (`shallok`) with **the AI Agent as the semantic translator and context enricher**:
+
+1. **The CLI (`shallok`)** handles deterministic tasks:
+   - Scaffolds Next.js configuration files: `src/i18n/routing.ts` and `src/i18n/request.ts`.
+   - AST parses Next.js JSX/TSX components (`shallok extract`).
+   - Replaces user-facing strings with `{t('key')}` and imports `useTranslations` (`shallok extract --apply`).
+   - Maintains per-key versioning and SHA-256 content hashes in `localization_base/`.
+   - Compiles runtime message bundles to `messages/runtime/<locale>.json` (`shallok build`).
+   - Validates 0 missing keys, 0 stale versions, and 0 broken placeholders (`shallok validate`).
+
+2. **The AI Agent (You)** provides semantic intelligence:
+   - **No external API keys required**: You generate natural, culturally authentic translations directly into target languages (e.g. Kannada, Hindi, Spanish, French, German).
+   - **Context Enrichment**: You inspect Next.js Server Components, Client Components, and layout hierarchies to provide rich, descriptive `context` in `localization_base/` for each key.
+   - **Integrity**: You preserve all interpolation tokens (`{userName}`, `{count}`, `{amount}`) exactly as they appear in the source text.
+
+---
+
+## 6-Phase Agent Workflow for Next.js
+
+### Phase A: Analyze
+Inspect repository architecture without modifying files:
+```bash
+shallok analyze --json
+```
+- Verify framework is detected as `nextjs`.
+- Check Next.js version in `package.json` (`dependencies.next`).
+- Check router type:
+  - **App Router**: `app/` directory exists (with or without `src/`).
+  - **Pages Router**: `pages/` directory exists.
+- Identify candidate page and component files (`app/**/*.tsx`, `src/**/*.tsx`).
+- Note user-requested target locales (e.g. `kn`, `hi`, `fr`, `es`).
+- **Never edit files during Phase A.**
+
+### Phase B: Plan and Review
+Present a concise plan to the developer:
+1. **Framework & Library**: Next.js with `next-intl`.
+2. **Locales**: Source locale (e.g. `en`) and target locales (e.g. `kn` Kannada, `hi` Hindi).
+3. **Dependencies to Install**:
+   ```bash
+   pnpm add next-intl
+   ```
+4. **Planned Scaffolding**:
+   - `localization.json` (Project manifest)
+   - `src/i18n/routing.ts` (Routing definition for `next-intl`)
+   - `src/i18n/request.ts` (Request configuration for server-side loading)
+   - `middleware.ts` (Locale detection and URL rewriting)
+   - `localization_base/<source_locale>.json` & `metadata.json` (Canonical catalog & versions)
+   - `messages/<locale>.json` (Authoritative target catalogs)
+   - `messages/runtime/<locale>.json` (Compiled runtime message bundles)
+5. **App Structure Updates**:
+   - Nest routes under `app/[locale]/...`
+   - Setup `NextIntlClientProvider` in `app/[locale]/layout.tsx` for client components
+6. Confirm with user before proceeding (or proceed if `--yes` / requested).
+
+### Phase C: Initialize
+Initialize configuration and Next.js scaffolding:
+```bash
+shallok init --source en --locales kn,hi --framework nextjs --yes
+```
+This automatically creates:
+- `localization.json`
+- `src/i18n/routing.ts`
+- `src/i18n/request.ts`
+- Initial catalogs in `localization_base/` and `messages/`
+- Installs `shallok` in `devDependencies` and copies skills
+
+Ensure dependencies are installed:
+```bash
+pnpm add next-intl
+```
+
+### Phase D: Extract & Enrich Context (AI-Driven)
+1. **Preview proposed extraction**:
+   ```bash
+   shallok extract --dry-run --json
+   ```
+2. **Extract strings to canonical catalog**:
+   ```bash
+   shallok extract
+   ```
+   This extracts text and JSX expressions to `localization_base/en.json`.
+
+3. **Enrich Context (Performed by AI Agent)**:
+   - Review `localization_base/en.json`.
+   - Inspect the Next.js page or component where each key originates.
+   - Enrich `context` with semantic clarity (e.g. *"Dashboard banner heading welcoming returning user"*).
+   - Use the CLI:
+     ```bash
+     shallok context set <key> "<semantic_description>"
+     ```
+     Or edit `"context"` directly in `localization_base/en.json`.
+   - **Preservation Guarantee**: Shallok's reconciliation algorithm strictly preserves your enriched context across all future extractions.
+
+### Phase E: Translate (AI-Driven)
+**No external API keys or LLM provider subscriptions are required.**
+You, as the AI coding agent, generate the translations directly:
+
+1. **Check translation status**:
+   ```bash
+   shallok status --json
+   ```
+   Identify keys in `messages/<locale>.json` marked with `status: "missing"` or `status: "stale"`.
+
+2. **Generate Natural Translations**:
+   - Translate each string into culturally authentic target language (e.g. Kannada, Hindi).
+   - Use the source `content` and your enriched `context` for accurate terminology.
+   - **Strict Rule**: Preserve all interpolation tokens (`{count}`, `{name}`, `{date}`) exactly as formatted in the source text.
+
+3. **Update Target Locale Catalogs**:
+   Write directly into `messages/<locale>.json` or use:
+   ```bash
+   shallok entry set <locale> <key> "<translated_text>"
+   ```
+
+### Phase F: Apply, Build & Validate
+1. **Transform Next.js source components**:
+   ```bash
+   shallok extract --apply
+   ```
+2. **Verify Next.js Integration Files**:
+   - `middleware.ts` configured with `next-intl/middleware`.
+   - `next.config.mjs` with `createNextIntlPlugin`.
+3. **Compile runtime message bundles**:
+   ```bash
+   shallok build
+   ```
+4. **Validate catalog integrity**:
+   ```bash
+   shallok validate
+   ```
+   Verifies 0 missing translations, 0 stale versions, 0 dropped or mismatched placeholders.

package/skills/nextjs-localization-and-translation-i18n/references/extraction.md

@@ -0,0 +1,29 @@
+# AST Extraction Reference
+
+## Extraction Strategy
+Shallok uses Babel AST parsing (`@babel/parser` and `@babel/traverse`) with full JSX and TypeScript support to safely inspect and transform source files without regular expressions.
+
+## What is Extracted
+1. **JSX Text Nodes**:
+   - `<h1>Welcome</h1>` → `{t('home.welcome')}`
+   - `<button>Pay now</button>` → `<button>{t('checkout.pay_now')}</button>`
+2. **User-Facing Attributes**:
+   - `placeholder="Enter your email"`
+   - `aria-label="Submit login form"`
+   - `title="Cart summary"`
+   - `alt="Product thumbnail"`
+   - `label="Password"`
+3. **Conditional UI Expressions**:
+   - `{isMember ? 'VIP Member' : 'Guest User'}`
+4. **Template Literals with Variables**:
+   - `Hello, ${name}!` → `Hello, {name}!` with variable preservation.
+
+## What is Explicitly Ignored
+- Technical attributes: `className`, `id`, `name`, `key`, `ref`, `type`, `href`, `src`, `data-testid`, `role`.
+- Console and logger calls: `console.log(...)`, `console.error(...)`, `logger.debug(...)`.
+- URLs, file paths, hex colors, CSS units.
+- Non-user-facing strings, code constants, and symbols.
+- Already localized calls: `t(...)`, `i18n.t(...)`.
+
+## Dry-Run Mode
+Always use `localize extract --dry-run` to preview keys and occurrences before committing changes to source files.

package/skills/nextjs-localization-and-translation-i18n/references/next-intl.md

@@ -0,0 +1,63 @@
+# Next.js & next-intl Technical Reference
+
+## Configuration Pattern
+
+### 1. `src/i18n/routing.ts`
+```typescript
+import { defineRouting } from 'next-intl/routing';
+
+export const routing = defineRouting({
+  locales: ['en', 'kn', 'hi'],
+  defaultLocale: 'en',
+});
+```
+
+### 2. `src/i18n/request.ts`
+```typescript
+import { getRequestConfig } from 'next-intl/server';
+import { routing } from './routing';
+
+export default getRequestConfig(async ({ requestLocale }) => {
+  let locale = await requestLocale;
+
+  if (!locale || !routing.locales.includes(locale as any)) {
+    locale = routing.defaultLocale;
+  }
+
+  return {
+    locale,
+    messages: (await import(`../../messages/runtime/${locale}.json`)).default,
+  };
+});
+```
+
+### 3. `middleware.ts`
+```typescript
+import createMiddleware from 'next-intl/middleware';
+import { routing } from './src/i18n/routing';
+
+export default createMiddleware(routing);
+
+export const config = {
+  matcher: ['/', '/(kn|hi|en)/:path*']
+};
+```
+
+## Hook & Async Usage
+- **Server Components**:
+  ```typescript
+  import { getTranslations } from 'next-intl/server';
+  const t = await getTranslations();
+  ```
+- **Client Components**:
+  ```typescript
+  'use client';
+  import { useTranslations } from 'next-intl';
+  const t = useTranslations();
+  ```
+- **Navigation**:
+  ```typescript
+  import { createNavigation } from 'next-intl/navigation';
+  import { routing } from './routing';
+  export const { Link, redirect, usePathname, useRouter } = createNavigation(routing);
+  ```

package/skills/nextjs-localization-and-translation-i18n/references/translation.md

@@ -0,0 +1,45 @@
+# Translation Engine & Agent-Native Translation Reference
+
+## Agent-Native Translation (Primary Workflow)
+When using Shallok via an AI coding agent (e.g., in Claude, Cursor, Copilot, Antigravity):
+- **No external API keys or LLM provider subscriptions are needed.**
+- The AI agent itself generates accurate, natural translations for each target locale.
+- The AI agent inspects `messages/<locale>.json` or runs `localize status --json` to identify entries with `status: "missing"` or `status: "stale"`.
+- The AI agent writes the translated strings into `messages/<locale>.json` (or uses `localize entry set <locale> <key> "<translated_text>"`).
+
+### Translation Schema
+Each entry in `messages/<locale>.json` maintains:
+```json
+{
+  "checkout.pay_now": {
+    "value": "ಈಗ ಪಾವತಿಸಿ",
+    "source_version": 1,
+    "translated_at": "2026-10-19T14:00:00.000Z",
+    "status": "translated"
+  }
+}
+```
+
+### Supported Statuses
+- `missing`: Key exists in canonical catalog but has no translation.
+- `stale`: Key source version was incremented; old translation preserved for reference.
+- `translated`: Translated and matching the current canonical `source_version`.
+- `review_required`: Flagged for human review.
+- `approved`: Formally approved translation.
+
+---
+
+## Placeholder Preservation Rules
+The AI agent must strictly preserve all interpolation placeholders in target translations:
+- Source: `"Welcome back, {userName}! You have {itemCount} items in your cart."`
+- Kannada: `"ಮರಳಿ ಸ್ವಾಗತ, {userName}! ನಿಮ್ಮ ಕಾರ್ಟ್‌ನಲ್ಲಿ {itemCount} ಐಟಂಗಳು ಇವೆ."`
+- Hindi: `"वापसी पर स्वागत है, {userName}! आपके कार्ट में {itemCount} आइटम हैं।"`
+
+If a translation drops a placeholder or introduces an invalid placeholder, `localize validate` will fail with an error.
+
+---
+
+## CLI-Based Translation (Optional / Fallback)
+For automated pipelines or scripts running outside an interactive AI agent:
+1. **Mock Provider (`mock`)**: Default provider with built-in dictionary for local development and CI testing.
+2. **LLM Provider (`llm`)**: Calls OpenAI, Gemini, or Anthropic HTTP APIs when `TRANSLATION_API_KEY` is provided.

package/skills/nextjs-localization-and-translation-i18n/references/versioning.md

@@ -0,0 +1,57 @@
+# Per-Key Versioning & Context Reference
+
+## Canonical Source Catalog (`localization_base/`)
+The canonical catalog is the single source of truth for all active and obsolete keys, including their cryptographic content hashes and version counters.
+
+### Structure of a Canonical Entry
+```json
+{
+  "checkout.pay_now": {
+    "key": "checkout.pay_now",
+    "content": "Pay now",
+    "context": "Primary action button on checkout screen to trigger payment modal",
+    "relative_file_path": "src/components/checkout.tsx",
+    "occurrences": [
+      {
+        "relative_file_path": "src/components/checkout.tsx",
+        "line": 42,
+        "column": 12
+      }
+    ],
+    "last_updated_at": "2026-10-19T10:00:00.000Z",
+    "key_version": 1,
+    "content_hash": "sha256:...",
+    "status": "active"
+  }
+}
+```
+
+## Context Enrichment by AI Agents
+1. When strings are extracted via `localize extract`, the CLI provides baseline AST context (e.g. `JSX text in <button> (in App <button>)`).
+2. The AI Agent analyzes the source code, component hierarchy, and user flow, and enriches the `context` with semantic clarity:
+   - CLI method: `localize context set <key> "<semantic_description>"`
+   - Direct edit: Update `"context"` in `localization_base/<source_locale>.json`.
+3. **Preservation Guarantee**:
+   Shallok's reconciliation algorithm (`reconcileCanonicalCatalog`) checks if a key already has an enriched context. Unless the source code introduces an explicit inline comment (`{/* context: ... */}`), the AI agent's enriched context is **strictly preserved** across all future extractions and will not be overwritten by generic AST node descriptions.
+
+## Reconciliation & Versioning Rules
+1. **New Key**: Initialized at `key_version = 1`, `status = "active"`.
+2. **Unchanged Content & Context**: `key_version` and `last_updated_at` remain unchanged.
+3. **Modified Source Content**: `key_version` increments by 1; `last_updated_at` is updated.
+4. **File Move / Occurrence Change**: Path and occurrence lines are updated; `key_version` does NOT increment.
+5. **Key Removed from Source**: Marked `status = "obsolete"`; preserved in catalog for historical retention.
+6. **Key Reintroduced**: Reactivated as `"active"`.
+
+## Stale Detection in Locale Catalogs
+In `messages/<locale>.json`, each entry records:
+```json
+{
+  "checkout.pay_now": {
+    "value": "ಈಗ ಪಾವತಿಸಿ",
+    "source_version": 1,
+    "translated_at": "2026-10-19T10:05:00.000Z",
+    "status": "translated"
+  }
+}
+```
+A translation is **stale** when `entry.source_version < canonicalEntry.key_version`. Stale entries retain their existing translated value for reference until the AI agent updates them.

package/skills/react-localization-and-translation-i18n/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: react-localization-and-translation-i18n
+description: React-specific localization and translation workflow using react-i18next and Shallok CLI (shallok). Guides AI coding agents through AST extraction of React JSX/TSX components, context enrichment, direct agent translation without external API keys, runtime bundle compilation, and validation.
+---
+
+# React Localization & Translation Skill (`react-i18next`)
+
+Use this skill when asked to add, configure, update, or audit localization in **React applications** (Vite, Create React App, Webpack, SPAs).
+
+## Two Ways Developers Use Shallok
+
+1. **Via CLI (`npx shallok init`)**: The developer runs `npx shallok init` in their project. Shallok initializes the catalogs, installs `shallok` into `devDependencies`, and adds this skill directly into `.agents/skills/` and `skills/`.
+2. **Direct Skill Installation**: The developer installs or links this skill into their AI coding agent and directly asks: *"Add localization to this application"* or *"Translate into Kannada and Hindi"*.
+
+---
+
+## Agent Step 0: Verify & Install Shallok CLI
+
+**Before executing any localization commands, you (the AI Agent) MUST verify that `shallok` is available:**
+
+1. Check `package.json` for `"shallok"` in `devDependencies` or run:
+   ```bash
+   npx shallok --version
+   ```
+2. **If `shallok` is NOT installed, install it immediately** using the project's package manager:
+   - If `pnpm-lock.yaml` exists: `pnpm add -D shallok`
+   - If `yarn.lock` exists: `yarn add -D shallok`
+   - If `bun.lockb` / `bun.lock` exists: `bun add -d shallok`
+   - Otherwise: `npm install -D shallok`
+   *(Alternatively, run commands directly via `npx shallok <command>`)*
+
+---
+
+## Architecture & Agent Role
+
+Shallok pairs a deterministic AST CLI (`shallok`) with **the AI Agent as the semantic translator and context enricher**:
+
+1. **The CLI (`shallok`)** handles deterministic tasks:
+   - Scaffolds `src/i18n.ts` configuring `react-i18next`.
+   - AST parses React JSX/TSX components (`shallok extract`).
+   - Replaces user-facing strings and JSX elements with `{t('key')}` and imports `useTranslation` (`shallok extract --apply`).
+   - Maintains per-key versioning and SHA-256 content hashes in `localization_base/`.
+   - Compiles runtime message bundles to `messages/runtime/<locale>.json` (`shallok build`).
+   - Validates 0 missing keys, 0 stale versions, and 0 broken placeholders (`shallok validate`).
+
+2. **The AI Agent (You)** provides semantic intelligence:
+   - **No external API keys required**: You generate natural, culturally authentic translations directly into target languages (e.g. Kannada, Hindi, Spanish, French, German).
+   - **Context Enrichment**: You inspect React components, state flows, and screen layouts to provide rich, descriptive `context` in `localization_base/` for each key.
+   - **Integrity**: You preserve all interpolation tokens (`{userName}`, `{count}`, `{amount}`) exactly as they appear in the source text.
+
+---
+
+## 6-Phase Agent Workflow for React
+
+### Phase A: Analyze
+Inspect repository architecture without modifying files:
+```bash
+shallok analyze --json
+```
+- Verify framework is detected as `react`.
+- Check React version in `package.json` (`dependencies.react`).
+- Identify source directory (typically `src/`) and entry file (`src/main.tsx`, `src/index.tsx`, or `src/App.tsx`).
+- Identify candidate React component files (`src/**/*.tsx`, `src/**/*.jsx`).
+- Note user-requested target locales (e.g. `kn`, `hi`, `fr`, `es`).
+- **Never edit files during Phase A.**
+
+### Phase B: Plan and Review
+Present a concise plan to the developer:
+1. **Framework & Library**: React with `react-i18next` and `i18next`.
+2. **Locales**: Source locale (e.g. `en`) and target locales (e.g. `kn` Kannada, `hi` Hindi).
+3. **Dependencies to Install**:
+   ```bash
+   pnpm add i18next react-i18next
+   ```
+4. **Planned Scaffolding**:
+   - `localization.json` (Project manifest)
+   - `src/i18n.ts` (React-i18next configuration)
+   - `localization_base/<source_locale>.json` & `metadata.json` (Canonical catalog & versions)
+   - `messages/<locale>.json` (Target locale catalogs)
+   - `messages/runtime/<locale>.json` (Compiled runtime bundles)
+5. **Entry Point Integration**: Adding `import './i18n';` in `src/main.tsx` (or `src/index.tsx`).
+6. Confirm with user before proceeding (or proceed if `--yes` / requested).
+
+### Phase C: Initialize
+Initialize configuration and React scaffolding:
+```bash
+shallok init --source en --locales kn,hi --framework react --yes
+```
+This automatically creates:
+- `localization.json`
+- `src/i18n.ts`
+- Initial catalogs in `localization_base/` and `messages/`
+- Installs `shallok` in `devDependencies` and copies skills
+
+Ensure React runtime dependencies are installed:
+```bash
+pnpm add i18next react-i18next
+```
+
+### Phase D: Extract & Enrich Context (AI-Driven)
+1. **Preview proposed extraction**:
+   ```bash
+   shallok extract --dry-run --json
+   ```
+2. **Extract strings to canonical catalog**:
+   ```bash
+   shallok extract
+   ```
+   This populates `localization_base/en.json` with extracted keys and initial AST locations.
+
+3. **Enrich Context (Performed by AI Agent)**:
+   - Review `localization_base/en.json`.
+   - Inspect the React component code where each key is used.
+   - Enrich `context` with semantic clarity (e.g. *"Primary CTA button inside CheckoutModal component to submit credit card payment"*).
+   - Use the CLI:
+     ```bash
+     shallok context set <key> "<semantic_description>"
+     ```
+     Or edit `"context"` directly in `localization_base/en.json`.
+   - **Preservation Guarantee**: Shallok's reconciliation algorithm strictly preserves your enriched context across all future extractions.
+
+### Phase E: Translate (AI-Driven)
+**No external API keys or LLM provider subscriptions are required.**
+You, as the AI coding agent, generate the translations directly:
+
+1. **Check translation status**:
+   ```bash
+   shallok status --json
+   ```
+   Identify keys in `messages/<locale>.json` marked with `status: "missing"` or `status: "stale"`.
+
+2. **Generate Natural Translations**:
+   - Translate each string into culturally authentic target language (e.g. Kannada, Hindi).
+   - Use the source `content` and your enriched `context` for accurate terminology.
+   - **Strict Rule**: Preserve all interpolation tokens (`{count}`, `{name}`, `{date}`) exactly as formatted in the source text.
+
+3. **Update Target Locale Catalogs**:
+   Write directly into `messages/<locale>.json` or use:
+   ```bash
+   shallok entry set <locale> <key> "<translated_text>"
+   ```
+   Example catalog entry:
+   ```json
+   {
+     "checkout.pay_now": {
+       "value": "ಈಗ ಪಾವತಿಸಿ",
+       "source_version": 1,
+       "translated_at": "2026-10-19T14:00:00.000Z",
+       "status": "translated"
+     }
+   }
+   ```
+
+### Phase F: Apply, Build & Validate
+1. **Transform React source components**:
+   ```bash
+   shallok extract --apply
+   ```
+   This injects `const { t } = useTranslation();` and replaces hardcoded text with `{t('key')}`.
+
+2. **Verify Entry Point Integration**:
+   Ensure `src/main.tsx` or `src/index.tsx` imports the i18n configuration:
+   ```tsx
+   import React from 'react';
+   import ReactDOM from 'react-dom/client';
+   import App from './App';
+   import './i18n'; // <-- Must be imported before rendering
+   ```
+
+3. **Compile runtime message bundles**:
+   ```bash
+   shallok build
+   ```
+   Compiles clean dictionaries into `messages/runtime/<locale>.json`.
+
+4. **Validate catalog integrity**:
+   ```bash
+   shallok validate
+   ```
+   Verifies:
+   - 0 missing translations.
+   - 0 stale versions.
+   - 0 dropped or mismatched placeholders.
+
+5. **Summarize results**:
+   Present modified components, added locales, completeness, and verification state.
+
+---
+
+## React Code Patterns & Best Practices
+
+### 1. Component Transformation
+Before:
+```tsx
+export function Hero() {
+  return (
+    <div>
+      <h1>Welcome to our store</h1>
+      <input placeholder="Search products..." />
+    </div>
+  );
+}
+```
+
+After (`shallok extract --apply`):
+```tsx
+import { useTranslation } from 'react-i18next';
+
+export function Hero() {
+  const { t } = useTranslation();
+  return (
+    <div>
+      <h1>{t('hero.welcome_title')}</h1>
+      <input placeholder={t('hero.search_placeholder')} />
+    </div>
+  );
+}
+```
+
+### 2. Language Switcher Component
+```tsx
+import { useTranslation } from 'react-i18next';
+
+export function LanguageSwitcher() {
+  const { i18n } = useTranslation();
+
+  const changeLanguage = (lng: string) => {
+    i18n.changeLanguage(lng);
+    document.documentElement.lang = lng;
+    document.documentElement.dir = ['ar', 'he', 'fa', 'ur'].includes(lng) ? 'rtl' : 'ltr';
+  };
+
+  return (
+    <div className="language-switcher">
+      <button onClick={() => changeLanguage('en')} disabled={i18n.language === 'en'}>
+        English
+      </button>
+      <button onClick={() => changeLanguage('kn')} disabled={i18n.language === 'kn'}>
+        ಕನ್ನಡ
+      </button>
+      <button onClick={() => changeLanguage('hi')} disabled={i18n.language === 'hi'}>
+        हिंदी
+      </button>
+    </div>
+  );
+}
+```
+
+---
+
+## Maintenance Workflows
+
+- **Add a new language**:
+  ```bash
+  shallok locale add es
+  ```
+  Translate active keys into `messages/es.json`, then run `shallok build && shallok validate`.
+
+- **Source wording changed in a React component**:
+  Run `shallok extract`. Modified strings automatically increment `key_version` and flag target translations as `stale`. Translate the changed string, then run `shallok build`.
+
+- **Rename a key**:
+  ```bash
+  shallok key rename old.key.name new.key.name
+  shallok build
+  ```