ss-tools/docs/bug-reports/2026-06-02-svelte5-proxy-store-t-undefined.md

# Bug Report: Svelte 5 — Proxy-based i18n store causes `ReferenceError: $t is not defined`

**Status:** ✅ Fixed
**Severity:** Critical (entire page unrenderable)
**Affected version:** Svelte 5.43.8+ (verified on 5.46.0)
**Date:** 2026-06-02
**Reporter:** Browser validation of translate/[id] refactor
**Fix commit:** `27435e4`

---

## Summary

After binding the `translate/[id]/+page.svelte` page to `TranslationJobModel`, the entire detail page rendered blank with `Uncaught ReferenceError: $t is not defined`. The same page renders fine for simpler pages (e.g. `/dashboards`, `/translate` list). Root cause: Svelte 5's static store-detection cannot recognize the `t` export from `$lib/i18n/index.svelte.ts` (a `Proxy` with a `subscribe` getter) as a store in deeply nested template expressions and in `.svelte.ts` model files, generating `ReferenceError: $t is not defined` at runtime.

---

## Reproduction

1. Run dev server: `cd frontend && npm run dev -- --port 5173`
2. Navigate to `http://localhost:5173/translate/54215412-d6ad-49cf-9704-ff8b194f74cd`
3. Observe: page renders only the layout (sidebar, navbar, footer) — `<main>` is empty
4. Open DevTools console → `Uncaught ReferenceError: $t is not defined`

The same page works for `/translate` (list), `/dashboards`, etc. The detail page is unique in that it uses a 49-atom `TranslationJobModel` plus 9 translate-specific sub-components with deeply nested template conditions.

---

## Root Cause Analysis

### The i18n module's `t` export

`frontend/src/lib/i18n/index.svelte.ts` exports `t` as a `Proxy` with a `subscribe` getter:

```typescript
export const t = new Proxy({} as any, {
  get(_target, prop) {
    if (prop === 'subscribe') {
      return (fn: (v: any) => void) => {
        fn(_tValue);
        _tSubs.add(fn);
        return () => { _tSubs.delete(fn); };
      };
    }
    if (prop === 'current') {
      return _tValue;
    }
    return (_tValue as any)[prop];
  }
});
```

The `subscribe` method is **defined via a `get` trap on the Proxy**, not as a direct own property.

### Svelte 5's `$store` template syntax

In Svelte 5, the `$t` template prefix triggers store subscription. The compiler normally generates code like:

```js
let $t;
const unsubscribe = t.subscribe((v) => ($t = v));
// ... template uses $t ...
unsubscribe();
```

For the compiler to detect `t` as a store, it must statically determine that `t` has a `subscribe` method.

### Why detection fails

**Three trigger conditions** (verified by binary-search testing of templates):

1. **Deeply nested conditional/loop blocks** (`{#if}…{:else if}…{:else}…` chains, nested `{#each}`)
2. **Complex ternary expressions** in attribute bindings like `title={a ? b : c ? d : e}`
3. **`.svelte.ts` model files** using `$derived.by()` callbacks that reference `$t`

In all three cases, the Svelte 5 compiler fails to statically determine `t.subscribe` exists (Proxy trap is invisible to static analysis) and emits a **direct reference to `$t`** instead of generating the subscription code. At runtime, `$t` is undefined → `ReferenceError`.

### Why other pages work

- `/dashboards` and `/translate` list: simpler templates without the trigger conditions
- The minimal test page with just `<h1>{_t.translate?.config?.new_title}</h1>` and no nested blocks: worked fine with `_t = $derived(getT())`

### Why even a model file triggers it

`TranslationJobModel.svelte.ts` line 70–81 has:

```typescript
tabs: { id: string; label: string }[] = $derived.by(() => {
  const base = [
    { id: 'config', label: $t.translate?.config?.basic_info || 'Configuration' },
    // ...
  ];
  // ...
});
```

The `$derived.by` callback body is compiled similarly to a template. Static analysis on the `t` import fails → `$t` is emitted as a direct reference → at model instantiation, the callback runs and throws.

---

## Symptoms (chronological)

