feat(i18n): add translation support for predefined category names

[steilerDev]

Summary

• Added translation_key column to trades, budget_categories, and household_item_categories tables; predefined categories get keys (e.g. trades.plumbing), user-created categories remain NULL
• API responses include translationKey on category entities; frontend uses getCategoryDisplayName() for translation-aware display with fallback to raw DB name across all display sites (ManagePage, VendorsPage, BudgetOverviewPage, CostBreakdownTable, TradePicker, BudgetLineCard, BudgetLineForm, and more)
• English and German translations added for all predefined trades, budget categories, and household item categories; hiCategory field fixed to use stable categoryId instead of display name

Fixes #1143

Test plan

• Unit tests pass (95%+ coverage) — budget breakdown service, route handlers
• Integration tests pass — translation key propagation through API responses
• Pre-commit hook quality gates pass
• German translations verified against glossary

Co-Authored-By: Claude dev-team-lead (Sonnet 4.6) noreply@anthropic.com
Co-Authored-By: Claude backend-developer (Haiku 4.5) noreply@anthropic.com
Co-Authored-By: Claude frontend-developer (Haiku 4.5) noreply@anthropic.com
Co-Authored-By: Claude translator (Sonnet 4.5) noreply@anthropic.com
Co-Authored-By: Claude qa-integration-tester (Sonnet 4.5) noreply@anthropic.com
Co-Authored-By: Claude e2e-test-engineer (Sonnet 4.5) noreply@anthropic.com

[steilerDev]

[security-engineer] Security review for PR #1156 — Story #1143: Predefined Category i18n Translation Keys.

Assessment

No blocking findings. Three areas reviewed: SQL migration, XSS risk from translationKey rendering, and data exposure.

---

SQL Migration (0030_translation_keys.sql)

All UPDATE statements use hardcoded literal string values and hardcoded literal WHERE clause IDs (e.g., WHERE id = 'trade-plumbing'). No user input reaches any statement in this migration. No SQL injection risk.

The migration runs inside the existing transaction wrapper in migrate.ts — rollback on failure is covered.

---

XSS Risk from translationKey in Frontend

getCategoryDisplayName() passes translationKey to i18next t() as a lookup key, not as rendered HTML:

if (!translationKey) return name;
return t(translationKey, { defaultValue: name });

The return value is a plain string from the i18n bundle — it is then rendered as a JSX text node or JSX attribute throughout the codebase ({getCategoryDisplayName(...)}, aria-label). React escapes both. No dangerouslySetInnerHTML, innerHTML, or eval usage anywhere in the diff. No XSS risk.

One nuance worth noting: a malicious or corrupt translationKey value from the DB (e.g., <script>...) would be passed as the i18n lookup key. i18next would fail to find it and fall back to name. Even if i18next somehow returned it, React's JSX renderer would escape it. Defense-in-depth is intact.

---

Data Exposure

translationKey is explicitly included in toTradeResponse(), toBudgetCategory(), and toHouseholdItemCategory() via explicit field mapping (the established pattern in this codebase). The field contains only static dotted-path keys like trades.plumbing — no user PII, no secrets, no internal structure beyond the i18n namespace. Exposure is intentional and benign.

createTrade(), createBudgetCategory(), and createHouseholdItemCategory() all hard-code translationKey: null on insert — user-created entries cannot receive a translation key through the API. Correct.

---

Checklist

• No SQL/command/XSS injection vectors in new code
• Authentication/authorization enforced on all affected endpoints (unchanged)
• No sensitive data exposed in the new field
• User input validated — translationKey is read-only from the DB, never accepted from API callers
• No new dependencies introduced
• No hardcoded credentials or secrets
• Error responses unchanged

Verdict: Approve.

[steilerDev]

[ux-designer]

Design review for PR #1156 — Story #1143: Predefined category names translatable via i18n.

Summary

This PR is primarily a text-content change. No new CSS files, no new design tokens, no layout changes. The getCategoryDisplayName() utility and its hook wrapper are a clean, non-visual abstraction. Design system impact is minimal.

Findings

Token Adherence

No new CSS introduced by story #1143. The two CSS module changes (DataTable.module.css, Filter.module.css) are DataTable bug fixes from the prior sprint, not from this story. Reviewing them for completeness:

