shallok 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "shallok",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "AI-Powered, Versioned Localization Tool for AI Coding Agents",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "shallok": "./dist/index.js",
+    "localize": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Hypermona/Shallok.git"
+  },
+  "keywords": [
+    "i18n",
+    "localization",
+    "internationalization",
+    "translation",
+    "ai-agent",
+    "nextjs",
+    "react",
+    "expo",
+    "astro",
+    "ast"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup && node scripts/copy-skills.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@shallok/core": "workspace:*",
+    "@shallok/framework-adapters": "workspace:*",
+    "@shallok/translation-providers": "workspace:*",
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "dotenv": "^16.4.7",
+    "ink": "^5.1.0",
+    "ora": "^8.2.0",
+    "react": "^18.3.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.8",
+    "@types/react": "^18.3.18",
+    "tsup": "^9.0.0",
+    "typescript": "^5.7.3"
+  }
+}

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

@@ -0,0 +1,164 @@
+---
+name: astro-localization-and-translation-i18n
+description: Astro-specific localization and translation workflow using astro:i18n and Shallok CLI (shallok). Covers static routing with [locale], Astro frontmatter useTranslations, client UI islands (React/Vue/Svelte), context enrichment, direct agent translation without external API keys, and validation.
+---
+
+# Astro Localization & Translation Skill (`astro:i18n`)
+
+Use this skill when asked to add, configure, update, or audit localization in **Astro websites and web applications** (Static SSG, Hybrid, or SSR).
+
+## 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/utils.ts` integrating with `astro:i18n`.
+   - AST parses Astro templates and UI islands (`shallok extract`).
+   - Replaces user-facing strings with `{t('key')}` (`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 Astro `.astro` pages, layouts, markdown collections, and interactive islands 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 Astro
+
+### Phase A: Analyze
+Inspect repository architecture without modifying files:
+```bash
+shallok analyze --json
+```
+- Verify framework is detected as `astro`.
+- Check `astro.config.mjs` (or `.ts`) for existing `i18n` block.
+- Identify page routing structure (`src/pages/`, `src/pages/[locale]/`).
+- Identify interactive islands (React, Vue, Svelte, Solid components).
+- 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 & Approach**: Astro with built-in `astro:i18n` and Shallok runtime translation helper (`src/i18n/utils.ts`).
+2. **Locales**: Source locale (e.g. `en`) and target locales (e.g. `kn` Kannada, `hi` Hindi).
+3. **Planned Scaffolding**:
+   - `localization.json` (Project manifest)
+   - `src/i18n/utils.ts` (Translation helper and locale type definitions)
+   - `astro.config.mjs` i18n configuration
+   - `localization_base/<source_locale>.json` & `metadata.json` (Canonical catalog & versions)
+   - `messages/<locale>.json` (Authoritative target catalogs)
+   - `messages/runtime/<locale>.json` (Compiled runtime message bundles)
+4. **Routing Structure**:
+   - Localized routes under `src/pages/[locale]/...`
+   - Default locale route under `src/pages/` or prefixed.
+5. Confirm with user before proceeding (or proceed if `--yes` / requested).
+
+### Phase C: Initialize
+Initialize configuration and Astro scaffolding:
+```bash
+shallok init --source en --locales kn,hi --framework astro --yes
+```
+This automatically creates:
+- `localization.json`
+- `src/i18n/utils.ts`
+- Initial catalogs in `localization_base/` and `messages/`
+- Installs `shallok` in `devDependencies` and copies skills
+
+Ensure `astro.config.mjs` specifies the locales:
+```javascript
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en', 'kn', 'hi'],
+    routing: {
+      prefixDefaultLocale: false,
+    },
+  },
+});
+```
+
+### 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 expressions into `localization_base/en.json`.
+
+3. **Enrich Context (Performed by AI Agent)**:
+   - Review `localization_base/en.json`.
+   - Inspect the `.astro` page or component where each key originates.
+   - Enrich `context` with semantic clarity (e.g. *"Landing page hero subtitle describing product mission"*).
+   - 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 Astro source pages & components**:
+   ```bash
+   shallok extract --apply
+   ```
+2. **Compile runtime message bundles**:
+   ```bash
+   shallok build
+   ```
+3. **Validate catalog integrity**:
+   ```bash
+   shallok validate
+   ```

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

@@ -0,0 +1,40 @@
+# Astro & astro:i18n Technical Reference
+
+## Configuration Pattern
+
+### 1. `astro.config.mjs`
+```javascript
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en', 'kn', 'hi'],
+    routing: {
+      prefixDefaultLocale: false,
+    },
+  },
+});
+```
+
+### 2. `src/i18n/utils.ts`
+```typescript
+export const defaultLocale = 'en';
+export const locales = ['en', 'kn', 'hi'] as const;
+
+export type Locale = (typeof locales)[number];
+
+export async function useTranslations(locale: Locale) {
+  const messages = (await import(`../../messages/runtime/${locale}.json`)).default;
+
+  return function t(key: string): string {
+    return (messages as Record<string, string>)[key] || key;
+  };
+}
+```
+
+## Routing Conventions
+- Root / Default Locale: `src/pages/index.astro`
+- Subpath / Translated Locales: `src/pages/[locale]/index.astro`
+- Current Locale Access: `Astro.currentLocale`
+- Preferred Locale Detection: `Astro.preferredLocale`

package/skills/astro-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/astro-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/astro-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/expo-localization-and-translation-i18n/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: expo-localization-and-translation-i18n
+description: Expo and React Native localization and translation workflow using expo-localization, i18next, and Shallok CLI (shallok). Covers device language detection via getLocales(), mobile Text/TextInput transformations, Metro-bundled runtime messages, context enrichment, direct agent translation without external API keys, and validation.
+---
+
+# Expo & React Native Localization Skill (`expo-localization` + `react-i18next`)
+
+Use this skill when asked to add, configure, update, or audit localization in **Expo and React Native mobile applications** (Expo Router, React Navigation, bare React Native).
+
+## 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 `i18n.ts` configuring `expo-localization` and `i18next`.
+   - AST parses mobile React Native components (`shallok extract`).
+   - Replaces user-facing strings in `<Text>`, `<TextInput>`, and props with `{t('key')}` (`shallok extract --apply`).
+   - Maintains per-key versioning and SHA-256 content hashes in `localization_base/`.
+   - Compiles static runtime message bundles to `messages/runtime/<locale>.json` for Metro bundling (`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 mobile translations directly into target languages (e.g. Kannada, Hindi, Spanish, French, German).
+   - **Context Enrichment**: You inspect mobile screens, modals, navigation stacks, and touch targets 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 Expo
+
+### Phase A: Analyze
+Inspect repository architecture without modifying files:
+```bash
+shallok analyze --json
+```
+- Verify framework is detected as `expo` (or `react-native`).
+- Inspect `package.json` for Expo SDK version and navigation library (Expo Router `expo-router` or `@react-navigation`).
+- Identify mobile entry point (`App.tsx`, `index.js`, or `app/_layout.tsx`).
+- Identify candidate screen and component files (`src/**/*.tsx`, `app/**/*.tsx`, `components/**/*.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 & Libraries**: Expo / React Native with `expo-localization`, `i18next`, and `react-i18next`.
+2. **Locales**: Source locale (e.g. `en`) and target locales (e.g. `kn` Kannada, `hi` Hindi).
+3. **Dependencies to Install**:
+   ```bash
+   npx expo install expo-localization
+   pnpm add i18next react-i18next
+   ```
+4. **Planned Scaffolding**:
+   - `localization.json` (Project manifest)
+   - `i18n.ts` (Mobile i18n initialization at root)
+   - `localization_base/<source_locale>.json` & `metadata.json` (Canonical catalog & versions)
+   - `messages/<locale>.json` (Authoritative target catalogs)
+   - `messages/runtime/<locale>.json` (Static runtime bundles imported by Metro)
+5. **Root Integration**: Adding `import './i18n';` in `App.tsx` or `app/_layout.tsx`.
+6. Confirm with user before proceeding (or proceed if `--yes` / requested).
+
+### Phase C: Initialize
+Initialize configuration and Expo scaffolding:
+```bash
+shallok init --source en --locales kn,hi --framework expo --yes
+```
+This automatically creates:
+- `localization.json`
+- `i18n.ts` (with `getLocales()` device language detection)
+- Initial catalogs in `localization_base/` and `messages/`
+- Installs `shallok` in `devDependencies` and copies skills
+
+Ensure mobile dependencies are installed:
+```bash
+npx expo install expo-localization
+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 extracts text inside `<Text>`, `<Button title="...">`, and `<TextInput placeholder="...">` into `localization_base/en.json`.
+
+3. **Enrich Context (Performed by AI Agent)**:
+   - Review `localization_base/en.json`.
+   - Inspect the mobile screen and component context.
+   - Enrich `context` with semantic clarity (e.g. *"Header label on Bluetooth pairing bottom sheet modal"*).
+   - 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).
+   - Keep mobile screen space constraints in mind (e.g. concise button labels).
+   - 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 React Native components**:
+   ```bash
+   shallok extract --apply
+   ```
+   This injects `const { t } = useTranslation();` and replaces hardcoded text with `{t('key')}`.
+
+2. **Verify Root Entry Integration**:
+   Ensure `App.tsx` or `app/_layout.tsx` imports `i18n.ts`:
+   ```tsx
+   import './i18n'; // <-- Must be at the top of the entry file
+   ```
+
+3. **Compile runtime message bundles**:
+   ```bash
+   shallok build
+   ```
+   Compiles static 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.

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

