---
phase: 34-i18n-foundation
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - package.json
  - src/client/lib/i18n.ts
  - src/client/main.tsx
  - src/client/locales/en/common.json
  - src/client/locales/en/collection.json
  - src/client/locales/en/threads.json
  - src/client/locales/en/setups.json
  - src/client/locales/en/onboarding.json
  - src/client/locales/en/settings.json
autonomous: true
requirements: [D-05, D-06, D-07, D-08, D-12]

must_haves:
  truths:
    - "i18next, react-i18next, and i18next-browser-languagedetector are installed"
    - "i18n.ts initializes i18next with LanguageDetector and initReactI18next"
    - "English locale JSON files exist in src/client/locales/en/ with namespaces: common, collection, threads, setups, onboarding, settings"
    - "main.tsx imports i18n.ts before rendering the app"
    - "fallback language is set to en"
    - "Language detection order is localStorage then navigator"
  artifacts:
    - path: "src/client/lib/i18n.ts"
      provides: "i18next initialization with language detection and all namespaces"
      contains: "initReactI18next"
    - path: "src/client/locales/en/common.json"
      provides: "English common namespace translations"
      contains: "save"
    - path: "package.json"
      provides: "i18n dependencies"
      contains: "react-i18next"
  key_links:
    - from: "src/client/main.tsx"
      to: "src/client/lib/i18n.ts"
      via: "import statement"
      pattern: "import.*i18n"
---

<objective>
Install the i18n framework (react-i18next) and create all English locale JSON files with namespace structure.

Purpose: Foundation — all other plans depend on having i18next initialized and English strings extracted into JSON files.
Output: Working i18n setup with all English translation files, app initializes i18next before rendering.
</objective>

<execution_context>
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
@$HOME/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/34-i18n-foundation/34-CONTEXT.md
@.planning/phases/34-i18n-foundation/34-RESEARCH.md

<interfaces>
From src/client/main.tsx:
```typescript
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { createRouter, RouterProvider } from "@tanstack/react-router";
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { routeTree } from "./routeTree.gen";
```

From src/client/hooks/useFormatters.ts:
```typescript
export function useFormatters() {
  const unit = useWeightUnit();
  const currency = useCurrency();
  return {
    weight: (grams: number | null) => formatWeight(grams, unit),
    price: (cents: number | null) => formatPrice(cents, currency),
    unit,
    currency,
  };
}
```
</interfaces>
</context>

<tasks>

<task type="auto">
  <name>Task 1: Install i18n packages</name>
  <files>package.json</files>
  <read_first>package.json</read_first>
  <behavior>
    - i18next is in dependencies
    - react-i18next is in dependencies
    - i18next-browser-languagedetector is in dependencies
  </behavior>
  <action>
Run: `bun add i18next react-i18next i18next-browser-languagedetector`

This adds the three required packages:
- `i18next` — core translation engine (~8KB)
- `react-i18next` — React hooks and components (`useTranslation`)
- `i18next-browser-languagedetector` — auto-detect browser locale from `navigator.language` (D-10)
  </action>
  <acceptance_criteria>
    - package.json contains "i18next" in dependencies
    - package.json contains "react-i18next" in dependencies
    - package.json contains "i18next-browser-languagedetector" in dependencies
    - `bun install` completes without errors
  </acceptance_criteria>
  <verify>
    <automated>cd /home/jlmak/Projects/jlmak/GearBox && grep -c "i18next\|react-i18next\|i18next-browser-languagedetector" package.json</automated>
  </verify>
  <done>All three i18n packages installed</done>
</task>

