kandev/docs/specs/platform/requirements/i18n.md

status, system, created, updated, owners

status	system	created	updated	owners
active	platform	2026-07-27	2026-09-21	jcfs

Internationalization (i18n) Requirements

Overview

Kandev's i18n foundation lets migrated web surfaces externalize copy, switch locale, and format dates and numbers per language. English remains the source locale. The shipped human locales are European Portuguese, Simplified Chinese, Traditional Chinese (Taiwan and Hong Kong), and Japanese. The pseudo-locale remains 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. English remains the source locale. The shipped human locales are European Portuguese, Simplified Chinese, Traditional Chinese (Taiwan and Hong Kong), and Japanese. The pseudo-locale remains 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, zh-hk, and ja; 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; Japanese details live in japanese-locale.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), Traditional Chinese (Hong Kong), and Japanese (日本語) 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.