shallok 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shallok",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "AI-Powered, Versioned Localization Tool for AI Coding Agents",
   "license": "MIT",
   "type": "module",
@@ -37,14 +37,10 @@
   "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:*",
+    "@shallok/core": "0.1.0",
+    "@shallok/framework-adapters": "0.1.0",
+    "@shallok/translation-providers": "0.1.0",
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
     "dotenv": "^16.4.7",
@@ -58,5 +54,9 @@
     "@types/react": "^18.3.18",
     "tsup": "^9.0.0",
     "typescript": "^5.7.3"
+  },
+  "scripts": {
+    "build": "tsup && node scripts/copy-skills.js",
+    "typecheck": "tsc --noEmit"
   }
-}
+}

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

@@ -14,20 +14,86 @@ Use this skill when asked to add, configure, update, or audit localization in **
 
 ---
 
-## Agent Step 0: Verify & Install Shallok CLI
+## Agent Step 0: Mandatory Pre-Flight Checklist (Run Before ANY Code or Config Changes)
+
+**Before making ANY changes to a new repo or an existing repo, you (the AI Agent) MUST execute the following checks in order:**
+
+### 1. Check if Shallok is Installed
+- Inspect `package.json` for `"shallok"` or `"@shallok/cli"` in `devDependencies` (or `dependencies`), or run:
+  ```bash
+  npx shallok --version
+  ```
+- **If `shallok` is NOT installed, install it immediately into `devDependencies`:**
+  - 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`
+
+### 2. Check if `localization.json` and `localization_base/` Exist
+- Verify that `localization.json` exists in the project root.
+- Verify that the `localization_base/` directory exists with `<source_locale>.json` and `metadata.json`.
+- **If either does NOT exist, create them using Shallok:**
+  ```bash
+  shallok init --source en --locales kn,hi --framework astro --yes
+  ```
+
+### 3. NEVER Delete `localization.json` or `localization_base/`
+> [!CAUTION]
+> **CRITICAL PERSISTENCE RULE: NEVER DELETE `localization.json` OR `localization_base/`!**
+> - `localization.json` is the single source-of-truth project manifest.
+> - `localization_base/` contains the canonical catalog (`<source_locale>.json`) with per-key version numbers (`key_version`), cryptographic content hashes (`sha256:`), source code occurrences, and enriched semantic context, alongside `metadata.json`.
+> - **Under NO circumstances should you EVER delete `localization.json` or `localization_base/`**. Deleting them destroys the versioning history, wipes out human- and AI-enriched context, resets version counters, breaks incremental translation, and corrupts catalog synchronization.
 
-**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>`)*
+## Core Architectural & Formatting Rules
+
+### Rule 1: Always Use Normalized Paths for Keys (Never Object-Based Paths)
+- **Always use normalized dot-separated key paths**: e.g., `"auth.login.title"`, `"checkout.pay_now"`, `"settings.profile.change_password"`.
+- **Never use nested object-based paths**: Do not structure keys or catalogs as nested JSON objects (e.g., `{ "auth": { "login": { "title": "..." } } }`). All keys in `localization_base/<source_locale>.json`, `messages/<locale>.json`, and runtime bundles MUST be flat normalized string paths.
+- **If an existing project is using object-based keys**:
+  - **STOP and ask the user** for confirmation to flatten them into normalized dot-separated key paths before proceeding with extraction or catalog edits.
+  - Explain that normalized dot-paths are required for deterministic AST extraction, per-key versioning, and collision-free reconciliation.
+  - Upon user approval, migrate and flatten all nested keys to normalized dot-paths.
+
+### Rule 2: Always Use the `messages/` Directory Structure (Ask User & Migrate If Different)
+- **Standard translations folder**: Shallok strictly standardizes on `messages/` for authoritative locale catalogs (`messages/<locale>.json`) and compiled runtime bundles (`messages/runtime/<locale>.json`).
+- **If the project uses any other folder structure** (e.g., `locales/`, `src/locales/`, `translations/`, `lang/`, `src/i18n/locales/`):
+  - **STOP and ask the user** for approval to switch to the standardized `messages/` directory structure.
+  - Upon user approval, **migrate** all existing translation files into `messages/`, update framework configuration and import paths, reconcile existing strings into `localization_base/`, and clean up the old directory.
+
+### Rule 3: Check Context for All Keys in `localization_base/{source_locale}` Before Translating
+- **Before generating any translations for any target locale**:
+  - Inspect all active keys in `localization_base/<source_locale>.json` (e.g., `localization_base/en.json`).
+  - Verify that **every key has meaningful, accurate semantic `context`**.
+  - If any key lacks context, has an empty context (`""`), or contains only generic AST descriptions (e.g., `"JSX text in button"`), you MUST inspect the component/screen and **generate rich semantic context for all such keys BEFORE generating translations**.
+  - Enrich context via:
+    ```bash
+    shallok context set <key> "<semantic_description>"
+    ```
+    or directly edit the `"context"` field in `localization_base/<source_locale>.json`.
+
+### Rule 4: Always Generate Translations from `localization_base/{source_locale}` and Its Context
+- **Never translate raw strings in isolation**:
+  - All translations MUST be generated directly from `localization_base/<source_locale>.json`, reading BOTH the source string (`content`) and its semantic `context`.
+  - The `context` provides critical disambiguation (grammatical gender, button vs label vs heading, formality, technical terminology).
+  - Strictly preserve all interpolation tokens (`{userName}`, `{count}`, `{amount}`) exactly as formatted in the source `content`.
+
+### Rule 5: Migrate Legacy Base Locale References to Specified Structure
+- **If the Astro project already has an existing localization setup**:
+  - Check how the base/source locale (`source_locale`, e.g., `en`) is imported and loaded.
+  - If any file (e.g. `src/i18n/utils.ts`, `astro.config.mjs`, layout files) is importing a legacy file (such as `src/locales/en.json`, `locales/en.json`, or arbitrary JSON files):
+    1. **Reconcile strings** into `localization_base/<source_locale>.json` and `messages/<source_locale>.json`.
+    2. **Update all code imports and translation helpers** to point to the standardized compiled runtime bundle (`messages/runtime/<locale>.json`).
+    3. Remove or deprecate the legacy base locale file so that Shallok does NOT extract it as source code (preventing false occurrences like `"relative_file_path": "src/locales/en.json"`).
+
+### Rule 6: Astro Architecture: Keep Translations Local for Static SSG & SSR
+- **Recommend keeping translations LOCAL in `messages/runtime/<locale>.json`**:
+  - Astro generates static HTML at build time (SSG) or renders on the server (Hybrid/SSR).
+  - Loading compiled message bundles directly from `messages/runtime/<locale>.json` (via `src/i18n/utils.ts`) guarantees:
+    - **Zero build network overhead**: Static site builds execute without making external HTTP requests.
+    - **Zero runtime latency**: Pre-rendered static pages contain translated text directly in the HTML.
+    - **No CDN failure risk**: Prevents blank or unlocalized pages due to network hiccups.
 
 ---
 
