@techninja/clearstack 0.3.49 → 0.4.0

package/README.md

@@ -36,6 +36,7 @@ A project/task tracker that exercises every pattern in the spec: API-backed enti
 | [SERVER_AND_DEPS.md](./docs/SERVER_AND_DEPS.md)                             | Express server, import maps, vendor dependency loading         |
 | [BACKEND_API_SPEC.md](./docs/BACKEND_API_SPEC.md)                           | REST CRUD, JSON Schema via HEAD, entity management             |
 | [TESTING.md](./docs/TESTING.md)                                             | Testing philosophy, tools, patterns, phase checkpoints         |
+| [I18N.md](./docs/I18N.md)                                                   | Internationalization — 4-layer cascade, `t()` usage, conventions |
 | [BUILD_LOG.md](./docs/BUILD_LOG.md)                                         | How this project was built — LLM-human collaboration proof     |
 | [QUICKSTART.md](./docs/QUICKSTART.md)                                       | Scaffolder setup, development workflow, updating, compliance   |
 

package/docs/I18N.md

@@ -0,0 +1,108 @@
+# Internationalization (i18n)
+
+## Why This Matters
+
+Hardcoding UI strings is a foot gun. Retrofitting i18n into an existing app
+requires touching every component — a painful, error-prone refactor. Starting
+with `t('key')` from day one costs almost nothing and keeps the door open while
+also clearly separating UI and exact wording concerns.
+
+## The Pattern
+
+A 4-layer message cascade. Last layer wins:
+
+```
+1. App defaults     → DEFAULTS in utils/i18n.js (English, ships with app)
+2. Locale file      → /locales/<lang>.json (e.g. es.json)
+3. Overrides        → /locales/overrides.json (project customizes English)
+4. Locale overrides → /locales/overrides.<lang>.json (project customizes locale)
+```
+
+This means:
+
+- The platform ships sensible English defaults
+- Projects override just what they need in `overrides.json`
+- Adding a new language only requires a `<lang>.json` file
+- No build step, no external dependency
+
+## Usage
+
+```js
+import { t, loadLocale } from '#utils/i18n.js';
+
+// Call once at app init (router or top-level component connect)
+await loadLocale(navigator.language);
+
+// Simple key
+t('general.loading')              // → 'Loading…'
+
+// With interpolation
+t('order.thanks', { name: 'James' })  // → 'Thanks, James!'
+
+// Falls back to key if not found — never throws
+t('missing.key')                  // → 'missing.key'
+```
+
+## Key Naming Convention
+
+`domain.action` or `component.concept` — dot-separated, lowercase, no spaces.
+
+```
+general.loading     general.error      general.back
+nav.home            nav.signIn         nav.signOut
+cart.add            cart.empty         cart.checkout
+product.inStock     product.outOfStock
+error.notFound      error.offline
+```
+
+Avoid generic keys like `button1` or `label`. Keys should be readable as
+documentation.
+
+## App Init
+
+Call `loadLocale()` once before rendering. In a Hybrids app, the router's
+`connect` is the right place:
+
+```js
+// router/index.js
+import { loadLocale } from '#utils/i18n.js';
+
+await loadLocale(navigator.language);
+```
+
+For SSR/static sites, call it in the page's `connect` handler instead.
+
+## Adding a Language
+
+1. Create `/locales/<lang>.json` with translated keys
+2. Only include keys that differ from English — missing keys fall back to defaults
+3. Optionally add `/locales/overrides.<lang>.json` for project-specific overrides
+
+```json
+// locales/es.json
+{
+  "general.loading": "Cargando…",
+  "general.error": "Algo salió mal.",
+  "nav.home": "Inicio"
+}
+```
+
+## Project Overrides
+
+To customize English strings (e.g. brand voice) without touching `i18n.js`:
+
+```json
+// locales/overrides.json
+{
+  "general.loading": "Analyzing your DNA…",
+  "error.offline": "Check your connection and try again."
+}
+```
+
+## Rules
+
+- **Always use `t()`** for any user-visible string in components
+- **Never hardcode UI strings** in component render functions
+- **Keys fall back to themselves** — `t('missing')` returns `'missing'`, never crashes
+- **`loadLocale()` is safe to call multiple times** — last call wins
+- **Locale files are optional** — English-only apps just use `overrides.json`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.3.49",
+  "version": "0.4.0",
   "type": "module",
   "description": "A no-build web component framework specification — scaffold, validate, and evolve spec-compliant projects",
   "bin": {

package/templates/shared/docs/clearstack/I18N.md

@@ -0,0 +1,108 @@
+# Internationalization (i18n)
+
+## Why This Matters
+
+Hardcoding UI strings is a foot gun. Retrofitting i18n into an existing app
+requires touching every component — a painful, error-prone refactor. Starting
+with `t('key')` from day one costs almost nothing and keeps the door open while
+also clearly separating UI and exact wording concerns.
+
+## The Pattern
+
+A 4-layer message cascade. Last layer wins:
+
+```
+1. App defaults     → DEFAULTS in utils/i18n.js (English, ships with app)
+2. Locale file      → /locales/<lang>.json (e.g. es.json)
+3. Overrides        → /locales/overrides.json (project customizes English)
+4. Locale overrides → /locales/overrides.<lang>.json (project customizes locale)
+```
+
+This means:
+
+- The platform ships sensible English defaults
+- Projects override just what they need in `overrides.json`
+- Adding a new language only requires a `<lang>.json` file
+- No build step, no external dependency
+
+## Usage
+
+```js
+import { t, loadLocale } from '#utils/i18n.js';
+
+// Call once at app init (router or top-level component connect)
+await loadLocale(navigator.language);
+
+// Simple key
+t('general.loading')              // → 'Loading…'
+
+// With interpolation
+t('order.thanks', { name: 'James' })  // → 'Thanks, James!'
+
+// Falls back to key if not found — never throws
+t('missing.key')                  // → 'missing.key'
+```
+
+## Key Naming Convention
+
+`domain.action` or `component.concept` — dot-separated, lowercase, no spaces.
+
+```
+general.loading     general.error      general.back
+nav.home            nav.signIn         nav.signOut
+cart.add            cart.empty         cart.checkout
+product.inStock     product.outOfStock
+error.notFound      error.offline
+```
+
+Avoid generic keys like `button1` or `label`. Keys should be readable as
+documentation.
+
+## App Init
+
+Call `loadLocale()` once before rendering. In a Hybrids app, the router's
+`connect` is the right place:
+
+```js
+// router/index.js
+import { loadLocale } from '#utils/i18n.js';
+
+await loadLocale(navigator.language);
+```
+
+For SSR/static sites, call it in the page's `connect` handler instead.
+
+## Adding a Language
+
+1. Create `/locales/<lang>.json` with translated keys
+2. Only include keys that differ from English — missing keys fall back to defaults
+3. Optionally add `/locales/overrides.<lang>.json` for project-specific overrides
+
+```json
+// locales/es.json
+{
+  "general.loading": "Cargando…",
+  "general.error": "Algo salió mal.",
+  "nav.home": "Inicio"
+}
+```
+
+## Project Overrides
+
+To customize English strings (e.g. brand voice) without touching `i18n.js`:
+
+```json
+// locales/overrides.json
+{
+  "general.loading": "Analyzing your DNA…",
+  "error.offline": "Check your connection and try again."
+}
+```
+
+## Rules
+
+- **Always use `t()`** for any user-visible string in components
+- **Never hardcode UI strings** in component render functions
+- **Keys fall back to themselves** — `t('missing')` returns `'missing'`, never crashes
+- **`loadLocale()` is safe to call multiple times** — last call wins
+- **Locale files are optional** — English-only apps just use `overrides.json`

package/templates/shared/src/locales/overrides.json

@@ -0,0 +1,3 @@
+{
+  "general.loading": "Loading…"
+}

package/templates/shared/src/utils/i18n.js

@@ -0,0 +1,87 @@
+/**
+ * i18n — 4-layer message cascade.
+ *
+ * Resolution order (last wins):
+ * 1. App defaults (English, defined in this file)
+ * 2. Locale file (/locales/<lang>.json)
+ * 3. Project overrides (/locales/overrides.json)
+ * 4. Project locale overrides (/locales/overrides.<lang>.json)
+ *
+ * Usage:
+ *   import { t, loadLocale } from '#utils/i18n.js';
+ *   await loadLocale(navigator.language); // call once at app init
+ *   t('general.loading')                 // → 'Loading…'
+ *   t('greeting', { name: 'James' })     // → 'Hello, James!'
+ *
+ * Key convention: component.action or domain.concept
+ * Add app-specific defaults below and override per-project in overrides.json.
+ * @module utils/i18n
+ */
+
+/** @type {Record<string, string>} */
+const DEFAULTS = {
+  'general.loading': 'Loading…',
+  'general.error': 'Something went wrong.',
+  'general.retry': 'Try again',
+  'general.back': 'Back',
+  'general.close': 'Close',
+  'general.save': 'Save',
+  'general.cancel': 'Cancel',
+  'general.confirm': 'Confirm',
+  'general.noResults': 'No results found.',
+  'nav.home': 'Home',
+  'error.notFound': 'Page not found.',
+  'error.offline': 'You appear to be offline.',
+};
+
+/** @type {Record<string, string>} */
+let active = { ...DEFAULTS };
+
+/** @param {string} url @returns {Promise<Record<string, string>>} */
+async function fetchJson(url) {
+  try {
+    const res = await fetch(url);
+    return res.ok ? await res.json() : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Load and merge all i18n layers. Call once on app init.
+ * @param {string} [locale] - BCP 47 locale string e.g. 'es', 'es-MX'
+ */
+export async function loadLocale(locale) {
+  const lang = locale?.split('-')[0] || '';
+  const isEnglish = !lang || lang === 'en';
+
+  const [localeStrings, overrides, localeOverrides] = await Promise.all([
+    isEnglish ? {} : fetchJson(`/locales/${lang}.json`),
+    fetchJson('/locales/overrides.json'),
+    isEnglish ? {} : fetchJson(`/locales/overrides.${lang}.json`),
+  ]);
+
+  active = { ...DEFAULTS, ...localeStrings, ...overrides, ...localeOverrides };
+}
+
+/**
+ * Get a translated string with optional {param} interpolation.
+ * Falls back to the key itself if not found.
+ * @param {string} key
+ * @param {Record<string, string>} [params]
+ * @returns {string}
+ */
+export function t(key, params) {
+  let msg = active[key] ?? key;
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      msg = msg.replace(`{${k}}`, v);
+    }
+  }
+  return msg;
+}
+
+/** @returns {string} Active locale language code e.g. 'en', 'es' */
+export function getLocale() {
+  return navigator.language?.split('-')[0] || 'en';
+}