toga-ai 1.0.415 → 1.0.416

package/knowledge/sessions/2026-07-22-compass-canada-french-localization-tcox.md

@@ -0,0 +1,78 @@
+---
+type: session
+slug: compass-canada-french-localization
+title: Compass Canada French localization — storefront done, persona DB backend deferred
+author: tcox
+repos: [toga2-commerce, dbchanges2, _underscore]
+framework: "2.0"
+client: compass-canada
+status: active
+created: 2026-07-22
+updated: 2026-07-22
+---
+
+# Session: compass-canada-french-localization
+**Date:** 2026-07-22
+**Project/Repo:** toga2-commerce (2.0), plus dbchanges2 + _underscore for the deferred backend
+**Task:** Finish Compass Canada French localization in the toga2-commerce storefront (Manage Requests, persona names, Account settings, Get Support, Kits, Open TOGa Supply, Orders for Others, order search, Get Support image) — frontend shipped; persona-name DB backend drafted but explicitly deferred.
+
+---
+
+## What WORKED
+- Account "Settings" tab → "Paramètres" and persona placeholder → "p. ex. Jean Tremblay" in all 4 French role files (`src/pages/Account/viewModel/FIELDS/COMPASSCANADA/FRENCH/<ROLE>/{ACCOUNTTABFIELDS,MYACCOUNTFIELDS}.json`). Evidence: JSON parse + EN/FR key-parity script passed.
+- Home page French: ADMIN file Kits→Trousses fixes (5 values); SUPERUSER `HOMEPAGEFIELDS.json` was mostly English and was fully rewritten to match USER/MANAGER French conventions; MANAGER itemsSection → "Articles". Evidence: parity + parse OK.
+- Hardcoded JSX keyed through HEADERFIELDS with in-code English fallbacks (COMPASS/QUAD unaffected): new `adminSubmenu.manageRequests` ("Gérer les demandes") and `alertsSubmenu.*` (markAllAsRead/openExternalLink/alertSingular/alertPlural/allUpToDate) in all 8 COMPASSCANADA HEADERFIELDS files; wired in `NavIconItem.tsx`, `AlertSubmenu.tsx` (+ `Submenus/types.ts`). Evidence: `npx tsc --noEmit` exit 0.
+- Orders for Others heading/subheading keyed (`ordersForOthersHeading`/`ordersForOthersSubheading`) and order search keyed (`pageSearchInput`) in ORDERHISTORYFIELDS (8 files); wired in `AccountPage.tsx` and `MyOrdersView.tsx`. French matches each role's existing phrasing style.
+- Get Support illustration switches by language: `GetSupportPage.tsx` uses `language?.startsWith("fr") ? get-support-img-french.svg : get-support-img.svg`; view model exposes `language`. Evidence: developer confirmed "Seeing it now".
+- Persona query cache fix: added `userPersonaDataOnLogin` + `userPersonaDataOnViewAs` to `LANGUAGE_SENSITIVE_QUERY_KEYS` in `src/queries/queries.ts` so persona names refetch on language switch.
+- Backend persona-translation artifacts drafted (5 files, see file table) — sql-reviewer verdict SAFE TO MERGE, 0 critical; reviewer's one warning (name-based JOIN) fixed by switching the 30 known personas to uuid-based JOIN.
+- Knowledge captured & pushed: CREATE `2.0/apps/_underscore/features/persona-name-translation.md` (status: draft), UPDATE `client-fields.md` (fr-CA correction), UPDATE compass-canada profile.
+
+## What did NOT work — DO NOT RETRY THESE
+- **`language === "fr"` comparison for French detection** — fails silently. The fields registry key and stored language value for COMPASSCANADA French is **`fr-CA`** (see `src/fieldsConfig/index.ts:909`; Account settings save stores the option uuid `en`/`fr-CA` via `setLanguage`). The team doc client-fields.md previously claimed `en`/`fr` — that was stale and is now corrected. Always use `startsWith("fr")`.
+- **Direct DB verification from this dev machine** — ALL endpoints timed out (connect ETIMEDOUT): `reader1.client.database.togahub.com`, `reader1.core.database.togahub.com`, both `production-*-global...rds.amazonaws.com` endpoints, `dev.sandbox.database.togahub.com`, and localhost MySQL (refused — none running). RDS clusters are VPC-restricted; needs VPN or the claude.ai "TOGa Database Integration" connector (not authorized in this session). A ready-to-run check script exists but the scratchpad is session-specific — recreate from the queries in the persona-name-translation.md doc.
+- **Seeding PersonaTranslations by joining on `Personas.name` for all rows** — sql-reviewer flagged it: `Personas.name` has no unique constraint, so a name join can fan out / mis-attach translations. Fixed: the 30 known personas join on `uuid`; only the 3 out-of-band personas (Admin Canada, MacBooks, Managers/VIPs) still match by name because their uuids exist only in the live DB.
+
+## Not tried yet (candidates for next session)
+- Run the DB pre-flight checks (needs VPN or TOGa DB connector): live `MAX(Core.Records.id)` must be 345 and `MAX(Core.RecordFields.id)` 2457 (migrations claim 346 / 2458-2462); `SELECT id,uuid,name,number FROM Personas ORDER BY id` on the Compass Canada client DB — confirm the 3 out-of-band personas exist and `GROUP BY name HAVING COUNT(*)>1` returns nothing; confirm `Languages` has `fr-CA`.
+- Confirm with the business whether the persona glossary has rows below "Managers/VIPs → Gestionnaires/VIP" (screenshot was cut off there) and extend the seed if so.
+- Commit/PR the frontend work (feature branch per git rules — never commit to `_main`); commit the backend files separately when un-deferred.
+- Visual verification pass against the developer's screenshots (was planned; not yet done in-session).
+- toga2-commerce full `npm run build` / smoke run (only `tsc --noEmit` was run).
+
+## Current file state
+| File | Status | Notes |
+|------|--------|-------|
+| toga2-commerce `.../FIELDS/COMPASSCANADA/FRENCH/<4 roles>/ACCOUNTTABFIELDS.json` | modified | Settings → Paramètres |
+| toga2-commerce `.../FRENCH/<4 roles>/MYACCOUNTFIELDS.json` | modified | persona placeholder French |
+| toga2-commerce `.../FRENCH/{ADMIN,SUPERUSER,MANAGER}/HOMEPAGEFIELDS.json` | modified | Trousses/Trousse; SUPERUSER fully retranslated |
+| toga2-commerce `.../COMPASSCANADA/{ENGLISH,FRENCH}/<4 roles>/HEADERFIELDS.json` | modified | + adminSubmenu, alertsSubmenu keys (8 files) |
+| toga2-commerce `.../COMPASSCANADA/{ENGLISH,FRENCH}/<4 roles>/ORDERHISTORYFIELDS.json` | modified | + ordersForOthers*, pageSearchInput (8 files) |
+| toga2-commerce `src/components/NavIcons/NavIconItem.tsx` | modified | labels from fields w/ fallbacks |
+| toga2-commerce `src/components/Submenus/AlertSubmenu.tsx` + `types.ts` | modified | 4 new optional label props |
+| toga2-commerce `src/pages/Account/AccountPage.tsx` | modified | orders-others heading from fields |
+| toga2-commerce `src/pages/Account/view/MyOrdersView.tsx` | modified | search label/placeholder from fields |
+| toga2-commerce `src/pages/GetSupport/GetSupportPage.tsx` + `viewModel/useGetSupportViewModel.ts` | modified | language-switched illustration |
+| toga2-commerce `src/queries/queries.ts` | modified | + 2 persona keys in LANGUAGE_SENSITIVE_QUERY_KEYS |
+| dbchanges2 `Client/2026-07-22a - PersonaTranslations.sql` | created — NOT run | sidecar DDL |
+| dbchanges2 `Core/2026-07-22a - PersonaTranslationsRecord.sql` | created — NOT run | record 346, fields 2458-2462, translation link |
+| dbchanges2 `Client/2026-07-22b - PersonaTranslationsAcl.sql` | created — NOT run | Base-role ACL chain |
+| dbchanges2 `Client_CompassCanada/2026-07-22a - PersonaTranslationsFrench.sql` | created — NOT run | fr-CA seed (30 by uuid + 3 by name) |
+| _underscore `Model/Client/PersonaTranslation.php` | created — NOT deployed | declarative sidecar model |
+
+## Decisions made
+- **Persona names translate server-side** via the metadata sidecar pattern (PersonaTranslations, mirror of AssortmentTranslations) — zero api2 code changes; rejected: client-side name mapping in the frontend (violates "business logic stays in API", wouldn't cover other consumers).
+- **Hardcoded JSX strings get FIELDS keys with in-code English fallbacks** so COMPASS/QUAD need no JSON changes; rejected: adding keys to every tenant's files (churn) or leaving literals (blocks localization).
+- **Header "Admin" stays "Admin" in French** — natural French abbreviation; "Administration" was applied then reverted at developer request.
+- **Backend/DB rollout DEFERRED** — developer decision 2026-07-22; frontend ships independently (fields labels French now; persona *values* go French when migrations run).
+- Identical-in-both-languages names (Servomax, ESFM, MacBooks…) are seeded anyway so the API translation layer finds sidecar rows instead of queueing missing-translation warnings.
+
+## Blockers
+- No network route to any TOGa RDS cluster from this dev machine (VPN needed), and the claude.ai "TOGa Database Integration" connector is unauthorized — blocks the pre-run DB verification for the persona migrations.
+- Persona glossary possibly incomplete (screenshot cut off after "Managers/VIPs").
+
+## Exact next step
+> When backend work resumes: connect VPN (or authorize the TOGa DB connector), run the three pre-flight queries in `knowledge/2.0/apps/_underscore/features/persona-name-translation.md` (next-free ids 346/2458-2462; the 3 name-matched personas + duplicate-name check; `fr-CA` in Languages), then commit the 4 dbchanges2 files + `_underscore/Model/Client/PersonaTranslation.php` on a `feature/persona-translations` branch. For frontend-only shipping: branch + PR the toga2-commerce changes listed above.
+
+---
+_Saved by /session-save on 2026-07-22_

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.415",
+  "version": "1.0.416",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",