@@ -38,7 +104,7 @@ Shallok pairs a deterministic AST CLI (`shallok`) with **the AI Agent as the sem
 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`).
+   - Replaces user-facing strings with `{t('key')}` using normalized dot-separated key paths (`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`).
@@ -59,6 +125,9 @@ shallok analyze --json
 ```
 - Verify framework is detected as `astro`.
 - Check `astro.config.mjs` (or `.ts`) for existing `i18n` block.
+- Check existing translation catalogs and folders (`locales/`, `src/locales/`, `messages/`).
+- Check if existing base locale is referencing legacy files (e.g., `src/locales/en.json`, `locales/en.json`).
+- Check if existing keys use object-based nesting or normalized dot-paths.
 - 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`).
@@ -68,28 +137,30 @@ shallok analyze --json
 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**:
+3. **Directory & Legacy File Migration**:
+   - If non-standard locale folders or legacy base locale files exist (e.g. `src/locales/en.json`): Propose migrating to `messages/` and updating all import references to `messages/runtime/<locale>.json`.
+   - If object-based keys exist: Explicitly propose flattening to normalized dot-path keys and request user confirmation.
+4. **Loading Strategy Recommendation**:
+   - Recommend keeping translations local in `messages/runtime/` for fast static compilation (SSG) and zero-latency SSR.
+5. **Planned Scaffolding**:
    - `localization.json` (Project manifest)
-   - `src/i18n/utils.ts` (Translation helper and locale type definitions)
+   - `src/i18n/utils.ts` (Translation helper loading from `messages/runtime/`)
    - `astro.config.mjs` i18n configuration
-   - `localization_base/<source_locale>.json` & `metadata.json` (Canonical catalog & versions)
+   - `localization_base/<source_locale>.json` & `metadata.json` (Canonical catalog & versions — **never delete**)
    - `messages/<locale>.json` (Authoritative target catalogs)
    - `messages/runtime/<locale>.json` (Compiled runtime message bundles)
-4. **Routing Structure**:
+6. **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).
+7. 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
+1. If migrating from an existing non-standard folder (e.g., `locales/` or `src/locales/`), copy/migrate existing translations into `messages/` and reconcile into `localization_base/`.
+2. **Update all code references**: Replace legacy imports like `import en from './locales/en.json'` with `messages/runtime/<locale>.json` in `src/i18n/utils.ts`.
 
 Ensure `astro.config.mjs` specifies the locales:
 ```javascript
@@ -117,33 +188,33 @@ export default defineConfig({
    ```
    This extracts text and expressions into `localization_base/en.json`.
 
-3. **Enrich Context (Performed by AI Agent)**:
+3. **Mandatory Context Check & Enrichment (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:
+   - **Verify that every key has proper semantic context**.
+   - If any key lacks context or has only generic AST descriptions, inspect the `.astro` page or component where each key originates and enrich `context` with semantic clarity BEFORE proceeding to translation:
      ```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)
+### Phase E: Translate (AI-Driven from `localization_base/{source_locale}` + Context)
 **No external API keys or LLM provider subscriptions are required.**
 You, as the AI coding agent, generate the translations directly:
 
-1. **Check translation status**:
+1. **Verify Context First**: Ensure all keys in `localization_base/<source_locale>.json` have proper semantic context.
+2. **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).
+3. **Generate Translations from `localization_base/{source_locale}` and Its Context**:
+   - Translate each string into culturally authentic target language (e.g. Kannada, Hindi) reading source `content` AND its semantic `context` from `localization_base/<source_locale>.json`.
    - 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**:
+4. **Update Target Locale Catalogs**:
    Write directly into `messages/<locale>.json` or use:
    ```bash
    shallok entry set <locale> <key> "<translated_text>"
@@ -154,6 +225,8 @@ You, as the AI coding agent, generate the translations directly:
    ```bash
    shallok extract --apply
    ```
+   Replaces hardcoded strings with `{t('key')}` using normalized dot-separated key paths.
+
 2. **Compile runtime message bundles**:
    ```bash
    shallok build

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

@@ -1,5 +1,20 @@
 # Astro & astro:i18n Technical Reference
 
+## Loading Architecture: Local Bundled Loading for Static SSG & SSR
+
+For Astro websites and applications, **always keep translations LOCAL** in `messages/runtime/<locale>.json`.
+- **Zero Build-Time Latency**: Static site generation renders all pages without making external HTTP requests.
+- **Resilient Static Output**: Builds do not fail when third-party CDN or bucket services are unreachable.
+- **Instant Hydration**: HTML pages already include the translated strings directly in the static markup.
+
+### Legacy Base Locale Migration
+If an existing Astro app was importing from `src/locales/en.json` or `locales/en.json`:
+1. Reconcile keys into `localization_base/en.json`.
+2. Update the dynamic import in `src/i18n/utils.ts` to target `../../messages/runtime/${locale}.json`.
+3. Deprecate and remove the old legacy locale folder.
+
+---
+
 ## Configuration Pattern
 
 ### 1. `astro.config.mjs`

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

@@ -3,6 +3,11 @@
 ## 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.
 
+## Normalized Dot-Paths for Keys (Never Object-Based)
+- **Always use normalized dot-separated key paths**: e.g., `"checkout.pay_now"`, `"auth.login.title"`, `"dashboard.metrics.active_users"`.
+- **Never use object-based or nested object paths**: Catalogs must never store nested object trees.
+- **If an existing project uses object-based keys**: Ask the user for confirmation to flatten them to normalized dot-path keys before running extraction or migrating catalogs.
+
 ## What is Extracted
 1. **JSX Text Nodes**:
    - `<h1>Welcome</h1>` → `{t('home.welcome')}`
@@ -26,4 +31,4 @@ Shallok uses Babel AST parsing (`@babel/parser` and `@babel/traverse`) with full
 - 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.
+Always use `shallok extract --dry-run` to preview keys and occurrences before committing changes to source files.

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

@@ -0,0 +1,59 @@
+# Framework Adapters Reference
+
+## Loading Strategies: Local vs. CDN
+
+| Framework Type | Recommended Strategy | Primary Rationale | Configuration & ENV |
+| :--- | :--- | :--- | :--- |
+| **Astro** (`astro:i18n`) | **Local** (`messages/runtime/`) | Static builds (SSG) & SSR; zero network hops, zero build dependency on external services. | Bundled in `src/i18n/utils.ts` |
+| **Next.js** (`next-intl`) | **Local** (`messages/runtime/`) | Server Components & SSR; instant First Contentful Paint, zero latency in Node/Edge. | Bundled in `src/i18n/request.ts` |
+| **Expo / React Native** | **CDN-Backed** (+ Local Fallback) | Instant Over-The-Air (OTA) translation & typo fixes without waiting for App Store review. | `EXPO_PUBLIC_TRANSLATIONS_CDN_URL` + AsyncStorage caching + local fallback |
+| **React SPA** (Vite / CRA) | **CDN-Backed** (+ Local Fallback) | Instant copy updates without rebuilding web bundle. | `VITE_TRANSLATIONS_CDN_URL` + localStorage caching + local fallback |
+
+---
+
+## Supported Frameworks & Adapters
+
+### 1. React (`react-i18next`)
+- **Initialization**: Generates `src/i18n.ts` configuring `i18next` with `initReactI18next`.
+- **Runtime Messages**: Generates clean key-value message files in `messages/runtime/<locale>.json`.
+- **CDN Loading**: Suggest `VITE_TRANSLATIONS_CDN_URL` in `.env` with local `messages/runtime/` fallback and `scripts/upload-locales.mjs`.
+- **Legacy Migration**: If `src/main.tsx` or `src/i18n.ts` imported `src/locales/en.json`, migrate to `messages/runtime/` or CDN loader.
+- **AST Transformation**:
+  - Adds `import { useTranslation } from 'react-i18next';`
+  - Injects `const { t } = useTranslation();` in components
+  - Replaces text with `{t('key')}` using normalized dot-separated key paths.
+
+### 2. Next.js (`next-intl`)
+- **App Router Support**:
+  - Generates `src/i18n/routing.ts` defining `locales` and `defaultLocale`.
+  - Generates `src/i18n/request.ts` using `getRequestConfig` loading local `messages/runtime/<locale>.json`.
+- **Runtime Messages**: Generates runtime message files in `messages/runtime/<locale>.json`.
+- **Loading Strategy**: Local loading recommended for Server Components and SSR.
+- **Legacy Migration**: If `src/i18n/request.ts` or `middleware.ts` imported old locale JSONs, update imports to `messages/runtime/<locale>.json`.
+- **AST Transformation**:
+  - Adds `import { useTranslations } from 'next-intl';`
+  - Injects `const t = useTranslations();` in components
+  - Replaces text with `{t('key')}` using normalized dot-separated key paths.
+
+### 3. Expo / React Native (`expo-localization` + `react-i18next`)
+- **Initialization**: Generates `i18n.ts` using `getLocales` from `expo-localization` and `i18next`.
+- **Runtime Messages**: Generates runtime message files in `messages/runtime/<locale>.json`.
+- **CDN Loading**: Suggest `EXPO_PUBLIC_TRANSLATIONS_CDN_URL` in `.env` with `AsyncStorage` caching and local `messages/runtime/` fallback.
+- **Legacy Migration**: If `app/_layout.tsx` or `src/i18n.ts` imported `src/locales/en.json`, migrate to `messages/runtime/` or CDN loader.
+- **AST Transformation**:
+  - Adds `import { useTranslation } from 'react-i18next';`
+  - Injects `const { t } = useTranslation();` in mobile components
+  - Replaces text inside `<Text>` and attributes like `placeholder` with `{t('key')}` using normalized dot-separated key paths.
+
+### 4. Astro (`astro:i18n`)
+- **Initialization**: Generates `src/i18n/utils.ts` defining `locales`, `defaultLocale`, and `useTranslations` loading local `messages/runtime/<locale>.json`.
+- **Runtime Messages**: Generates runtime message files in `messages/runtime/<locale>.json`.
+- **Loading Strategy**: Local loading recommended for fast static SSG and hybrid SSR.
+- **Legacy Migration**: If `src/i18n/utils.ts` or `.astro` files imported old locale JSONs, update imports to `messages/runtime/<locale>.json`.
+- **Component Usage**:
+  - In Astro components frontmatter: `const t = await useTranslations(locale);`
+  - Renders `{t('key')}` in templates and islands using normalized dot-separated key paths.
+
+### 5. Vue (`vue-i18n`)
+- **Initialization**: Generates `src/i18n.ts` using `createI18n`.
+- **Runtime Messages**: Generates runtime message files in `messages/runtime/<locale>.json`.

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