<task type="auto">
  <name>Task 2: Create English locale JSON files with all translatable strings</name>
  <files>src/client/locales/en/common.json, src/client/locales/en/collection.json, src/client/locales/en/threads.json, src/client/locales/en/setups.json, src/client/locales/en/onboarding.json, src/client/locales/en/settings.json</files>
  <read_first>src/client/components/TopNav.tsx, src/client/components/BottomTabBar.tsx, src/client/components/FabMenu.tsx, src/client/components/ConfirmDialog.tsx, src/client/components/AuthPromptModal.tsx, src/client/routes/__root.tsx, src/client/components/CollectionView.tsx, src/client/components/ItemCard.tsx, src/client/components/ItemForm.tsx, src/client/components/CategoryPicker.tsx, src/client/components/CategoryHeader.tsx, src/client/components/WeightSummaryCard.tsx, src/client/components/PlanningView.tsx, src/client/components/ThreadCard.tsx, src/client/components/ThreadTabs.tsx, src/client/components/CandidateCard.tsx, src/client/components/CandidateForm.tsx, src/client/components/ComparisonTable.tsx, src/client/components/CreateThreadModal.tsx, src/client/components/SetupsView.tsx, src/client/components/SetupCard.tsx, src/client/components/SetupImpactSelector.tsx, src/client/components/ShareModal.tsx, src/client/components/onboarding/OnboardingWelcome.tsx, src/client/components/onboarding/OnboardingHobbyPicker.tsx, src/client/components/onboarding/OnboardingItemBrowser.tsx, src/client/components/onboarding/OnboardingReview.tsx, src/client/components/onboarding/OnboardingDone.tsx, src/client/components/onboarding/OnboardingFlow.tsx, src/client/routes/settings.tsx, src/client/components/StatusBadge.tsx, src/client/components/ClassificationBadge.tsx, src/client/components/ExternalLinkDialog.tsx, src/client/components/CatalogSearchOverlay.tsx, src/client/components/AddToCollectionModal.tsx, src/client/components/AddToThreadModal.tsx, src/client/components/GlobalItemCard.tsx, src/client/components/GearImage.tsx, src/client/components/ImageUpload.tsx, src/client/components/DashboardCard.tsx, src/client/components/TotalsBar.tsx, src/client/components/ImpactDeltaBadge.tsx, src/client/routes/index.tsx, src/client/routes/login.tsx, src/client/routes/profile.tsx, src/client/components/UserMenu.tsx, src/client/components/ProfileSection.tsx, src/client/components/PublicSetupCard.tsx, src/client/components/ManualEntryForm.tsx, src/client/components/LinkToGlobalItem.tsx, src/client/components/SlideOutPanel.tsx, src/client/components/ItemPicker.tsx, src/client/components/ImageCropEditor.tsx, src/client/components/CategoryFilterDropdown.tsx</read_first>
  <behavior>
    - src/client/locales/en/common.json contains keys for: nav items, action buttons (save, cancel, delete, edit, create, back, close, search, confirm), empty states, error messages, loading states, auth prompts
    - src/client/locales/en/collection.json contains keys for: collection page, item cards, item forms, category picker, weight summary, planning view, totals bar
    - src/client/locales/en/threads.json contains keys for: thread list, thread detail, candidate cards, candidate form, comparison table, create thread modal, status badges
    - src/client/locales/en/setups.json contains keys for: setup list, setup detail, setup cards, impact preview, share modal
    - src/client/locales/en/onboarding.json contains keys for: welcome, hobby picker, item browser, review, done screens
    - src/client/locales/en/settings.json contains keys for: settings page, weight unit, currency, API keys, import/export
  </behavior>
  <action>
Create directory `src/client/locales/en/`.

Read EVERY component listed in read_first. For each component, extract all hardcoded English strings (button text, headings, labels, descriptions, placeholder text, error messages, empty states, toast messages, modal titles/descriptions, confirmation dialogs) and add them to the appropriate namespace JSON file.

**String key convention:** Nested objects with dot notation access. Group by component/feature. Use camelCase for keys.

Example structure for `common.json`:
```json
{
  "nav": {
    "home": "Home",
    "collection": "Collection",
    "setups": "Setups",
    "discover": "Discover",
    "settings": "Settings",
    "search": "Search"
  },
  "actions": {
    "save": "Save",
    "cancel": "Cancel",
    "delete": "Delete",
    "edit": "Edit",
    "create": "Create",
    "close": "Close",
    "back": "Back",
    "confirm": "Confirm",
    "tryAgain": "Try again",
    "dismiss": "Dismiss",
    "loading": "Loading...",
    "saving": "Saving...",
    "deleting": "Deleting..."
  },
  "errors": {
    "somethingWentWrong": "Something went wrong",
    "unexpectedError": "An unexpected error occurred"
  },
  "auth": {
    "signIn": "Sign in",
    "signInRequired": "Sign in to continue",
    "signInDescription": "Create an account or sign in to start tracking your gear"
  }
}
```

**IMPORTANT:** Read every component file thoroughly. Do NOT guess strings — extract the actual English text from the JSX. Every user-visible string in the component should become a translation key.

For interpolation (dynamic values), use `{{variable}}` syntax. Example: if a component shows "3 items", the key would be `"itemCount": "{{count}} items"` or use pluralization `"itemCount_one": "{{count}} item"`, `"itemCount_other": "{{count}} items"`.

Do NOT translate: item names, category names created by users, thread titles, candidate names, setup names — these are user-generated content (D-03).
  </action>
  <acceptance_criteria>
    - src/client/locales/en/common.json exists and is valid JSON
    - src/client/locales/en/collection.json exists and is valid JSON
    - src/client/locales/en/threads.json exists and is valid JSON
    - src/client/locales/en/setups.json exists and is valid JSON
    - src/client/locales/en/onboarding.json exists and is valid JSON
    - src/client/locales/en/settings.json exists and is valid JSON
    - common.json contains "nav" key with at least "home", "collection", "setups"
    - common.json contains "actions" key with at least "save", "cancel", "delete"
    - settings.json contains keys for "weightUnit", "currency", "apiKeys", "importExport"
    - onboarding.json contains keys for all 5 onboarding steps (welcome, hobby, items, review, done)
  </acceptance_criteria>
  <verify>
    <automated>cd /home/jlmak/Projects/jlmak/GearBox && for f in common collection threads setups onboarding settings; do node -e "JSON.parse(require('fs').readFileSync('src/client/locales/en/$f.json','utf8')); console.log('$f.json: valid')"; done</automated>
  </verify>
  <done>All 6 English namespace JSON files created with strings extracted from every component</done>