@@ -0,0 +1,46 @@
+# Expo & React Native Technical Reference
+
+## Configuration Pattern (`i18n.ts`)
+React Native applications require static message loading because dynamic Node.js filesystem operations (`fs.readFile`) are not available in native runtimes.
+
+```typescript
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+import { getLocales } from 'expo-localization';
+
+import enMessages from './messages/runtime/en.json';
+import knMessages from './messages/runtime/kn.json';
+import hiMessages from './messages/runtime/hi.json';
+
+const resources = {
+  en: { translation: enMessages },
+  kn: { translation: knMessages },
+  hi: { translation: hiMessages },
+};
+
+const deviceLanguage = getLocales()[0]?.languageCode ?? 'en';
+
+i18n
+  .use(initReactI18next)
+  .init({
+    resources,
+    lng: deviceLanguage,
+    fallbackLng: 'en',
+    interpolation: {
+      escapeValue: false,
+    },
+  });
+
+export default i18n;
+```
+
+## React Native Component Rules
+1. **Text Nodes**:
+   Raw strings cannot exist outside `<Text>` in React Native.
+   - Correct: `<Text>{t('auth.title')}</Text>`
+   - Incorrect: `<div>{t('auth.title')}</div>`
+2. **Prop Localizations**:
+   - `<TextInput placeholder={t('form.email')} />`
+   - `<Button title={t('actions.submit')} />`
+3. **Alerts & Modals**:
+   - `Alert.alert(t('common.confirm'), t('dialog.delete_body'))`

package/skills/expo-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.