docs(14.2.1): lock Go tables to golem15_translate_*

Execute-phase Task 2 chose golem15-prefix over the researched winter_translate_* names so the plugin ships vendor tables; PHP winter names stay a later import mapping.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Jakub Zych
2026-10-06 11:36:28 +02:00
parent 28bd45fa04
commit bd0a27f59f
9 changed files with 73 additions and 72 deletions

View File

@@ -12,10 +12,10 @@ files_modified:
- ../sm-translate-plugin/models/registry.go
- ../sm-translate-plugin/models/locale.go
- ../sm-translate-plugin/updates/registry.go
- ../sm-translate-plugin/updates/202610060001_create_winter_translate_locales.go
- ../sm-translate-plugin/updates/202610060002_create_winter_translate_attributes.go
- ../sm-translate-plugin/updates/202610060003_create_winter_translate_indexes.go
- ../sm-translate-plugin/updates/202610060004_create_winter_translate_messages.go
- ../sm-translate-plugin/updates/202610060001_create_golem15_translate_locales.go
- ../sm-translate-plugin/updates/202610060002_create_golem15_translate_attributes.go
- ../sm-translate-plugin/updates/202610060003_create_golem15_translate_indexes.go
- ../sm-translate-plugin/updates/202610060004_create_golem15_translate_messages.go
- ../sm-translate-plugin/updates/202610060005_seed_en_pl_locales.go
- ../sm-translate-plugin/classes/translator.go
- modules/surf/locale_resolver.go
@@ -26,7 +26,7 @@ requirements: [D-01, D-02, D-03, D-04, D-07, D-08, D-10, D-12, D-15, D-16]
must_haves:
truths:
- "D-01/D-02/D-03/D-04: implementation is derived only from the read-only PHP tree at SHA 725d547ec839f02b5fdc0f0a6faaed601a414d50; no PHP file changes."
- "D-10: gormigrate creates final `winter_translate_locales`, `winter_translate_attributes`, `winter_translate_indexes`, and empty `winter_translate_messages`; it creates no rainlab-era or `golem15_translate_*` tables."
- "D-10: gormigrate creates final `golem15_translate_locales`, `golem15_translate_attributes`, `golem15_translate_indexes`, and empty `golem15_translate_messages`; it creates no rainlab-era or `winter_translate_*` tables."
- "D-08: an idempotent seed creates enabled `en` as default at sort_order 1 and enabled non-default `pl` as Polski at sort_order 2, and never seeds `de`."
- "D-07/D-12: a backpack-published resolver selects URL prefix, valid user preferred_locale, remembered `golem15.translate.locale`, cookie-gated Accept-Language, then default, and surf stores only a validated code on context."
- "KERN-07: no package-level mutable current locale exists; `Translator.Locale(ctx)` and `towel.WithLocale` carry request state."
@@ -35,12 +35,12 @@ must_haves:
- path: "../sm-translate-plugin/plugin.go"
provides: "compiled Plugin registration, migrations/models/config, Resolver publication"
contains: "golem15.translate"
- path: "../sm-translate-plugin/updates/202610060001_create_winter_translate_locales.go"
- path: "../sm-translate-plugin/updates/202610060001_create_golem15_translate_locales.go"
provides: "squashed Locale schema"
contains: "winter_translate_locales"
- path: "../sm-translate-plugin/updates/202610060004_create_winter_translate_messages.go"
contains: "golem15_translate_locales"
- path: "../sm-translate-plugin/updates/202610060004_create_golem15_translate_messages.go"
provides: "empty compatibility Messages table without admin"
contains: "winter_translate_messages"
contains: "golem15_translate_messages"
- path: "../sm-translate-plugin/classes/translator.go"
provides: "context-only Translator and request Resolver"
contains: "func ("
@@ -93,7 +93,7 @@ Phase 14.2.1 has no mapped REQUIREMENTS.md IDs, so requirement probing is visibl
## Artifacts this phase produces
- Module `git.golem15.com/golem15/sm-translate-plugin`, package `translate`, `Plugin.ID() == "golem15.translate"`.
- `models.Locale`, model and migration registries, five gormigrate entries, and exact `winter_translate_*` tables.
- `models.Locale`, model and migration registries, five gormigrate entries, and exact `golem15_translate_*` tables.
- `classes.Translator`, `Translator.Locale(context.Context)`, and a request resolver implementing surf's `LocaleResolver`.
- Surf optional resolver seam with unchanged fallback behavior when the translate plugin is absent.
- Application-neutral plugin and surf README updates for exported contracts.
@@ -122,22 +122,22 @@ Phase 14.2.1 has no mapped REQUIREMENTS.md IDs, so requirement probing is visibl
</task>
<task type="checkpoint:decision" gate="blocking-human">
<name>Task 2: Confirm the one-way Winter table contract</name>
<name>Task 2: Confirm the one-way table contract</name>
<files>../sm-translate-plugin/updates/</files>
<read_first>.planning/phases/14.2.1-translate-plugin/14.2.1-CONTEXT.md (D-10), .planning/phases/14.2.1-translate-plugin/14.2.1-RESEARCH.md (Tables, columns, indexes), /media/nvme/dev/golem15/fonoteka/plugins/golem15/translate/updates/version.yaml, /media/nvme/dev/golem15/fonoteka/plugins/golem15/translate/models/Locale.php</read_first>
<action>Record the selected schema contract before migrations are implemented. Research resolved D-10's provisional prefix against the frozen source: the only compatible selection is the final `winter_translate_*` table family. This gate records the one-way import/storage choice; it does not reopen the PHP pin or permit a JSON-column alternative.</action>
<action>Record the selected schema contract before migrations are implemented. Execute-phase Task 2 locked `golem15-prefix`: Go tables are `golem15_translate_*` with the PHP pin's columns and indexes. PHP still uses `winter_translate_*`; do not copy those names into Go DDL. This gate does not reopen the PHP pin or permit a JSON-column alternative.</action>
<decision>Which persistent table contract should this shared plugin publish?</decision>
<context>Once released and imported by Journal, renaming these tables requires coordinated data migrations in every host. The frozen PHP pin explicitly reads `winter_translate_*` after its RainLab rename history.</context>
<context>Once released and imported by Journal, renaming these tables requires coordinated data migrations in every host. The frozen PHP pin reads `winter_translate_*`; the Go plugin deliberately uses `golem15_translate_*`.</context>
<options>
<option id="winter-final">
<name>Squash directly to the four final winter_translate_* tables</name>
<pros>Matches SHA 725d547, Winter imports, and Journal cutover.</pros>
<cons>The names become a shared persistent contract.</cons>
<cons>Not the locked Go contract.</cons>
</option>
<option id="golem15-prefix">
<name>Use provisional golem15_translate_* names</name>
<pros>Vendor-style naming.</pros>
<cons>Contradicts the frozen source and breaks direct imports.</cons>
<name>Use golem15_translate_* names</name>
<pros>Vendor-style naming; locked D-10 execute decision.</pros>
<cons>Winter import needs a later mapping; PHP source still says winter_translate_*.</cons>
</option>
<option id="host-json">
<name>Store translations on host-model JSON columns</name>
@@ -151,22 +151,22 @@ Phase 14.2.1 has no mapped REQUIREMENTS.md IDs, so requirement probing is visibl
</verify>
<acceptance_criteria>
- The response is recorded in the summary.
- Task 3 starts only for `winter-final`; either alternative stops execution as a locked-decision conflict.
- Task 3 starts only for `golem15-prefix`; `host-json` stops as a locked-decision conflict. `winter-final` is the discarded research recommendation.
</acceptance_criteria>
<resume-signal>Select `winter-final` to implement the locked/researched contract, or select an alternative to stop.</resume-signal>
<resume-signal>Select `golem15-prefix` (locked). `winter-final` is no longer the implementation path.</resume-signal>
</task>
<task type="tracer">
<name>Task 3: Resolve one URL-prefixed request through the plugin, enabled Locale row, surf, and context</name>
<reversibility rating="one-way">The four table names and columns become the import target; changing them after release requires data migrations in every host.</reversibility>
<precondition>Tasks 1 and 2 completed, with schema option `winter-final`.</precondition>
<files>../sm-translate-plugin/go.mod, ../sm-translate-plugin/plugin.go, ../sm-translate-plugin/README.md, ../sm-translate-plugin/config/config.yaml, ../sm-translate-plugin/models/registry.go, ../sm-translate-plugin/models/locale.go, ../sm-translate-plugin/updates/registry.go, ../sm-translate-plugin/updates/202610060001_create_winter_translate_locales.go, ../sm-translate-plugin/updates/202610060002_create_winter_translate_attributes.go, ../sm-translate-plugin/updates/202610060003_create_winter_translate_indexes.go, ../sm-translate-plugin/updates/202610060004_create_winter_translate_messages.go, ../sm-translate-plugin/updates/202610060005_seed_en_pl_locales.go, ../sm-translate-plugin/classes/translator.go, modules/surf/locale_resolver.go, modules/surf/router.go, modules/surf/README.md</files>
<precondition>Tasks 1 and 2 completed, with schema option `golem15-prefix`.</precondition>
<files>../sm-translate-plugin/go.mod, ../sm-translate-plugin/plugin.go, ../sm-translate-plugin/README.md, ../sm-translate-plugin/config/config.yaml, ../sm-translate-plugin/models/registry.go, ../sm-translate-plugin/models/locale.go, ../sm-translate-plugin/updates/registry.go, ../sm-translate-plugin/updates/202610060001_create_golem15_translate_locales.go, ../sm-translate-plugin/updates/202610060002_create_golem15_translate_attributes.go, ../sm-translate-plugin/updates/202610060003_create_golem15_translate_indexes.go, ../sm-translate-plugin/updates/202610060004_create_golem15_translate_messages.go, ../sm-translate-plugin/updates/202610060005_seed_en_pl_locales.go, ../sm-translate-plugin/classes/translator.go, modules/surf/locale_resolver.go, modules/surf/router.go, modules/surf/README.md</files>
<read_first>../fonoteka.go/plugins/golem15/user/go.mod, ../fonoteka.go/plugins/golem15/user/plugin.go, ../fonoteka.go/plugins/golem15/user/models/registry.go, ../fonoteka.go/plugins/golem15/user/updates/registry.go, ../fonoteka.go/plugins/golem15/user/updates/00_base.go, modules/backpack/app.go, modules/surf/router.go, modules/surf/locale_from_principal.go, modules/towel/context.go, /media/nvme/dev/golem15/fonoteka/plugins/golem15/translate/classes/Translator.php, /media/nvme/dev/golem15/fonoteka/plugins/golem15/translate/classes/LocaleMiddleware.php, /media/nvme/dev/golem15/fonoteka/plugins/golem15/translate/classes/ApiLocaleMiddleware.php, /media/nvme/dev/golem15/fonoteka/plugins/golem15/translate/config/config.php, .planning/phases/14.2.1-translate-plugin/14.2.1-PATTERNS.md</read_first>
<action>Implement the production tracer and the complete Plan 01 scope.
Create the Go 1.27 module using only existing GORM/gormigrate/framework dependencies. Register the compiled plugin in `init`, expose config/models/migrations, and publish a framework-owned `surf.LocaleResolver` in Boot. Keep `Requires()` empty so user-preference lookup is optional.
Implement exact squashed DDL for `winter_translate_locales`, `winter_translate_attributes`, `winter_translate_indexes`, and `winter_translate_messages`, including all final columns and PHP-indexed columns from RESEARCH. Messages is DDL only and remains empty. Use explicit gormigrate up/down; never AutoMigrate and never create rainlab or provisional-prefixed tables. Seed only en/pl idempotently with D-08 values.
Implement exact squashed DDL for `golem15_translate_locales`, `golem15_translate_attributes`, `golem15_translate_indexes`, and `golem15_translate_messages`, including all final columns and PHP-indexed columns from RESEARCH. Messages is DDL only and remains empty. Use explicit gormigrate up/down; never AutoMigrate and never create rainlab or `winter_translate_*` tables. Seed only en/pl idempotently with D-08 values.
Implement `Locale` with no timestamps, table name, code/name rules, and Fillable limited to code/name/is_enabled. Implement Translator/Resolver with the exact D-07 order: enabled URL first segment; valid principal preferred_locale; remembered `golem15.translate.locale`; Accept-Language only when browser detection is enabled and `locale_manually_set` is absent; enabled default. The manual cookie is a flag with value 1, never a locale. Validate every candidate against enabled rows. URL-prefix handling strips only a valid enabled prefix before routing and sets the manual flag using configured expiry. Provide the API resolver variant preferred → Accept-Language → default without persistence. All current-locale access takes context.
@@ -176,7 +176,7 @@ Add the surf interface and optional lookup without importing the plugin. When no
<fails_when>Non-zero exit, any package reports build failed, or either test command reports FAIL.</fails_when>
</verify>
<acceptance_criteria>
- All four migration files contain their exact `winter_translate_*` table name; no source file contains `golem15_translate_` or `rainlab_translate_`.
- All four migration files contain their exact `golem15_translate_*` table name; no source file contains `winter_translate_` or `rainlab_translate_`.
- Seed source contains en and pl with en default/enabled and pl enabled/non-default, and contains no Deutsch seed.
- Plugin module/ID/package match D-15 and plugin Boot publishes the framework resolver interface.
- Resolver order is URL → principal → remembered locale → cookie-gated Accept-Language → default.
@@ -217,7 +217,7 @@ Run the Task 3 command. Confirm `git diff -- /media/nvme/dev/golem15/fonoteka/pl
<success_criteria>
- The plugin and surf packages compile and pass short tests.
- Exact final tables and en/pl seed are implemented through gormigrate.
- Exact final `golem15_translate_*` tables and en/pl seed are implemented through gormigrate.
- Full resolver order is implemented without process-wide locale state.
- No deferred Messages UI, CMS components, AI/theme commands, import/export, or PHP edits are introduced.
</success_criteria>