docs: add a Role in the framework section to every module README

Each module README now says where the module sits in the dependency
graph, why it is its own module, and lists use cases for application
developers.
This commit is contained in:
2026-10-11 00:58:17 +02:00
parent 87953f68bf
commit 602e0412f3
24 changed files with 240 additions and 0 deletions

View File

@@ -10,6 +10,16 @@ Namespaced translation catalogs loaded from plugin YAML, with locale fallback, p
phrasebook owns every translatable string in a SummerCMS application. At boot, `phrasebook.Activate` loads the framework's own strings plus the `lang/` tree of every plugin that implements `pact.HasLang`, applies overrides from plugins that implement `pact.HasLangOverrides`, and publishes a single `phrasebook.Translator` on the `backpack.App`. Keys use the WinterCMS form `namespace::group.dot.path`, and message syntax follows Laravel (`:name` placeholders, `|` plural pipes), so it is the counterpart of WinterCMS's `Lang::get` / `trans_choice` and plugin `lang/` directories.
## Role in the framework
The translation layer, on `backpack`, `pact` and `towel`. `lagoon`, `party` and `cabana` use it for model, plugin and admin messages. It is separate so translation works the same in the API, mail and admin, and reads the request locale from `towel` rather than a global.
Use cases:
- Ship a plugin's messages in YAML for each language next to the plugin.
- Pluralize correctly for languages with several plural forms.
- Fall back to a default locale for keys that are missing in one language.
## Features
- YAML catalogs laid out as `lang/<locale>/<group>.yaml`; nested maps flatten into keys such as `acme.blog::posts.title` (`phrasebook.Catalog.Load`). Duplicate keys, duplicate namespaces, malformed paths and non-string leaves fail at load time.