shallok 0.1.1 → 0.1.3

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

@@ -14,20 +14,91 @@ 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 expo --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, mobile character limits).
+  - 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 mobile app 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. `i18n.ts`, `src/i18n.ts`, `app/_layout.tsx`, `App.tsx`) 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** to point to the standardized compiled runtime bundle (`messages/runtime/<locale>.json`) or the CDN loader.
+    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: Mobile Translation Architecture: CDN-Backed Dynamic Loading (OTA Updates)
+- **Suggest loading translations from a CDN for Expo & React Native**:
+  - App Store and Google Play binary releases require review cycles that take days or weeks. Shipping translations solely inside the mobile binary prevents quick fixes for typos, copy tweaks, or adding languages.
+  - Recommend hosting compiled `messages/runtime/<locale>.json` on a CDN or cloud storage bucket (e.g. Cloudflare R2, AWS S3/CloudFront, Supabase Storage, Vercel Blob).
+- **Environment Variables & Configuration**:
+  - Define `EXPO_PUBLIC_TRANSLATIONS_CDN_URL=https://cdn.yourdomain.com/locales` in `.env` and `.env.example`.
+  - **Prompt and ask the user to configure/update `EXPO_PUBLIC_TRANSLATIONS_CDN_URL`** with their actual CDN endpoint.
+- **Resilient Mobile Runtime Loader with Local Offline Fallback**:
+  - Configure `i18n.ts` to fetch dynamic translations from `${EXPO_PUBLIC_TRANSLATIONS_CDN_URL}/${locale}.json` and cache them locally using `AsyncStorage`.
+  - Always bundle `messages/runtime/<locale>.json` locally as fallback resources, ensuring the app works 100% offline or on first launch before network connectivity is established.
+- **Upload Script**:
+  - Suggest / scaffold an upload script (e.g., `scripts/upload-locales.mjs`) to automate publishing compiled `messages/runtime/` dictionaries to the CDN.
 
 ---
 
@@ -38,7 +109,7 @@ Shallok pairs a deterministic AST CLI (`shallok`) with **the AI Agent as the sem
 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`).
+   - Replaces user-facing strings in `<Text>`, `<TextInput>`, and props 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 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`).
@@ -59,6 +130,9 @@ 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`).
+- 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 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`).
@@ -68,30 +142,37 @@ shallok analyze --json
 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**:
+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**:
+   - Propose loading translations from a CDN via `EXPO_PUBLIC_TRANSLATIONS_CDN_URL` with local offline fallback for OTA updates without app store reviews.
+   - Ask the user to configure their CDN endpoint in `.env`.
+5. **Dependencies to Install**:
    ```bash
-   npx expo install expo-localization
+   npx expo install expo-localization @react-native-async-storage/async-storage
    pnpm add i18next react-i18next
    ```
-4. **Planned Scaffolding**:
+6. **Planned Scaffolding**:
    - `localization.json` (Project manifest)
-   - `i18n.ts` (Mobile i18n initialization at root)
-   - `localization_base/<source_locale>.json` & `metadata.json` (Canonical catalog & versions)
+   - `i18n.ts` (Mobile i18n initialization at root with CDN loader & local fallback)
+   - `.env` / `.env.example` (Configured with `EXPO_PUBLIC_TRANSLATIONS_CDN_URL`)
+   - `scripts/upload-locales.mjs` (Script to sync `messages/runtime/` to CDN)
+   - `localization_base/<source_locale>.json` & `metadata.json` (Canonical catalog & versions — **never delete**)
    - `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).
+7. **Root Integration**: Adding `import './i18n';` in `App.tsx` or `app/_layout.tsx`.
+8. 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
+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/` or CDN loader.
+3. Configure `.env` and `.env.example` with `EXPO_PUBLIC_TRANSLATIONS_CDN_URL` and ask the user to update it with their CDN URL.
+4. Scaffold `scripts/upload-locales.mjs` if CDN loading is chosen.
 
 Ensure mobile dependencies are installed:
 ```bash
@@ -110,34 +191,34 @@ pnpm add i18next react-i18next
    ```
    This extracts text inside `<Text>`, `<Button title="...">`, and `<TextInput placeholder="...">` 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 mobile screen and component context.
