Internationalization (i18n) Requirements

Overview

Kandev's i18n foundation lets migrated web surfaces externalize copy, switch locale, and format dates and numbers per language, but English is still the only human language shipped. Adding Simplified Chinese makes the existing localized surface usable by Chinese-speaking users while preserving English as the source language and the pseudo-locale as the migration QA oracle.

Requirements

REQ-PLATFORM-I18N-001: Internationalization (i18n)

Intent: Kandev's i18n foundation lets migrated web surfaces externalize copy, switch locale, and format dates and numbers per language, but English is still the only human language shipped. Adding Simplified Chinese makes the existing localized surface usable by Chinese-speaking users while preserving English as the source language and the pseudo-locale as the migration QA oracle.

Acceptance criteria

AC-PLATFORM-I18N-001.1: The web UI SHALL render all user-facing text through a translation layer (i18next t("ns:key") / react-i18next <Trans>), not from inline literals. "User-facing text" covers visible copy, placeholder, aria-label/aria-description, title, alt, toast/sonner messages, form-validation messages, empty-state and error copy, and confirm/dialog text.
AC-PLATFORM-I18N-001.2: Native UI plugins SHALL register plugin-owned catalogs through the public plugin SDK. Kandev SHALL isolate them by verified plugin identity, require English fallback copy, expose the active locale through imperative and reactive scoped translation APIs, and remove their resources with the plugin lifecycle. Plugin catalogs SHALL NOT mutate built-in or sibling-plugin namespaces.
AC-PLATFORM-I18N-001.3: English SHALL remain the source locale. The shipped human locales SHALL be en, pt-pt, zh-cn, zh-tw, and zh-hk; copy lives in per-namespace JSON catalogs keyed by stable ids. The pseudo catalog is generated from en, never hand-edited. Traditional Chinese details live in traditional-chinese-locales.md.
AC-PLATFORM-I18N-001.4: The app SHALL expose a language switcher in Settings. It lists English, European Portuguese, Simplified Chinese, Traditional Chinese (Taiwan), and Traditional Chinese (Hong Kong) by their fixed endonyms. Selecting a locale re-renders the UI without a full reload and persists the choice across restarts. Development and E2E builds additionally list the pseudo-locale (see below).
AC-PLATFORM-I18N-001.5: The app SHALL ship a pseudo-locale (pseudo) that transforms every extracted message (accents + padding, e.g. Ĉřéàţé ţàśķ) so QA can visually confirm a string was externalized and detect truncation. The pseudo-locale is only selectable in dev/e2e builds, not in production builds.
AC-PLATFORM-I18N-001.6: Date, time, relative-time, and number formatting SHALL be locale-aware, driven by the active locale rather than hardcoded English strings. The custom apps/web/lib/utils/time.ts timeAgo helper is replaced by a locale-aware relative-time formatter, and date-fns calls take the active locale.
AC-PLATFORM-I18N-001.7: The document <html lang> attribute SHALL reflect the active locale (both in the Go-rendered shell's default and after client locale changes).
AC-PLATFORM-I18N-001.8: The @kandev/ui shared primitives' built-in strings (≈12 accessibility/ default labels) SHALL be translatable without the package depending on the app's i18n runtime — via defaultProps-style overridable string props or a lightweight injected dictionary, so the package stays framework-agnostic.

System design

The migrated technical source is split into part 1.

3.8 KiB Raw Blame History