@@ -1,11 +1,37 @@
 # 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):
+When using Shallok via an AI coding agent (e.g., in Antigravity, Claude, Cursor, Copilot):
 - **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>"`).
+- **Always verify context first**: Before translating any key, check that all keys in `localization_base/<source_locale>.json` have proper semantic context. If any key lacks context or has generic AST context, generate rich context before translating.
+- **Always translate from `localization_base/<source_locale>.json` and its context**: Never translate raw isolated string fragments. Combine the canonical source `content` and its semantic `context` to generate culturally authentic, grammatically correct translations.
+- Inspect `messages/<locale>.json` or run `shallok status --json` to identify entries with `status: "missing"` or `status: "stale"`.
+- Write the translated strings into `messages/<locale>.json` (or use `shallok entry set <locale> <key> "<translated_text>"`).
+
+## Core Rules for Translations
+
+### 1. Pre-Flight Verification & Persistence
+- Before making changes to a new or existing repo, verify `shallok` is installed and check that `localization.json` and `localization_base/` exist. If not, initialize with `shallok init`.
+- **NEVER delete `localization.json` or `localization_base/`**. They hold the single source of truth, content hashes, version counters, and context.
+
+### 2. Normalized Dot-Paths for Keys
+- All keys must use normalized dot notation (e.g., `"checkout.pay_now"`, `"auth.login.title"`).
+- Never use nested object structures. If an existing codebase uses nested objects for keys, ask the user to convert/flatten them to normalized dot-path keys.
+
+### 3. Standardized `messages/` Folder
+- All translations must reside in `messages/` (`messages/<locale>.json` and `messages/runtime/<locale>.json`).
+- If an existing project uses another directory (such as `locales/`, `src/locales/`, `translations/`), ask the user to switch to `messages/` and migrate existing files.
+
+### 4. Context Verification Before Translation
+- Check all keys in `localization_base/<source_locale>.json` have meaningful semantic context.
+- If any key lacks context, generate clear context describing the screen, element, and user action before initiating translation.
+
+### 5. Always Translate from Source Locale Catalog + Context
+- Read both `content` and `context` from `localization_base/<source_locale>.json`.
+- Preserve all interpolation placeholders (`{name}`, `{count}`, `{amount}`) exactly as formatted.
+
+---
 
 ### Translation Schema
 Each entry in `messages/<locale>.json` maintains:
