Frontend and i18n rules for work under web/.
- React 19 + Vite + TypeScript + Tailwind v4.
- Source:
web/src; static assets:web/public. - Production bundle must stay synced to
internal/web/distviamake frontendormake build. - Organize React modules by feature within
web/src/{pages,routes,components}. - File names should be descriptive, e.g.
torrent-table.tsx. - Style: two-space indentation, double quotes, trailing commas on multiline literals, Unix line endings.
- Frontend tests: Vitest + React Testing Library, colocated as
*.test.tsxnear the component.
- Colocate
*.test.ts(x)specs with the change. Prefer extracting logic into hooks (web/src/hooks/) and pure helpers (web/src/lib/) so it is unit-testable without mounting the whole tree (seeweb/src/hooks/torrent-table/for the pattern). - Vitest runs with
globals: false+ jsdom and no setup file:- Import test globals explicitly:
import { describe, it, expect, vi } from "vitest"; userender/renderHook/actfrom@testing-library/react. - No jest-dom matchers (
toBeInTheDocument,toHaveTextContent, …) — assert plain DOM:el.textContent,el.getAttribute(...),expect(node).toBeNull(). - When mounting components with effects, mock their boundaries (
@/lib/api, router, context providers,useVirtualizer, query hooks) and return a stable singleton from each mock — fresh objects per render loop effects and OOM the worker. Usevi.hoisted()for values referenced insidevi.mockfactories.
- Import test globals explicitly:
- jsdom does no real layout, scroll, or pointer/drag work — it renders zero virtual rows and cannot exercise virtualization, dnd-kit, or scroll restoration. Unit-test the extractable logic (reorder math, row-height mapping, handler wiring) and manually smoke anything visual or interactive; a green suite is not full coverage. Run targeted with
cd web && npx vitest run <path>; CI runs the full suite viamake test-frontend.
- Use
useEffectonly to sync with external systems: DOM, subscriptions, network. - Avoid derived state in Effects; calculate during render or use
useMemofor expensive compute. - Put user-driven logic in event handlers.
- To reset state, prefer a
keyor render-time adjustment. - Fetch Effects must guard stale responses with cleanup/abort.
- Reference: https://react.dev/learn/you-might-not-need-an-effect
Locales live under web/src/i18n/locales/<lang>/ with 10 namespaces:
common, auth, settings, torrents, dashboard, crossseed, rss, search, instances, automations
English is fallback/eager-loaded. Other languages are lazy-loaded by initI18n() / changeLanguage() through import.meta.glob in web/src/i18n/index.ts. Supported today: en, zh-CN, fr, de, it, ko.
pnpm check:i18npnpm check:i18n:hardcodedpnpm check:i18n:raw-backend-valuespnpm check:i18n:zh-cnpnpm check:i18n:frpnpm check:i18n:depnpm check:i18n:itpnpm check:i18n:ko
Run relevant checks when touching UI strings, locale JSON, web/src/i18n/index.ts, or formatter hooks.
- Add all 10 namespace JSON files under
web/src/i18n/locales/<lang>/. - Add code to
supportedLanguagesand display name tolanguageNamesinweb/src/i18n/index.ts. - Add/adapt a locale coverage script if the locale is not
zh-CN. - Run
pnpm check:i18n. - Update the supported-language list in
README.md(Features) anddocumentation/docs/intro.md(Features + Languages section) so the promoted list stays accurate.
Coverage must compare against English for missing/extra keys, interpolation placeholders, HTML tag parity, plural forms, empty strings, encoding, and JSON validity.
- Never hardcode text or raw backend variables (e.g.,
run.status,task.status) directly into JSX. If a status or string is displayed to the user, you MUST create a correspondingi18nkey (e.g.,statusLabels) in the relevant JSON namespace and render it viat(). - Read English namespace JSON and relevant UI first; translate in product context.
- Preserve placeholders, HTML tags, keys, examples, paths, URLs, commands, and technical notation unless the checker allows an exception.
- Keep a glossary for product names and torrent/domain terms.
- English plurals use
_one/_other; Chinese needs_other. Legacy_pluralkeys are manually dispatched and must exist in all locales. - Product/ecosystem terms often stay English where clearer:
qBittorrent,Prowlarr,DHT,PEX. - Chinese text should prefer full-width
,。:;!?; half-width is fine inside URLs, IPs, paths, and technical notation.
web/src/components/torrents/TorrentDetailsPanel.tsx live row state is stream-backed via useSyncStream; polling is fallback while stream unavailable. Content/files and Peers tabs still poll on interval, but polling is tab-scoped and visibility-gated.