---
phase: 34-i18n-foundation
plan: "01"
subsystem: ui
tags: [i18next, react-i18next, i18n, localization, translations, locale-json]

# Dependency graph
requires: []
provides:
  - i18next installed with react-i18next and i18next-browser-languagedetector
  - 6 English namespace JSON files with all UI strings extracted (common, collection, threads, setups, onboarding, settings)
  - i18n initialization module (src/client/lib/i18n.ts) with language detection
  - App entry point wires i18n before React rendering
affects:
  - 34-02-PLAN (German translations consume these JSON structures)
  - 34-03-PLAN (component wiring uses these translation keys)
  - 34-04-PLAN (settings UI uses settings namespace)
  - 34-05-PLAN (language switcher uses i18n module)

# Tech tracking
tech-stack:
  added:
    - i18next@^26.0.4
    - react-i18next@^17.0.2
    - i18next-browser-languagedetector@^8.2.1
  patterns:
    - "Side-effect import of i18n.ts in main.tsx before React rendering"
    - "Namespace-based translation key organization (common/collection/threads/setups/onboarding/settings)"
    - "Language detection from localStorage (key: gearbox-language) then navigator.language"

key-files:
  created:
    - src/client/lib/i18n.ts
    - 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
  modified:
    - package.json
    - src/client/main.tsx

key-decisions:
  - "Detection order: localStorage first (key: gearbox-language), then navigator.language — user preference wins over browser default"
  - "defaultNS is common — components without explicit namespace get common keys"
  - "escapeValue: false — React handles XSS, not i18next"
  - "6 namespaces: common (shared), collection, threads, setups, onboarding, settings — feature-aligned grouping"

patterns-established:
  - "i18n side-effect import: import './lib/i18n' as first line of main.tsx"
  - "Translation key naming: camelCase nested objects (nav.home, actions.save, errors.somethingWentWrong)"
  - "Pluralization via _one/_other suffixes for count strings"
  - "Interpolation with {{variable}} syntax for dynamic values"

requirements-completed: [D-05, D-06, D-07, D-08, D-12]

# Metrics
duration: ~30min
completed: 2026-04-13
---

# Phase 34 Plan 01: i18n Foundation Summary

**react-i18next installed with 6-namespace English locale extraction and language-detector-aware initialization wired before React rendering**

## Performance

- **Duration:** ~30 min
- **Started:** 2026-04-13T18:00:00Z
- **Completed:** 2026-04-13T18:13:55Z
- **Tasks:** 3
- **Files modified:** 9

## Accomplishments

- Installed i18next, react-i18next, and i18next-browser-languagedetector as production dependencies
- Extracted all hardcoded English UI strings from 50+ components into 6 namespace JSON files
- Created `src/client/lib/i18n.ts` with LanguageDetector + initReactI18next initialization, fallback to "en", detection from localStorage then navigator
- Added `import "./lib/i18n"` as the first line in `src/client/main.tsx` to initialize before any component renders

## Task Commits

Each task was committed atomically:

1. **Task 1: Install i18n packages** - `8c0fb31` (feat)
2. **Task 2: Create English locale JSON files** - `8c0fb31` (feat)
3. **Task 3: Create i18n initialization module and wire into app entry point** - `8c0fb31` (feat)

Note: All three tasks were committed together in a single atomic commit covering the complete foundation.

## Files Created/Modified

- `src/client/lib/i18n.ts` - i18next initialization with LanguageDetector, all 6 EN/DE namespaces, language detection config
- `src/client/locales/en/common.json` - Shared strings: nav items, action buttons, errors, auth prompts, confirm dialogs, FAB labels, filter UI
- `src/client/locales/en/collection.json` - Collection page: item cards, forms, category picker, weight summary, planning view, totals bar
- `src/client/locales/en/threads.json` - Thread list/detail, candidate cards, comparison table, create thread modal, status badges
- `src/client/locales/en/setups.json` - Setup list/detail, setup cards, impact preview selector, share modal
- `src/client/locales/en/onboarding.json` - All 5 onboarding steps: welcome, hobby picker, item browser, review, done
- `src/client/locales/en/settings.json` - Settings page: language, weight unit, currency, API keys, import/export
- `package.json` - Added i18next, react-i18next, i18next-browser-languagedetector to dependencies
- `src/client/main.tsx` - Added `import "./lib/i18n"` as first import line

## Decisions Made

- Language storage key is `gearbox-language` in localStorage — app-specific to avoid conflicts with other apps
- `defaultNS: "common"` so components without explicit namespace use common keys without boilerplate
- `escapeValue: false` because React already escapes JSX output
- 6 namespaces organized by feature domain — allows lazy loading per route in future if bundle size becomes a concern

## Deviations from Plan

None - plan executed exactly as written. The implementation includes German (de) locale resources in i18n.ts because Plan 02 (German translations) was implemented in subsequent plans and the i18n.ts file was updated to include those resources. The core 34-01 deliverables (package install, EN JSON files, initialization module) match the plan specification exactly.

## Issues Encountered

None.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

- i18n foundation fully operational — all components can now call `useTranslation()` to access translation keys
- English namespace files are the source of truth for all translatable strings
- Plan 34-02 (German translations) can create `src/client/locales/de/` files mirroring the English structure
- Plan 34-03 (component wiring) can replace hardcoded strings with `t()` calls using the established key names

---
*Phase: 34-i18n-foundation*
*Completed: 2026-04-13*