@@ -35,7 +61,7 @@ The AI agent must strictly preserve all interpolation placeholders in target tra
 - Kannada: `"ಮರಳಿ ಸ್ವಾಗತ, {userName}! ನಿಮ್ಮ ಕಾರ್ಟ್‌ನಲ್ಲಿ {itemCount} ಐಟಂಗಳು ಇವೆ."`
 - Hindi: `"वापसी पर स्वागत है, {userName}! आपके कार्ट में {itemCount} आइटम हैं।"`
 
-If a translation drops a placeholder or introduces an invalid placeholder, `localize validate` will fail with an error.
+If a translation drops a placeholder or introduces an invalid placeholder, `shallok validate` will fail with an error.
 
 ---
 

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

@@ -1,8 +1,22 @@
 # Per-Key Versioning & Context Reference
 
+## Strict Catalog Persistence: NEVER Delete `localization.json` or `localization_base/`
+> [!CAUTION]
+> `localization.json` and `localization_base/` are the permanent foundation of the localization system:
+> - `localization.json` stores project settings, locales, paths, and key strategies.
+> - `localization_base/` stores canonical source strings, per-key version counters (`key_version`), cryptographic SHA-256 hashes (`content_hash`), occurrence positions, and enriched semantic `context`.
+> - **Under NO circumstances should you EVER delete `localization.json` or `localization_base/`**. Deleting them resets version counters, destroys human- and AI-enriched context, breaks incremental translation, and corrupts catalog synchronization.
+
+---
+
 ## 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.
 
+### Key Format: Normalized Dot-Separated Paths Only
+- All keys must use normalized dot-separated string paths (e.g. `"checkout.pay_now"`, `"auth.login.title"`).
+- **Never use nested object-based keys**.
+- If an existing project uses object-based keys, ask the user to convert and flatten them to normalized dot-paths before modifying catalogs.
+
 ### Structure of a Canonical Entry
 ```json
 {
@@ -26,12 +40,14 @@ The canonical catalog is the single source of truth for all active and obsolete
 }
 ```
 
-## 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>"`
+## Context Enrichment & Verification Before Translation
+1. When strings are extracted via `shallok extract`, the CLI provides baseline AST context (e.g. `JSX text in <button> (in App <button>)`).
+2. **Mandatory Check Before Translation**: Before generating any translations, check that all active keys in `localization_base/<source_locale>.json` have proper, high-quality semantic context.
+3. If any key lacks context or has only generic AST descriptions, analyze the source code, component hierarchy, and user flow, and enrich the `context` with semantic clarity:
+   - CLI method: `shallok context set <key> "<semantic_description>"`
    - Direct edit: Update `"context"` in `localization_base/<source_locale>.json`.
-3. **Preservation Guarantee**:
+4. **Always Translate from Source Locale + Context**: Translations must be derived directly from `localization_base/<source_locale>.json` using BOTH `content` and `context`.
+5. **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
@@ -54,4 +70,4 @@ In `messages/<locale>.json`, each entry records:
   }
 }
 ```
-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.
+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 from `localization_base/<source_locale>.json` and its enriched `context`.