Repository navigation
i18n: move UI translations to versioned DB ledger and complete 8-locale coverage #922
Description
Buyer-visible gap
LineageWeave currently declares only en, ko, zh, ja, and vi in frontend/src/i18n.ts, and translation resources are compiled into the SPA source. The product contract requires KO/EN/JA/ZH/VI/ES/DE/FR and a database-distributed, versioned translation ledger with screen-key caching; ontology labels remain a separate semantic concern.
This is a LineageWeave presentation/read-model boundary. Do not copy ontology truth, locale management, or other CWL owners into this repository. If a released shared i18n owner becomes available, consume it through a versioned contract/ACL instead of duplicating it.
Required repair
- Add
es,de, andfras first-class supported locales without treating English fallback as translated coverage. - Replace the SPA-bundled translation dictionary as the production source of truth with a normalized PostgreSQL translation ledger. Keep the client payload scoped by product/screen/key/locale/version and cache by immutable/versioned ledger identity so locale switching does not require shipping the full translation corpus in the JS bundle.
- Preserve English source keys as stable message identities for the migration only if an ADR demonstrates collision/versioning safety; otherwise introduce an explicit stable message key and migrate callers without breaking existing accessibility names.
- Keep ontology labels out of the translation ledger. Translation records are presentation resources, not semantic ontology truth.
- Fail closed on missing required production translations for the eight supported locales in release/build evidence; development fallback must be explicit and observable, not silently counted as coverage.
- Verify KO/EN/JA/ZH/VI/ES/DE/FR text expansion, CJK rendering/font fallback, normal/loading/empty/error/permission states, responsive layouts, keyboard/focus semantics, and screen-reader names for material UI.
- Add migration/rollback, seed/version provenance, cache invalidation semantics, tenant/scope rules if applicable, API/read-model contract, and operational evidence. No cross-service SQL.
- Update PRD/TRD/ARCHITECTURE/ADR/UX/OPERABILITY/TEST_STRATEGY and
docs/product-technical-gap-baseline.mdcode-current with the chosen transaction/cache/version boundary.
RED acceptance
- A contract test must demonstrate that
SUPPORTED_LOCALESis missinges,de, andfron current code. - A packaging/build assertion must demonstrate that production translation payloads currently live in the frontend source/bundle rather than a versioned database resource.
- An i18n completeness test must distinguish a real translation from English fallback and fail when any required screen key is missing in one of the eight supported locales.
GREEN acceptance
SUPPORTED_LOCALEScontains exactly the supported product locales KO/EN/JA/ZH/VI/ES/DE/FR (canonical locale tags documented).- Production translations are read through the versioned DB-ledger/API boundary and screen-key cache; the frontend bundle is not the canonical translation store.
- Full current-head i18n/accessibility tests cover all eight locales and all material states; no untranslated fallback is counted as translated coverage.
- Migration rollback and immutable/versioned resource provenance are demonstrated on current head.
- No ontology-label conflation, raw cross-service SQL, or mutable sibling dependency is introduced.
Open material-UI lanes covered by this gate
At the 2026-09-03 live sweep, this release gate applies to open material UI work including #667 (Ask history), #679 (public-claim verification), #770 (project-history timeline), #774 (Operations Dashboard status), #802 (leftover-map explained-share presentation), #903 (Event Lineage), #907 (Affiliate Tree), #909 (Customer Master), and the #918 → #920 → #921 leftover-map composition stack. These PRs retain their own domain/test findings, but none may count five-locale SPA-bundled predecessor evidence as completion of this eight-locale DB-ledger requirement. Keep conflicts and unique deltas repairable; do not close them merely because this shared presentation prerequisite is unfinished.
Activity
seonghobae commentedon Sep 3, 2026
Starting the RED/GREEN repair this cycle on a main-targeting branch (
feat/i18n-translation-ledger-eight-locales, ADR 0357 / v2.31.0). Stacked leftover-map origin ADRs 0272–0356 stay on #921 and descendants; this increment does not mix into that stack. Canonical locales:enkojazhviesdefr. Production translations persist to a versioned PostgreSQL ledger with screen-key cache identity; English source keys remain message identities only when they equal theentranslated string. English fallback is not translated coverage for the other seven locales. Ontology labels stay out of the ledger.seonghobae commentedon Sep 3, 2026
Cycle 2026-09-03T05:01Z: writes work this cycle (comment/create-branch). Independent of leftover-map origin stack #912–#921 (ADR 0272–0356).
Implementing ADR 0357 / v2.31.0 on
feat/i18n-translation-ledger-eight-locales(from main@0f1d447):ui_product/ui_screen/ui_locale/ui_message_key/ui_ledger_edition/ui_translated_string(migration 0246){product}:{screen}:{locale}:{edition}lineageweave/fixtures/ui_translated_strings.json(edition 1)GET /api/ui-translationsread modelNever invent a leftover score or a theta. No self-approve. Draft PR onto main after tests + push. Independent exact-head APPROVE required before squash-merge.
seonghobae commentedon Sep 3, 2026
#929 now carries the #922 persistence/read-model foundation on exact protected base
b0e94aa2a6f7a943f96dc5c4f2fdecd0021978a1.Implemented under Draft:
ui_translation_resource/ui_translation_key/ui_translation_textschema;ko/en/ja/zh/vi/es/de/fr;370f83a...RED →bb61753...fix);ba7af630b390c5edf33bc112bc624d56f28d0b09.#922 stays open. Buyer-visible completion still requires FastAPI locale-request admission and
frontend/src/i18n.tsto stop using the old five-locale/bundled-copy contract, actual screen-resource seeding/versioning, and current-head 8-locale normal/loading/empty/error/permission/responsive/a11y evidence. Current #929 checks are non-terminal, so no Ready/merge claim is being made.seonghobae commentedon Sep 3, 2026
#929 advanced the DB-ledger/read-model foundation, but #922 remains open. Review of predecessor
ba7af630b390c5edf33bc112bc624d56f28d0b09found that an exact-identity Valkey payload could contain only a subset of a published screen's required keys and still bypass PostgreSQL. RED3b68e4ed16731e97e8743748ab5775fa78240064captures the partial-cache case; repair249b6cfba21c37899cae10ee7519d4e77132269dnow resolves the published required-key set from PostgreSQL before accepting an explicit-version cache hit and requires exact key-set equality; verification-contract alignment isf666a5b12b9ddd0bbef040c238ef541ec1fa1af1. ADR 0362 is code-current at7df347874ae26b95947be14b0cb97d7789b8d07aand remains Proposed. Buyer-visible completion is still gated on released foundation + API/frontend cutover, actual versioned screen resources, and eight-locale UI/a11y evidence.seonghobae commentedon Sep 3, 2026
#929 foundation progressed beyond the earlier cache repair. Current exact head
00896929ab67427c53f7809b533857e65ab20ca7now also rejects padded PostgreSQL product/screen identities (REDd75d0a96...→ repaird4d03da3...) and makes immutable publication provenance database-owned. A new real-PostgreSQL test path (d982d265...) applies migrations 0001 + 0044 + 0246 in a throwaway DB and verifies canonical identity, publication immutability/provenance, and eight-locale completeness. That runtime test exposed PostgreSQLnow()as transaction-start time; RED74f0521b...→ repaire2429b14...now usesstatement_timestamp()so a long transaction cannot backdate the publication receipt. ADR 0362 remains Proposed. #922 stays open: API/frontend cutover, versioned production screen resources, eight-locale material-state/a11y evidence, and the wider code-current product/technical docs are still outstanding.docs(gaps): derive PRD/TRD/UML/Gap/actions for #922 without volatile …
seonghobae commentedon Sep 11, 2026
Current i18n foundation/consumer state after fresh review and non-force convergence:
f898399c5ff9ab89fe440d2e66985860e141620c506caa9...and causal fix atf898399...34646694392is terminal GREEN: frontend lint/tests/build/Storybook and PostgreSQL/full-suite both completed successfully; PROV-O, Ontology Pages, and SAST are also GREEN.github#810); exact LineageWeave canary evidence is already recorded thereverdict=pendingbefore the later dispatcher completed;.github#1929owns terminal receipt publication/wake ordering. This is not a LineageWeave source-scan verdict.4fa09d9051978b408c6998009b21fd166358a9e5, preserving the prior Customer Master delta. Its predecessor GREEN does not transfer to the converged head, so feat(i18n): consume published Customer Master screen copy #932 is temporarily Ready only to execute fresh current-head Tests34648698628; those checks are running and are not yet acceptance evidence.Issue #922 remains open. The database-ledger foundation still does not prove a complete reviewed/published
customer-masterresource for allko/en/ja/zh/vi/es/de/fr, and the product-wide locale selector remains limited to product-completeko/en/ja/zh/virather than pretending untranslated surfaces satisfy eight-locale product coverage. No English fallback is counted as translated coverage.seonghobae commentedon Sep 11, 2026
Fresh consumer evidence from #858: exact head
2689a80f09aa0f47444b2daeddae24882ae9667bkeeps a behavior-level Vitest RED for the grouping-comparison rank accessible name acrossko/zh/ja/vi. The current branch falls back to the English key for that new screen-reader label. I removed an intermediate test that required literal entries infrontend/src/i18n.ts, because that would incorrectly make the SPA dictionary the production authority and conflict with this issue's DB-ledger/screen-key-cache contract. Treat historical v2.75 translations only as semantic copy evidence; GREEN for #858 should come from the current canonical translation boundary without English fallback or a competing static authority.seonghobae commentedon Sep 17, 2026
2026-09-17 live repair update: #929 now has an executable Customer Master eight-locale review candidate rather than only the generic ledger foundation.
RED
eb6eca97df64656ab0bce1e5d3deeaa7c5566760requires the exact governed 37 Customer Master keys ×ko/en/ja/zh/vi/es/de/fr= 296 nonblank values, placeholder parity for parameterized copy, no non-English value equal to the English/source key, idempotent seed replay, database publishability, and rollback that removes an unpublished draft but refuses an immutable published resource.Causal product repair
0426a70a627fe01665235722d5bf4d926cde9b74addsmigrations/0248_customer_master_translation_draft.sqlplus rollback. It intentionally leaveslineageweave/customer-master/v1indraft: the localized copy has not received qualifying independent language/product review, so this run does not turn it into immutable publication authority.Current parent head
64fa200e46854878b3154880af678afa69284fdbadds a test-causality correction only. The rollback-refusal migration deliberately opens a transaction and raises on published resources, so the expected exception leaves that transaction aborted; the test now issuesROLLBACKbefore asserting the previously committed published resource is durable. Current parent Tests/PROV-O/Ontology Pages are Draft-skipped and SAST/Security/CodeQL are queued, so no current-head GREEN is claimed.Consumer #932 was immediately converged ordinary/non-force to
8133220817a875da72f4bbc5dd011f30f060a126; its publication review thread remains open. The remaining #922 acceptance gap is independent review -> hosted PostgreSQL GREEN -> explicit publication -> authenticated API/browser eight-locale state/a11y/font/text-expansion evidence, rather than absence of a concrete 8-locale resource. Product-wide locale admission remains separate and no English fallback was promoted.seonghobae commentedon Sep 17, 2026
2026-09-17 current evidence update: #929 moved to exact
d4f42f579663e88a0c9af0cc492aa6ff7cae96ee, with direct consumer #932 non-force/two-parent converged tofb2422537216a19280860f710b55f4df963902db.Fresh semantic-upgrade RED
8b395738d2815ee002c85b27648841a06aa5e45fshows the prior same-name constraint upgrade still relied on token presence: a canonical shape CHECK could mentionretiredwhile requiring the wrongresource_id IS NOT NULLshape and therefore block ordinary owned-root retirement. Repair667aca9b233f269d868fb99f8740aa66002b09ceversions the two repository-owned canonical ownership constraints with catalog comments; unversioned same-named predecessors are replaced once, while differently named operator/DBA checks remain untouched. Exact headd4f42f57...adds marker assertions plus OID-stable replay evidence so subsequent migration replay does not repeatedly rebuild/validate the constraints.This narrows the DB-ledger migration/replay gap but does not satisfy #922 GREEN acceptance. #929 Tests
35236145547remains pre-runner (Full suite105252445377,Frontend105252445197, both queued withrunner_id=0,steps=[]), the ownership/replay review thread is unresolved, and the 37×8 candidate remains unpublished pending independent language/product review and authenticated eight-locale browser/a11y/CJK/text-expansion evidence. #932 Tests35236229290is Draft-policy skipped and is not GREEN.