cesnimda
4.8 KiB
Ordered implementation specification — not execution authority
Proposed architecture decision
Keep existing useI18n call sites and React/MUI owners. Replace only its message evaluation/storage behind that contract after entry approval. Compare: current substitution is smallest but cannot meet plural/select requirements; i18next offers namespace loading and CLDR plural suffixes but changes interpolation/catalogue shape; FormatJS ICU supports complete sentence plural/select messages behind the current helper with less caller churn. Proposed preference: ICU message evaluation behind the existing API plus platform Intl formatting, subject to actual lockfile/runtime compatibility, bundle and extraction prototype after approval. Do not install either now. Do not implement two competing message engines. .NET renders server communications from its own typed templates with shared IDs/parameter contracts; do not assume identical ICU parser support in .NET/Python.
Sources checked 2026-11-02: https://www.i18next.com/translation-function/plurals and https://formatjs.github.io/docs/core-concepts/icu-syntax/. These establish syntax capabilities, not repository compatibility.
Independent preference contract
Residence countryId, searchCountryIds, typed location IDs, uiLocale, adLanguageFilters, document outputLocale, optional communicationLocale and timeZone are distinct. Country changes only suggestion ordering. Manual saved preference wins over URL/app choice, onboarding, browser negotiation and English fallback. Explicitly distinguish signed-out local storage from account hydration. Persist provenance and revision semantics without weakening tenant ownership. Existing en stays canonical until an approved compatibility migration; en-GB is a candidate variant, not a silent rewrite. nb/no/nb-NO legacy aliases preserve existing Bokmål behavior. nn-NO must never silently map to Bokmål. sr-Latn and sr-Cyrl retain script identity. Unsupported locale resolves to reliable English chrome; user content unchanged.
Stage sequence and evidence
| Stage | Bounded change after prerequisites | Required exit evidence |
|---|---|---|
| 00 | Finish contextual census, country legal cross-check, reviewer ownership | Complete source-bound inventory; independent schema validation; planning review |
| 01 | Registry, aliases, separate preferences, migration, formatting | Legacy roundtrip, invalid IDs, tenant/multi-device conflicts, MariaDB migration/reversal; new locales hidden |
| 02 | Extract full UI and accessible strings into existing owners | Required-key completeness, placeholder parser, dirty-form language switch, pseudo/long-label responsive tests |
| 03 | Stable backend codes; queued communication templates | Event-time locale snapshot proposed, retry determinism, isolated Mailpit/plain/HTML tests, legal approvals |
| 04 | Per-document headings/fonts, import boundaries | RD21/history invariance; script/PDF extraction and layout; native/physical review distinct |
| 05 | GJ-owned geography/provider/search integration | All-industry synthetic fixtures, explicit alias suggestions, source language and rights/retention evidence |
| 06 | Translation supply chain and glossary | Licensed source, translator context, independent proficient review, source-change invalidation |
| 07 | Launch Site localisation/SEO contract | Approved visual design; published-only alternates/sitemaps; truthful feature/provider claims |
| 08 | Cross-surface/native/device/security acceptance | Locale × surface × market × profession × device matrix; exact commit and disjoint counts |
Phase 10 completion/appropriate accepted handoff, PRODUCT-REVIEW-01, accepted I18N-00 and explicit stage authority precede I18N-01. Sequential accepted stage integration is mandatory. Separate development commits, no main merge/deploy.
GJ owns source fetch, rights, stable geography/occupation IDs and search mechanics; I18N owns display labels, ad-language semantics and translated-summary labels. ESCO concept identity cannot be replaced by translated free text. Original advertisement always remains distinguishable. Provider rights are checked before requests, not inferred from locale availability. Launch Site owns visual design/routing architecture; I18N supplies market+content-locale+publication schema and claims binding to deployed capability. Future fixtures may be designed now but no dependent runtime is invented.
Terminology queue: Career Profile (canonical facts), CV (document variant), cover letter, application (pursuit), job (opportunity), apprenticeship, shift, seasonal work, salary, qualification, nursing/teaching licence. Define each English concept before translation; profession label never establishes accreditation. Planned fixtures include teacher, cook, nurse, electrician, construction worker, driver, cleaner, retail, office administrator and developer.