shallok 0.0.0-stage → 0.1.1

package/skills/react-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/react-localization-and-translation-i18n/references/react-i18next.md

@@ -0,0 +1,47 @@
+# React & react-i18next Technical Reference
+
+## Configuration Pattern (`src/i18n.ts`)
+Shallok sets up a deterministic configuration importing compiled runtime message bundles from `messages/runtime/`:
+
+```typescript
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+
+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 },
+};
+
+i18n
+  .use(initReactI18next)
+  .init({
+    resources,
+    lng: 'en',
+    fallbackLng: 'en',
+    interpolation: {
+      escapeValue: false, // React already escapes values safely
+    },
+  });
+
+export default i18n;
+```
+
+## Hook Usage (`useTranslation`)
+- Import: `import { useTranslation } from 'react-i18next';`
+- Call inside functional component: `const { t, i18n } = useTranslation();`
+- Text replacement: `<h1>{t('key')}</h1>`
+- Interpolation: `{t('welcome_user', { name: user.name })}`
+- Language switching: `i18n.changeLanguage('kn');`
+
+## JSX Attributes to Localize
+The Babel AST extractor automatically targets:
+- `placeholder` (e.g. `<input placeholder={t('form.email_placeholder')} />`)
+- `aria-label` (e.g. `<button aria-label={t('nav.close_menu')} />`)
+- `title`
+- `alt`
+- `label`

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