1. Build: `npm run build` — passes clean, no errors.
2. Type check: `tsc` — no errors.
3. Unit tests: `npm run test` — 698/698 pass (tests don't exercise the page's runtime rendering).
4. Browser: clicking on a job card from `/translate` navigates to the detail URL, but the `<main>` content is empty.
5. Console: `Uncaught ReferenceError: $t is not defined  in <unknown>  in ProtectedRoute.svelte  in +layout.svelte  in root.svelte`

The stack trace shows `<unknown>` because Svelte's component-name resolution fails when the component crashes before mounting.

---

## Diagnostic Process (binary search)

Took **~12 iterations** to isolate the root cause:

| # | What was changed | Result |
|---|---|---|
| 1 | Navigate to `/translate/[id]` | Blank, `$t is not defined` |
| 2 | Restart dev server (port conflict) | Same error |
| 3 | Replace full page with minimal 34-line test | ✅ Renders ("Новое задание перевода") |
| 4 | Add all imports but simple template | ✅ Still renders |
| 5 | Restore full template (no sub-component usages) | ❌ Blank again |
| 6 | Comment out all `<Component>` template usages | ❌ Still blank |
| 7 | Comment out `title={...long ternary...}` on tab button | ❌ Still blank |
| 8 | Identify `TranslationRunGlobalIndicator` is global → fix it | ❌ Still blank |
| 9 | Fix script-block `$t` in `ScheduleConfig`, `TranslationPreview` | ❌ Still blank |
| 10 | Apply `_t = $derived(getT())` pattern to 6 sub-components | ❌ Still blank |
| 11 | Find `$t` in `TranslationJobModel.svelte.ts` line 72–78 | **🎯 Root cause** |
| 12 | Replace model's `$t.` with `getT()?.` and import `getT` | ✅ Renders all 5 tabs |

---

## Fix

### Pattern

Replace all `$t.xxx` references in **templates and `.svelte.ts` model files** with one of:

| Context | Pattern |
|---|---|
| Template | `const _t = $derived(getT())` in script, then `_t.xxx` in template |
| Script function | `getT()?.xxx` direct call (no `_t` needed because function bodies don't have reactive context) |
| Script `$derived.by()` callback | `getT()?.xxx` direct call (Svelte can't make `$t` reactive inside model callbacks) |

### Import change

```diff
- import { t } from '$lib/i18n/index.svelte.js';
+ import { getT } from '$lib/i18n/index.svelte.js';
```

### Template change

```diff
- <h1>{$t.translate?.config?.new_title}</h1>
+ const _t = $derived(getT());
+ <h1>{_t.translate?.config?.new_title}</h1>
```

### Script change

```diff
- addToast($t.translate?.schedule?.saved, 'success');
+ addToast(getT()?.translate?.schedule?.saved, 'success');
```

### Why this works

`getT()` is a plain function exported from the i18n module. It does NOT require store-detection — the compiler treats it as a regular function call. The `$derived(getT())` wrapper in scripts gives templates reactive re-evaluation when the locale changes (because `getT()` reads the `$state`-backed `_locale` internally).

---

## Files Changed

| File | `_t` added | `$t` → `getT()?.` in script |
|---|---|---|
| `src/routes/translate/[id]/+page.svelte` | ✅ | — |
| `src/lib/models/TranslationJobModel.svelte.ts` | — | 8 refs |
| `src/lib/components/translate/ConfigTabForm.svelte` | ✅ | 2 refs |
| `src/lib/components/translate/ScheduleConfig.svelte` | ✅ | 12 refs |
| `src/lib/components/translate/TranslationPreview.svelte` | ✅ | 15 refs |
| `src/lib/components/translate/TargetTabForm.svelte` | ✅ | 2 refs |
| `src/lib/components/translate/RunTabContent.svelte` | ✅ | 3 refs |
| `src/lib/components/translate/BulkReplaceModal.svelte` | ✅ | 2 refs |
| `src/lib/components/translate/TranslationRunProgress.svelte` | ✅ | (template only) |
| `src/lib/components/translate/TranslationRunResult.svelte` | ✅ | (template only) |
| `src/lib/components/translate/TermCorrectionPopup.svelte` | ✅ | (template only) |
| `src/lib/components/translate/BulkCorrectionSidebar.svelte` | ✅ | (template only) |
| `src/lib/components/translate/TranslationMetricsDashboard.svelte` | ✅ | (template only) |
| `src/lib/components/translate/CorrectionCell.svelte` | ✅ | (template only) |
| `src/lib/components/translate/TranslationRunGlobalIndicator.svelte` | ✅ | 8 refs |

**Total:** 15 files, +496 / -451 LOC.

---

## Verification

After the fix:

| Check | Result |
|---|---|
| `npm run build` | ✅ clean |
| `npm run test -- --run` | ✅ 698/698 tests pass |
| `node scripts/audit-frontend-style.mjs` | ✅ 0 color violations, 2 oversized (out of scope) |
| Browser `/translate/[id]` Config tab | ✅ renders form, all fields, columns, LLM, languages |
| Browser `/translate/[id]` Preview tab | ✅ renders sample size slider + Run button |
| Browser `/translate/[id]` Target tab | ✅ renders schema/table/DB/columns/write-settings |
| Browser `/translate/[id]` Run tab | ✅ renders incremental/full + run history (5 runs) |
| Browser `/translate/[id]` Schedule tab | ✅ renders "Create schedule" prompt |
| Browser console | ✅ no JS errors (only expected backend API 404/422) |

---

## Lessons Learned

### 1. Build/test green ≠ runtime safe

All standard verification (build, type-check, 698 unit tests) passed. The bug only manifested in browser runtime when Svelte's reactive engine actually executed the compiled template. **Browser validation is non-negotiable for pages with complex templates.**

### 2. Svelte 5 Proxy-based stores are fragile

Svelte 5's static store-detection can fail on `Proxy` objects even when they implement the store protocol. Prefer:
- **Class instances** with `subscribe` as a direct method, or
- **Plain objects** with `subscribe` as an own property, or
- **Skip the store pattern entirely** — use functions like `getT()` + `$derived` for reactive reads.

### 3. Model files are a blind spot

`.svelte.ts` files using `$derived.by()` callbacks that reference `$t` will also fail. The compiler treats model callback bodies like templates for store-detection purposes. Always use `getT()?.xxx` in model files, not `$t`.

### 4. The error message is misleading

`Uncaught ReferenceError: $t is not defined  in <unknown>` looks like a missing import, but the import is correct. The actual cause is the compiler failing to generate the store-subscription code. Look at the i18n module's `t` export mechanism, not the call sites.

### 5. The minimal reproduction pattern is critical

A 34-line minimal page with identical imports and one `$t` reference worked. Adding back the full template (no sub-components) broke it. This proved the issue was in **template complexity**, not the import chain.

---

## Related Files & References

- **Commit:** `27435e4 fix(frontend): replace $t with _t pattern in translate components`
- **i18n module:** `frontend/src/lib/i18n/index.svelte.ts` (lines 188–202: `t` Proxy export; line 209: `getT()` function)
- **Model file:** `frontend/src/lib/models/TranslationJobModel.svelte.ts` (line 70: `tabs: ... = $derived.by(() => { ... $t ... })`)
- **Page:** `frontend/src/routes/translate/[id]/+page.svelte`
- **Related ADR:** `docs/adr/ADR-0006-frontend-architecture.md` (Design Token System, Screen Model tier)
- **Svelte 5 docs:** [Stores](https://svelte.dev/docs/svelte/stores) — `$store` template syntax
- **Svelte 5 issue:** store-detection on Proxy-based objects with `get` trap (upstream behavior)

---

## Recommended Follow-up

1. **Update `t` export** in `i18n/index.svelte.ts` to use a class instance with `subscribe` as a direct method, avoiding the Proxy entirely. This may restore `$t` template syntax reliability.

2. **Add ESLint rule** to disallow `$t` template references — force `_t = $derived(getT())` pattern.

3. **Document the pattern** in `semantics-svelte` skill (`§VII` or new `§X`) so future agents don't repeat this debugging cycle.

4. **Audit other pages** with complex templates: any page using `t` import + nested `{#if}` chains is a latent bug.