# Phase 34: i18n Foundation - Context

**Gathered:** 2026-04-13
**Status:** Ready for planning

<domain>
## Phase Boundary

Add a translation framework to GearBox with string extraction, locale-aware formatting, and ship English + German. UI chrome and system content are translated. Catalog data and user-generated content remain untranslated. Language selection is independent from market/currency (Phase 33) but both auto-detected from browser.

</domain>

<decisions>
## Implementation Decisions

### Translation Scope & Boundaries
- **D-01:** Translate UI chrome: buttons, labels, headings, navigation items, empty states, error messages, toast notifications, modal titles/descriptions, placeholder text
- **D-02:** Translate system content: default category names (e.g., "Uncategorized"), onboarding flow text, MCP tool descriptions, email templates if any
- **D-03:** Do NOT translate: catalog item names/descriptions, user-generated content (item names, notes, setup names, thread titles), category names created by users
- **D-04:** Locale-aware formatting integrates with the existing `useFormatters()` hook — number formatting, date formatting, and pluralization handled by the i18n framework, weight/price formatting continues through existing formatters

### Library & Architecture
- **D-05:** Claude's discretion on library choice — pick between react-i18next and Lingui based on best fit with React 19, Vite, Bun, Hono stack. Key criteria: hook-based API, lazy loading per locale, compile-time or runtime extraction, TypeScript support
- **D-06:** Translation files stored as JSON in the repo: `src/client/locales/en.json`, `src/client/locales/de.json`. Checked into git. Switching to an external translation service (Crowdin/Lokalise) later is a CI/sync change, not a code change
- **D-07:** Translations loaded client-side — the React app loads the appropriate locale JSON. Server-side strings (API error messages, MCP descriptions) use a simple server-side translation utility
- **D-08:** Namespace support for organizing strings by feature area (e.g., `common`, `collection`, `threads`, `setups`, `onboarding`, `settings`) to keep files manageable as string count grows

### Language Selection UX
- **D-09:** Language and market/currency are independent settings. A German expat in the UK can have GBP prices but German UI
- **D-10:** Language auto-detected from browser locale on first visit (navigator.language). User can override in settings
- **D-11:** Language picker in settings page — alongside but separate from the market/currency picker from Phase 33
- **D-12:** If browser locale has no matching translation (e.g., `ja`), fall back to English

### First Additional Language
- **D-13:** German (de) ships alongside English (en) as the first additional language. Primary target market is EU/DE
- **D-14:** German translations AI-generated by Claude during implementation. No formal review step — user catches and fixes issues organically during app usage
- **D-15:** Translation quality approach for future languages: same AI-generated strategy. Professional/community translation deferred until there's a real user base requesting specific languages

### Claude's Discretion
- Library choice between react-i18next and Lingui (evaluate DX, bundle size, extraction tooling, React 19 compatibility)
- String key naming convention (flat vs. nested, dot notation style)
- How to handle dynamic content interpolation patterns
- Whether to extract strings from existing components in one pass or incrementally

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

No external specs — requirements fully captured in decisions above.

### Existing Implementation (to integrate with)
- `src/client/hooks/useFormatters.ts` — Central formatting hook for weight + price. i18n number/date formatting should integrate here
- `src/client/lib/formatters.ts` — `formatWeight()` and `formatPrice()` functions. Locale-aware formatting may need to wrap or replace these
- `src/client/hooks/useCurrency.ts` — Currency/market hook. Language selection is separate but both auto-detect from browser
- `src/client/routes/settings.tsx` — Settings page where language picker will be added
- `src/client/routes/__root.tsx` — Root layout where i18n provider wraps the app
- `src/client/main.tsx` — App entry point for i18n initialization
- `src/server/mcp/` — MCP tool descriptions need server-side translation
- `src/client/components/onboarding/` — Onboarding flow has significant translatable text

### Phase 33 Integration
- `src/client/hooks/useCurrency.ts` — Market auto-detection logic from Phase 33. Language auto-detection should follow the same pattern but remain independent

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `useFormatters()` hook: Already composites weight + price formatting. Extend to include locale-aware number/date formatting
- `useSetting()` hook: Settings storage pattern — language preference fits here
- Settings page: Existing pill-toggle pattern (used for weight units, currency) — reuse for language picker

### Established Patterns
- Hooks for user preferences (`useWeightUnit`, `useCurrency`) — `useLanguage` follows the same pattern
- Settings stored in DB via settings table, read via `useSetting()` hook
- Component structure: presentational components in `components/`, route components in `routes/`

### Integration Points
- `src/client/main.tsx`: Initialize i18n provider
- `src/client/routes/__root.tsx`: Wrap app in i18n context provider
- `src/client/routes/settings.tsx`: Add language picker
- Every component with hardcoded English strings: needs `t()` calls (bulk extraction task)
- `src/server/index.ts`: Server-side translation utility initialization for API errors and MCP descriptions

### Scale of String Extraction
- Estimated 100-200 translatable strings across the app (buttons, labels, headings, empty states, error messages, onboarding flow)
- Onboarding flow is the most string-heavy component

</code_context>

<specifics>
## Specific Ideas

- Language picker uses the same pill-toggle pattern as weight units and currency in settings
- Auto-detection: `navigator.language` → match to available locales → fallback to `en`
- String extraction can be done incrementally — doesn't need to be all-at-once
- German translations generated alongside English during implementation, not as a separate post-extraction step

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope.

</deferred>

---

*Phase: 34-i18n-foundation*
*Context gathered: 2026-04-13*