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. 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

These PRs are context links only, not closing conditions. Keep this issue open until the overall module capability reaches the expected stable state.

• 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
• refactor: add i18n governance report #961 refactor: add i18n governance report
• refactor: enforce i18n governance baseline #962 refactor: enforce i18n governance baseline
• refactor: reuse shared i18n terms across surfaces #968 refactor: reuse shared i18n terms across surfaces
• refactor(i18n): tighten shared terms and dynamic key proofs #972 refactor(i18n): tighten shared terms and dynamic key proofs

Current Quantitative Snapshot

Latest snapshot from the #972 branch:

• confirmedUnusedKeys: 0
• dynamicKeyCandidates: 194 (source-proven: 194)
• sharedTermDuplicates: 206
• l10nQualityCandidates: 1093
• Remaining shared-term duplicates by surface: web-ui 183, core 15, mobile-web 8, installer 0, relay-static-homepage 0

Latest Key Comparison: #972

Incremental comparison is the #968 snapshot vs the #972 branch.

Metric	Before	After	Delta
sharedTermDuplicates.maxTotal	214	206	-8
sharedTermDuplicates.bySurface.installer	3	0	-3
sharedTermDuplicates.bySurface.core	18	15	-3
sharedTermDuplicates.bySurface.relay-static-homepage	2	0	-2
product.name duplicate candidates	6	0	-6
features.remoteControl duplicate candidates	2	0	-2
Dynamic candidates with source references	0	194	+194
Dynamic candidates marked source-proven	0	194	+194

Review follow-up in #972: stale relay static $shared references are now covered by a contract test and fail i18n:audit, so self-contained static pages cannot silently point at missing shared terms.

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.

[limityan]

Update from #972 (refactor(i18n): tighten shared terms and dynamic key proofs).

Key Comparison

Metric	Before	After	Delta
Shared-term duplicate candidates	214	211	-3
Installer shared-term duplicates	3	0	-3
product.name duplicate candidates	6	3	-3
Dynamic key candidates	194	194	0
Dynamic candidates with source references	0	194	+194

Notes:

• Installer titlebar defaults now read shared.product.name; copied titlebar.default keys were removed.
• Dynamic-key contracts now require audited sourceReferences, so future cleanup can distinguish documented dynamic access from removable keys.

[limityan]

Follow-up snapshot for PR #977.

This PR continues the i18n/l10n governance track without closing this issue. It adds audit visibility for literal fallback and direct locale-formatting debt, lowers several existing debt baselines, keeps remaining work visible for later cleanup, and adds a review follow-up so direct Intl.* calls without new cannot bypass the locale-format audit.

Metric	Before	After #977	Delta
Confirmed unused keys	0	0	0
Dynamic key candidates	194	193	-1
Shared-term duplicate candidates	206	201	-5
L10n quality candidates	1093	1087	-6
Literal defaultValue fallbacks	457	396	-61
Direct locale-format calls	32	24	-8

Review/CI follow-up:

• Fixed Web UI test mocks that still depended on literal fallback behavior after static fallback strings were removed.
• Hardened the locale-format audit to catch both new Intl.* and bare Intl.* calls, plus existing toLocale* calls.
• GitHub Actions CI passed on a3c966bf: Frontend Build and all Rust Build Check jobs for ubuntu-latest, macos-15, and windows-latest.
• Local validation includes i18n contract/audit/report, Web UI full tests, Web/Mobile type checks, Web/Mobile builds, repo hygiene, GitHub config, and diff hygiene.

Remaining work is still tracked here rather than tied to PR closure: continue reducing Web UI literal fallbacks, review high-confidence zh-TW localization candidates, migrate only semantically stable shared concept labels, and move the remaining direct locale-formatting call sites behind surface i18n helpers.