-   - Enrich `context` with semantic clarity (e.g. *"Header label on Bluetooth pairing bottom sheet modal"*).
-   - Use the CLI:
+   - **Verify that every key has proper semantic context**.
+   - If any key lacks context or has only generic AST descriptions, inspect the mobile screen and component context 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`.
    - 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**:
+4. **Update Target Locale Catalogs**:
    Write directly into `messages/<locale>.json` or use:
    ```bash
    shallok entry set <locale> <key> "<translated_text>"
@@ -148,7 +229,7 @@ You, as the AI coding agent, generate the translations directly:
    ```bash
    shallok extract --apply
    ```
-   This injects `const { t } = useTranslation();` and replaces hardcoded text with `{t('key')}`.
+   This injects `const { t } = useTranslation();` and replaces hardcoded text with `{t('key')}` using normalized dot-separated key paths.
 
 2. **Verify Root Entry Integration**:
    Ensure `App.tsx` or `app/_layout.tsx` imports `i18n.ts`:

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

@@ -1,39 +1,84 @@
 # 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.
+## Deployment Architecture: CDN-Backed Loading (OTA) vs. Local Bundling
 
+Mobile apps benefit greatly from CDN-backed translation loading because updating text via App Store / Google Play requires full binary reviews.
+
+### 1. CDN Dynamic Loading Pattern (Recommended for Production & OTA Updates)
+
+Configure `.env`:
+```env
+EXPO_PUBLIC_TRANSLATIONS_CDN_URL=https://cdn.yourdomain.com/locales
+```
+
+`i18n.ts`:
 ```typescript
 import i18n from 'i18next';
 import { initReactI18next } from 'react-i18next';
 import { getLocales } from 'expo-localization';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+// Local bundled fallbacks (from our specified structure)
+import enFallback from './messages/runtime/en.json';
+import knFallback from './messages/runtime/kn.json';
 
-import enMessages from './messages/runtime/en.json';
-import knMessages from './messages/runtime/kn.json';
-import hiMessages from './messages/runtime/hi.json';
+const CDN_URL = process.env.EXPO_PUBLIC_TRANSLATIONS_CDN_URL;
 
 const resources = {
-  en: { translation: enMessages },
-  kn: { translation: knMessages },
-  hi: { translation: hiMessages },
+  en: { translation: enFallback },
+  kn: { translation: knFallback },
 };
 
 const deviceLanguage = getLocales()[0]?.languageCode ?? 'en';
 
+export async function fetchRemoteTranslations(locale: string) {
+  if (!CDN_URL) return;
+  try {
+    const res = await fetch(`${CDN_URL}/${locale}.json`);
+    if (res.ok) {
+      const messages = await res.json();
+      i18n.addResourceBundle(locale, 'translation', messages, true, true);
+      await AsyncStorage.setItem(`translations_${locale}`, JSON.stringify(messages));
+    }
+  } catch (err) {
+    // Falls back seamlessly to bundled local messages
+  }
+}
+
 i18n
   .use(initReactI18next)
   .init({
     resources,
     lng: deviceLanguage,
     fallbackLng: 'en',
-    interpolation: {
-      escapeValue: false,
-    },
+    interpolation: { escapeValue: false },
   });
 
 export default i18n;
 ```
 
+### 2. Upload Script (`scripts/upload-locales.mjs`)
+Suggest creating an upload script to sync `messages/runtime/` to CDN/bucket:
+```javascript
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Upload all JSON files in messages/runtime/ to Cloudflare R2 / S3 / Supabase Storage
+const runtimeDir = path.resolve('messages/runtime');
+const files = fs.readdirSync(runtimeDir);
+for (const file of files) {
+  console.log(`Uploading ${file} to CDN...`);
+}
+```
+
+### 3. Legacy Base Locale Migration
+If existing code imported `src/locales/en.json`:
+- Reconcile keys into `localization_base/en.json`.
+- Update imports in `i18n.ts` and `app/_layout.tsx` to point to `./messages/runtime/en.json` (or CDN loader).
+- Deprecate or remove `src/locales/en.json`.
+
+---
+
 ## React Native Component Rules
 1. **Text Nodes**:
    Raw strings cannot exist outside `<Text>` in React Native.

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