GearBox/.planning/phases/34-i18n-foundation/34-01-SUMMARY.md

phase, plan, subsystem, tags, requires, provides, affects, tech-stack, key-files, key-decisions, patterns-established, requirements-completed, duration, completed

phase	plan	subsystem	tags	requires	provides	affects	tech-stack	key-files	key-decisions	patterns-established	requirements-completed	duration	completed
34-i18n-foundation	01	ui	i18next react-i18next i18n localization translations locale-json		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	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)	added patterns i18next@^26.0.4 react-i18next@^17.0.2 i18next-browser-languagedetector@^8.2.1 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	created modified 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 package.json src/client/main.tsx	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	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	D-05 D-06 D-07 D-08 D-12	~30min	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