• height: 36px hardcoded on .searchInput, .resetButton, .columnSettingsButton — no height token exists for this value in tokens.css, consistent with the DataTable toolbar height spec (#1136). Informational — acceptable since no token covers control height in this scale.
• Filter.module.css .filterDateInputConfirmed uses var(--color-primary) and var(--color-primary-bg) correctly. No hardcoded values.
• Drag drop indicator ::before uses var(--color-primary) and var(--radius-sm) — matches spec.

No issues with the i18n text additions.

Accessibility

• aria-label attributes on Edit/Delete buttons now use getCategoryDisplayName(), so screen readers announce the translated name rather than the raw database value. This is correct — the user sees the translated name, so the aria-label must match.
• TradePicker search also matches against the translated display name, so keyboard users searching in their locale will find items correctly.
• No ARIA regressions found.

Dark Mode

Text-only changes; all existing color tokens remain in place. No dark mode impact.

Visual Consistency

The useCategoryDisplayName hook correctly scopes to the settings i18n namespace, consistent with the key structure (settings:trades.plumbing, etc.). The defaultValue: name fallback ensures the raw DB name is shown if a key is missing — no blank text risk.

Verdict

Approved. No design system violations. The text changes improve accessibility by ensuring translated names are used consistently in both visible content and ARIA labels.

[steilerDev]

[product-owner]

Story #1143 — Predefined Category Translation Support

All 8 acceptance criteria verified against the diff:

AC	Criterion	Verdict
AC-1	translation_key nullable column on 3 tables; predefined rows non-null, user-created NULL	PASS — Migration 0030 adds column, UPDATEs predefined rows with keys
AC-2	API responses include translationKey	PASS — Services/SQL updated to SELECT and return the field; shared types updated
AC-3	English translation keys in en/settings.json	PASS — Keys under trades.*, budgetCategories.*, householdItemCategories.*
AC-4	German translations in de/settings.json	PASS — Corresponding German keys added
AC-5	Frontend shows translated string when key present	PASS — getCategoryDisplayName(t, name, translationKey) calls t(key, { defaultValue: name })
AC-6	User-created categories show raw name unchanged	PASS — Null/falsy key returns raw name without calling t()
AC-7	ALL UI locations use translation-aware display	PASS — getCategoryDisplayName used across 13+ components/pages
AC-8	Migration is backward-compatible (nullable column)	PASS — No NOT NULL constraint

Verdict: APPROVE — all acceptance criteria met.

[steilerDev]

[product-architect]

Architecture Review — Story #1143: Translatable Category Names

Verified

• Migration 0030: Correctly adds nullable translation_key column to trades, budget_categories, and household_item_categories. UPDATEs for predefined rows are well-structured with stable IDs. New user-created rows correctly get NULL.
• Schema.ts: Drizzle schema matches the migration DDL across all three tables.
• Shared types: translationKey: string | null added consistently to TradeResponse, TradeSummary, BudgetCategory, HouseholdItemCategoryEntity, CategoryBudgetSummary, InvoiceBudgetLineSummary, InvoiceBudgetLineDetailResponse, BreakdownWorkItemCategory, and BreakdownHouseholdItemCategory.
• Service layer: All converters correctly map translationKey. Create functions hardcode null for user-created rows. Budget breakdown service propagates the field through raw SQL queries.
• hiCategory bug fix: The change from catMeta.categoryName to catMeta.categoryId ?? '' is a correctness fix — the hiCategory field type is HouseholdItemCategory (a category ID string), not a display name. The new categoryName field provides the display name separately.
• Frontend utility: getCategoryDisplayName(t, name, translationKey) is clean — pure function with i18n fallback, plus a hook wrapper. Consistent usage across 12+ display sites.
• Test coverage: Comprehensive service, route, and client-side tests.

Findings

MEDIUM — Wiki not updated: Schema.md and API-Contract.md were not updated to reflect the new translation_key column on three tables or the changed API response shapes. This is a documented requirement in CLAUDE.md. Recurring gap from prior reviews (#399, #414, #416, #612).

LOW — CLA Check failing: Unrelated to code changes but should be investigated.

Verdict

Approve — code changes are architecturally sound, types are consistent, migration is correct. Wiki gap is medium and should be addressed in refinement.

[github-actions]

🎉 This PR is included in version 2.2.0-beta.20 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version 2.2.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