Skip to content

[RFC] i18n foundation: react-i18next + zh-CN, phased approach #404

Description

@guobailin

Summary

Issue #191 ("需要中文") and its thread show clear community demand for a Chinese UI, and other locales will follow. Today the GUI has no i18n infrastructure: UI copy is hardcoded inline across ~72 TSX files (~350 user-facing strings). Before anyone opens a large translation PR, I'd like to propose a small, phased i18n foundation and check it fits your roadmap.

Current state (from reading surfaces/gui/src)

  • No i18n library in package.json; strings are inline literals in components.
  • Scope is still modest: ~350 extractable UI strings — cheap to instrument now, expensive later.

Proposal

Phase 1 (foundation, one PR, intentionally small)

  • Add react-i18next + i18next (de-facto React standard; zero new heavy deps; lazy-loads locale JSON so the bundle stays lean).
  • Introduce src/i18n/ with en.json (source of truth) and zh-CN.json.
  • Migrate one pilot surface end-to-end (suggestion: the onboarding / empty-state + Settings sections) as the reference pattern for contributors.
  • Add a short docs/i18n.md: how to wrap strings, pluralization rules, how to add a locale.

Phase 2 (community-driven, after Phase 1 lands)

  • Good-first-issue style tickets to externalize remaining components screen-by-screen.
  • Locales beyond zh-CN contributed by native speakers (ja, ko, es, …).

Explicitly out of scope for now: backend/persona prompt localization, date/number formatting, RTL.

Why react-i18next

  • Works with the existing minimal React setup (no state library) and Vite.
  • Trans component handles inline markup without restructuring JSX.
  • ICU plurals via i18next-icu later if needed — not required for zh-CN.

Questions for maintainers

  1. Does i18n fit the current roadmap, and is the phased shape above acceptable?
  2. Any preference on framework or file layout before I start?
  3. If yes to both, I'm happy to send the Phase 1 PR (with before/after screenshots per the contributing guide).

Happy to adjust to whatever direction you prefer — mainly want to avoid a 350-string mega-PR nobody wants to review. 🙂

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions