refactor(i18n): track cross-surface i18n and l10n governance

[limityan]

Background

BitFun is moving internationalization across Web UI, mobile-web, installer, backend, and relay static pages toward one shared language contract while keeping each product surface responsible for loading only its own resources. Recent i18n PRs have already introduced the shared contract, loading boundaries, audit guardrails, missing-key fixes, and part of the redundant-key cleanup.

This issue is the long-lived snapshot and tracking entry for the broader i18n / l10n module requirements. It is not tied to the lifecycle of any single PR. Related PRs can merge or close without closing this issue; keep it open until the overall module capability reaches the expected stable state.

Related PRs

These PRs are context links only, not closing conditions:

• feat: add shared i18n contract guardrails #948 feat: add shared i18n contract guardrails
• feat: refine i18n loading guardrails #950 feat: refine i18n loading guardrails
• refactor: harden i18n audit coverage #952 refactor: harden i18n audit coverage
• refactor(i18n): harden locale audit guardrails #957 refactor(i18n): harden locale audit guardrails

Identified Problem Areas

• Multiple product surfaces need shared language identity, aliases, fallback chains, and surface defaults, but they must not share or load each other's full resource catalogs.
• Web UI, mobile-web, installer, backend, and relay static pages need consistent and auditable resource ownership, loading strategy, and key access rules.
• Stable product concepts, feature names, tool names, and status labels still have repeated values and potential drift; they should gradually converge into shared terms or be explicitly owned by a surface/feature namespace.
• Some keys are reached through dynamic construction, metadata, enum/error-code mappings, or fallback-key arrays, so key deletion needs a provable dynamic-reference boundary.
• Key parity only proves that locales have the same keys; it does not prove localization quality. For example, zh-TW may still contain copied zh-CN text, stale English, or inconsistent terminology.
• Some Web UI namespaces are large, and the bootstrap namespace set needs ongoing control so a unified contract does not become a unified large startup bundle.
• Legacy literal fallback and hardcoded-copy debt still exists and should keep shrinking without allowing new debt.

Requirement Snapshot

Unified Language Contract

• All frontend/backend boundaries should exchange canonical locale ids, such as zh-CN, zh-TW, and en-US.
• Browser language, legacy config, URL params, installer UI code, and other input boundaries may accept aliases, but they must resolve to canonical ids as early as possible.
• Language metadata, fallback chains, surface order, surface defaults, and shared terms should have a centralized and generated source of truth.

Per-Surface Resource Boundaries

• Each product surface should own and load only its own resources.
• Web UI should keep the bootstrap namespace plus lazy namespace model.
• mobile-web, installer, backend, and relay static pages should not import the Web UI locale catalog.
• Shared terms are an explicit concept layer, not a global fallback namespace.

Key And Value Policy

• Keys should be stable and semantic; avoid English-copy-shaped keys, position-shaped keys, and temporary abbreviations.
• common should contain only truly generic UI atoms. Workflow, page, toast, validation, and feature copy should stay in the nearest owner namespace.
• Stable concept labels should prefer shared.*; context-sensitive wording should stay in the owning surface or feature namespace.
• Repeated values should be reviewed through reports, but repeated value does not automatically mean redundant key.

Quality Guardrails

• Audits should distinguish confirmed unused keys, dynamic-key candidates, shared-term duplicates, and l10n quality candidates.
• Confirmed unused keys can be removed. Dynamic-key candidates need an allowlist or code-level mapping comment. L10n quality candidates belong to translation-quality work, not structural key deletion.
• CI should cover contract sync, key parity, placeholder parity, static key existence, literal fallback budget, hardcoded-copy budget, and surface boundaries.
• Local development should keep the minimum-check principle and avoid making heavy rebuilds the default precheck for every i18n change.

L10n Evolution

• Establish terminology and regional-quality checks for zh-CN, zh-TW, and en-US.
• Identify direct zh-CN reuse in zh-TW, stale English values, placeholder semantic mismatches, and inconsistent brand/feature terminology.
• Static HTML fallback text should be used only for first paint and failure resilience, not as a replacement for locale resources.
• Future work may introduce pseudo-locales, translation QA reports, terminology glossaries, or translation pipeline integration as needed.

Done Criteria

• Adding a locale or product surface has clear entry points for the language contract, resource boundary, fallback rules, generated files, and audit rules.
• Product surfaces do not load resource catalogs that they do not own merely because the language contract is shared.
• Key deletion has machine-readable evidence and can explicitly rule out dynamic key references.
• Stable concept names have an authoritative source, repeated values have a reviewable report, and l10n quality issues have a separate tracking category.
• Documentation is sufficient for future contributors to add, read, migrate, and audit i18n resources consistently.