diff --git a/.planning/phases/04-cli-scaffolding-i18n-and-mail/04-02-SUMMARY.md b/.planning/phases/04-cli-scaffolding-i18n-and-mail/04-02-SUMMARY.md new file mode 100644 index 0000000..f4c0a5d --- /dev/null +++ b/.planning/phases/04-cli-scaffolding-i18n-and-mail/04-02-SUMMARY.md @@ -0,0 +1,162 @@ +--- +phase: 04-cli-scaffolding-i18n-and-mail +plan: 02 +subsystem: i18n +tags: [phrasebook, i18n, cldr, go-i18n, yaml, wintercms] + +requires: + - phase: 04-cli-scaffolding-i18n-and-mail + provides: pact.HasLang, party.Activate Register-then-Boot order + - phase: 01-framework-kernel-foundation + provides: backpack.Publish/Lookup, towel.Locale, compass app.locale +provides: + - phrasebook catalog loader for lang//.yaml + - app-scoped Translator with Get/Choice and explicit-locale variants + - HasLang activation before plugin Boot + - hello plugin en/pl embedded catalog +affects: [04-03-mail, 04-04-tests, plugin-porting, I18N-02] + +tech-stack: + added: [github.com/nicksnyder/go-i18n/v2@v2.6.1] + patterns: + - go-i18n selects only a CLDR category label via IdentityParser + - phrasebook owns YAML source text and :name/:Name/:NAME substitution + - HasLang catalogs load after Register and publish Translator before Boot + +key-files: + created: + - phrasebook/loader.go + - phrasebook/translator.go + - phrasebook/translator_test.go + - examples/hello/plugins/base/lang/en/lang.yaml + - examples/hello/plugins/base/lang/pl/lang.yaml + modified: + - party/registry.go + - party/registry_test.go + - examples/hello/plugins/base/plugin.go + - examples/hello/hello_test.go + - go.mod + - go.sum + +key-decisions: + - "go-i18n is used only to choose a CLDR category label; YAML message text never enters its template engine" + - "A per-locale i18n.Bundle is cached so matcher/plural rules follow the requested tag, not the English default bundle" + - "Fallback order is requested, parent, app.fallback_locale, then the raw key; framework defaults remain en/en" + +patterns-established: + - "LangFS paths must be lang//.yaml; malformed paths, non-string leaves, duplicate keys and duplicate namespace owners fail boot with plugin/file/key context" + - "YAML maps whose keys are all CLDR categories are plural maps requiring other; otherwise they flatten as nested namespaces" + - "Missing keys log once per translator outside production and never include parameters" + +requirements-completed: [I18N-01] + +duration: 10min +completed: 2026-09-18 +--- + +# Phase 4 Plan 02: i18n phrasebook Summary + +**Plugin-owned English and Polish YAML catalogs resolve `vendor.plugin::group.key` with CLDR and Laravel plurals, `:name` case variants, and pl-PL→pl→fallback→raw lookup** + +## Performance + +- **Duration:** 10 min +- **Started:** 2026-09-18T11:43:00Z +- **Completed:** 2026-09-18T11:52:55Z +- **Tasks:** 3 +- **Files modified:** 11 + +## Accomplishments + +- `phrasebook` loads embedded `lang//.yaml`, flattens nested maps to `vendor.plugin::group.dot.path`, and rejects malformed catalogs with plugin/file/key context +- `party.Activate` publishes one `*phrasebook.Translator` after Register and before Boot, using `app.locale` / `app.fallback_locale` with framework defaults `en`/`en` +- Polish and English plural maps and Laravel pipe strings select the specified forms; `:name`, `:Name`, and `:NAME` substitute after selection without sending YAML through go-i18n templates +- Requested locale walks parent then configured fallback then returns the raw key; missing keys log once outside production + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Load a namespaced translation from an embedded plugin** - `f824e55` (feat) +2. **Task 2: Select CLDR and Laravel plural forms with PHP parameters** - `6d8786a` (feat) +3. **Task 3: Apply configured locale fallback and missing-key behavior** - `8a4e0ef` (feat) + +**Plan metadata:** (this commit) + +## Files Created/Modified + +- `phrasebook/loader.go` - WalkDir catalog load, YAML flatten, plural-map detection, pipe parse +- `phrasebook/translator.go` - Get/Choice, CLDR category selection, fallback chain, missing-key log +- `phrasebook/translator_test.go` - translation, plural, and locale-fallback smokes +- `party/registry.go` - HasLang scan and translator publish before Boot +- `party/registry_test.go` - translator available at Boot; malformed lang fails with plugin id +- `examples/hello/plugins/base/plugin.go` - embeds LangFS and implements HasLang +- `examples/hello/plugins/base/lang/en/lang.yaml` - English nested keys, plurals, pipes, parameters +- `examples/hello/plugins/base/lang/pl/lang.yaml` - Polish nested keys, CLDR map and pipe forms +- `examples/hello/hello_test.go` - Activate + en/pl/pl-PL/fallback/raw-key smoke +- `go.mod` / `go.sum` - pin go-i18n/v2 v2.6.1 + +## Decisions Made + +- go-i18n receives only category-name message variants and `IdentityParser`, so PHP `:name` placeholders and `{{.Count}}` YAML stay literal +- Each locale gets its own `i18n.Bundle` default language so Polish `few`/`many` are real categories, not English `other` +- Fallback stops at configured `app.fallback_locale` then the raw key; there is no extra core-locale step beyond that default + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 3 - Blocking] phrasebook tests cannot import party** +- **Found during:** Task 1 (TestTranslationSmoke Activate) +- **Issue:** `phrasebook_test` → `party` → `phrasebook` is an import cycle in tests +- **Fix:** Call `phrasebook.Activate` from phrasebook tests; keep `party.Activate` HasLang wiring tests in `party/registry_test.go` +- **Files modified:** `phrasebook/translator_test.go`, `party/registry_test.go` +- **Verification:** `TestTranslationSmoke` and `TestActivatePublishesTranslatorBeforeBoot` pass +- **Committed in:** `f824e55` (Task 1 commit) + +**2. [Rule 1 - Bug] go-i18n rejects float PluralCount** +- **Found during:** Task 2 (fractional plural samples) +- **Issue:** `plural.NewOperands` requires integers or decimal strings, not `float64` +- **Fix:** Coerce float counts to decimal strings before category selection +- **Files modified:** `phrasebook/translator.go` +- **Verification:** `TestPluralSmoke` covers `1.5` for pl/en +- **Committed in:** `6d8786a` (Task 2 commit) + +**3. [Rule 1 - Bug] English default bundle hid Polish CLDR forms** +- **Found during:** Task 2 (Polish `few` rejected as invalid for `pl`) +- **Issue:** A single `NewBundle(language.English)` made Localizer match English plural rules +- **Fix:** Cache one bundle per locale tag with that tag as default language +- **Files modified:** `phrasebook/translator.go` +- **Verification:** Polish counts 1/2/5/22 select one/few/many/few +- **Committed in:** `6d8786a` (Task 2 commit) + +--- + +**Total deviations:** 3 auto-fixed (1 blocking, 2 bugs) +**Impact on plan:** No behavior divergence from D-01–D-05. Fixes were required for catalog tests to compile and for Polish CLDR selection to be real. + +## Issues Encountered + +None + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness + +Ready for 04-03 (postcard / mail). Translator is app-scoped and available at plugin Boot. Unit-test coverage remains the last plan (04-04). Per-request preferred-locale lookup stays Phase 7. + +## Verification + +- `go test ./phrasebook -run 'TestTranslationSmoke|TestPluralSmoke|TestLocaleFallbackSmoke' -short -count=1` — PASS +- `go -C examples/hello test ./...` — PASS +- `go vet ./... && go test ./...` — PASS +- No second context key; phrasebook reads `towel.Locale` only +- No package-level current-locale variable + +## Self-Check: PASSED + +--- +*Phase: 04-cli-scaffolding-i18n-and-mail* +*Completed: 2026-09-18*