</task>

<task type="auto">
  <name>Task 3: Create i18n initialization module and wire into app entry point</name>
  <files>src/client/lib/i18n.ts, src/client/main.tsx</files>
  <read_first>src/client/main.tsx, src/client/locales/en/common.json</read_first>
  <behavior>
    - src/client/lib/i18n.ts initializes i18next with LanguageDetector and initReactI18next
    - Resources include all 6 namespaces for "en" locale
    - fallbackLng is "en"
    - defaultNS is "common"
    - interpolation.escapeValue is false (React handles XSS)
    - Detection order is ["localStorage", "navigator"]
    - Detection lookupLocalStorage is "gearbox-language"
    - Detection caches is ["localStorage"]
    - main.tsx imports i18n.ts before any React rendering (side-effect import)
  </behavior>
  <action>
Create `src/client/lib/i18n.ts`:

```typescript
import i18n from "i18next";
import LanguageDetector from "i18next-browser-languagedetector";
import { initReactI18next } from "react-i18next";

import enCommon from "../locales/en/common.json";
import enCollection from "../locales/en/collection.json";
import enThreads from "../locales/en/threads.json";
import enSetups from "../locales/en/setups.json";
import enOnboarding from "../locales/en/onboarding.json";
import enSettings from "../locales/en/settings.json";

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    resources: {
      en: {
        common: enCommon,
        collection: enCollection,
        threads: enThreads,
        setups: enSetups,
        onboarding: enOnboarding,
        settings: enSettings,
      },
    },
    fallbackLng: "en",
    defaultNS: "common",
    interpolation: {
      escapeValue: false,
    },
    detection: {
      order: ["localStorage", "navigator"],
      lookupLocalStorage: "gearbox-language",
      caches: ["localStorage"],
    },
  });

export default i18n;
```

Update `src/client/main.tsx` — add `import "./lib/i18n";` as the FIRST import (before React, before QueryClient, before Router). This ensures i18next is initialized before any component tries to use `useTranslation()`. The import is a side-effect import — no named export needed.

The final import order in main.tsx should be:
1. `import "./lib/i18n";` (side-effect — initializes i18next)
2. Existing imports (QueryClient, Router, etc.)
  </action>
  <acceptance_criteria>
    - src/client/lib/i18n.ts exists
    - src/client/lib/i18n.ts contains `import { initReactI18next } from "react-i18next"`
    - src/client/lib/i18n.ts contains `fallbackLng: "en"`
    - src/client/lib/i18n.ts contains `defaultNS: "common"`
    - src/client/lib/i18n.ts contains `lookupLocalStorage: "gearbox-language"`
    - src/client/lib/i18n.ts imports all 6 en namespace JSON files
    - src/client/main.tsx first import line is `import "./lib/i18n"`
    - `bun run build` completes without errors
  </acceptance_criteria>
  <verify>
    <automated>cd /home/jlmak/Projects/jlmak/GearBox && grep -c "initReactI18next\|fallbackLng\|defaultNS\|LanguageDetector" src/client/lib/i18n.ts && head -3 src/client/main.tsx | grep -c "i18n"</automated>
  </verify>
  <done>i18n initialized with language detection, all English namespaces loaded, app entry point imports i18n first</done>
</task>

</tasks>

<threat_model>
## Trust Boundaries

| Boundary | Description |
|----------|-------------|
| localStorage→i18n | Language preference read from localStorage — treated as user preference, not security-sensitive |
| navigator.language→i18n | Browser locale — untrusted but benign (only matched against known locales) |

## STRIDE Threat Register

| Threat ID | Category | Component | Disposition | Mitigation Plan |
|-----------|----------|-----------|-------------|-----------------|
| T-34-01 | Tampering | i18n.ts localStorage | accept | Language preference is non-sensitive. Tampered localStorage key only affects UI language, not data. Validated against known locale list via i18next supportedLngs. |
| T-34-02 | Information Disclosure | locale JSON files | accept | Translation files contain only UI strings, no secrets. Bundled in client JS — intentionally public. |
</threat_model>

<verification>
- `bun install` completes without errors
- All 6 en/*.json files are valid JSON
- `bun run build` completes without errors
- src/client/lib/i18n.ts initializes correctly with all namespaces
- src/client/main.tsx imports i18n before rendering
</verification>

<success_criteria>
- i18next and react-i18next installed
- All English translation strings extracted into 6 namespace JSON files
- i18n initialization module created with language detection
- App entry point wires i18n before React rendering
- Build passes
</success_criteria>

<output>
After completion, create `.planning/phases/34-i18n-foundation/34-01-SUMMARY.md`
</output>
