Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .config/dotnet-tools.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
"isRoot": true,
"tools": {
"formaui-net.locali": {
"version": "1.0.0-preview.23",
"version": "1.0.0-preview.25",
"commands": [
"locali"
],
Expand Down
20 changes: 20 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,26 @@ release is cut, and reads *Unreleased* until then. It lists every change a consu
breaks what the release before it allowed says how to migrate, as [Versioning's rules](https://github.com/FormaUI/Versioning/blob/v1.0.0-preview.5/docs/releases.md#the-release-record)
set out. What Forma gained before its first release, month by month, is in [the feature history](FEATURE-HISTORY.md).

## `1.0.0-preview.10`

*November 17, 2026*

- The composer's selection bar is named by the selection row's label, *Selection Formatting*, which Hebrew and
Spanish localize. The row's label had no entry in either language, and the bar carried a label of its own,
*Selection formatting*. `ComposerSelectionBar` takes the label as its first argument, `Label`; to migrate, pass the
row's label ahead of the items.
- `ComposerGroups` names the toolbar groups the composer provides, `Media` the first, and the composer titles one in
its own words whichever plugin declares it, as it labels a row `ComposerRows` names. A plugin's other titles are read
from the locale its `LocaleSourceType` names alone. The composer read every title there first and fell back to its
own, so a plugin from another package joining the media group, as `ExplorerPlugin` does, threw under
`RequireMatchingLocalization` in a language other than English, and `Diagnostics` reported the title missing. The
image, video and explorer plugins put their commands in `ComposerGroups.Media`, whose identifier is
`composer.media`; to migrate, a plugin that named the group `media` names `ComposerGroups.Media`.
- An application a test runner hosts, as `WebApplicationFactory` does, reads the locale packs and files its build
recorded: where the entry assembly's build didn't mark it as the application, every loaded assembly whose build did
is read before it. A test hosting the application read only the test assembly's, so the application's components
rendered in English unless the test referenced the packs as well.

## `1.0.0-preview.9`

*November 17, 2026*
Expand Down
2 changes: 1 addition & 1 deletion Directory.Build.props
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
<!-- The one version every package ships at; a preview, as the framework it targets is. -->
<PropertyGroup>
<VersionPrefix>1.0.0</VersionPrefix>
<VersionSuffix>preview.9</VersionSuffix>
<VersionSuffix>preview.10</VersionSuffix>
</PropertyGroup>

<!-- Reports the .editorconfig IDE* code-style severities from the compiler, not just the IDE, and fails the build on any warning, the compiler's or MSBuild's. -->
Expand Down
8 changes: 4 additions & 4 deletions docs/composer-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ Key bindings come through `IComposerKeyBindingSource`, which every plugin is and

A **view** has the shape of an editor — its own component, rows, items and assets, maximizable like any surface — but shows one editor's document read-only rather than editing it. An editor offers a view by registering it as a child, and a feature registered under that view contributes to its rows exactly as one registered under an editor contributes to the editor's; the layout for a view takes the built-in row, the rows the view declared, and what is registered under the view or at the composer root, and nothing else — so neither an editor's formatting nor a command acting on the document, such as attaching a file, lands on its preview. The switcher lists the active editor's views as trailing tabs after the editors, and those tabs are the only way in: a view is its own surface, not a toolbar toggle. A plugin reports which of its own toggles and options are active through `ActiveStates`, which is how a view's paper size and zoom show in its bar without going through the selection.

`Title` is the **English source string**, not a resolved localized string, and so is every title and row label a plugin contributes; the composer localizes them when it draws them. A plugin never resolves a localizer of its own — one that did would capture whichever culture it was built under, and would have to carry the composer's words for every group it joins. What a plugin does name is **where its localization lives**, through `LocaleSourceType`, the way a component part names its composite's: the composer reads a title from that type's locale first and from its own after, so a plugin shipped from another package brings its own strings and still borrows the composer's for a group they share. A plugin naming none is read from the composer's alone. Localization happens before contributions are merged, since a merged group no longer says which plugin declared each item in it.
`Title` is the **English source string**, not a resolved localized string, and so is every title and row label a plugin contributes; the composer localizes them when it draws them. A plugin never resolves a localizer of its own — one that did would capture whichever culture it was built under, and would have to carry the composer's words for every group it joins. What a plugin does name is **where its localization lives**, through `LocaleSourceType`, the way a component part names its composite's: the composer reads a plugin's titles from that type's locale, so a plugin shipped from another package brings its own strings, and reads those of a plugin naming none from its own. A group the composer provides, named in `ComposerGroups`, takes the composer's title whichever plugin declares it, as a row named in `ComposerRows` takes the composer's label, so a plugin joining one never carries the composer's word for it. Every title is read from one locale, so a title missing from it is a miss the localization's checks report. Localization happens before contributions are merged, since a merged group no longer says which plugin declared each item in it.

### 3.1a Composing a composer

Expand Down Expand Up @@ -222,7 +222,7 @@ Everything around the canvas is a **region**, and every region takes contributio
| 2 | Editor specific | `IComposerEditorPlugin` | the built-in toolbar row |
| 3 | External | any other `IComposerPlugin` | the plugin toolbar row |

An item names its row through `ComposerToolbarItem.RowId`: the shared built-in row, one of the rows the composer always provides — formatting, paragraph, plugins and selection, named in `ComposerRows` — or a row its contributor declares through `Rows`. An editor therefore chooses between joining the shared row and standing on its own purely by the row it names, and a plugin does the same. Rows an editor declares render after the built-in row, the composer's own rows follow, then the rows external plugins declared; a row nothing fills is dropped, and an item naming a row nobody declared lands on the plugins row rather than vanishing. Rows holding only a few commands are folded together so no bar is spent on a handful; the plugins row shows on demand behind a toggle at the end of the first bar, overflowing its surplus into a menu; and the selection row is what the selection bar renders.
An item names its row through `ComposerToolbarItem.RowId`: the shared built-in row, one of the rows the composer always provides — formatting, paragraph, plugins and selection, named in `ComposerRows` — or a row its contributor declares through `Rows`. An editor therefore chooses between joining the shared row and standing on its own purely by the row it names, and a plugin does the same. Rows an editor declares render after the built-in row, the composer's own rows follow, then the rows external plugins declared; a row nothing fills is dropped, and an item naming a row nobody declared lands on the plugins row rather than vanishing. Rows holding only a few commands are folded together so no bar is spent on a handful; the plugins row shows on demand behind a toggle at the end of the first bar, overflowing its surplus into a menu; and the selection row is what the selection bar renders, named by the row's label.

| Region | Placement |
|---|---|
Expand Down Expand Up @@ -527,7 +527,7 @@ These are correctness requirements for every Forma component, and the composer i

**A plugin joining the composer to another component is an AddOn of its own**, `Forma.AddOns.Composer.Plugins.{Component}`, borrowing the composer plugins' namespace as an AddOn borrows what it extends. The stored-files plugin and its dialog body are `Forma.AddOns.Composer.Plugins.Explorer`, with their own strings beside them, so the composer never depends on the explorer, the explorer never depends on the composer, and a host wanting both adds the one package that joins them.

**Every component in the composer's package reads its strings through the component it names with `LocaleSourceType`**: `FormaComposer` for the engine, its bars, its dialogs and the editor canvases, `FormaRichTextEditor` for the rich text selection bar and views. Its strings sit in that component's section of the language packs, nested as the component's namespace is. A plugin's titles are the exception, read through the locale the plugin names and then the composer's (§3.1), and an AddOn carries its own.
**Every component in the composer's package reads its strings through the component it names with `LocaleSourceType`**: `FormaComposer` for the engine, its bars, its dialogs and the editor canvases, `FormaRichTextEditor` for the rich text selection bar and views. Its strings sit in that component's section of the language packs, nested as the component's namespace is. A plugin's titles are the exception, read through the locale the plugin names (§3.1), and an AddOn carries its own.

---

Expand Down Expand Up @@ -555,4 +555,4 @@ These are correctness requirements for every Forma component, and the composer i
| C18 | Where does registering, building and disposing plugins live? | In `Forma.Framework.Plugins`, generic over the plugin contract a feature declares, since none of it names a composer concept. The composer's builders keep only the editor, feature and view roles (§3.1a). |
| C19 | Whose defaults does an editor get? | Its own. The editor builder is typed by its editor, so each editor's package extends it with defaults of its own and one editor's defaults cannot be called on another. The composer's defaults are what belongs on every surface, which is maximizing and the shortcut reference; attaching is each editor's, since a view never edits the document (§4.3a). |
| C20 | How does a capability that joins the composer to another component ship? | As an AddOn of its own, `Forma.AddOns.Composer.Plugins.{Component}` (§9), so neither component's package depends on the other and a host wanting both adds the one package that joins them. |
| C21 | Where does a plugin from another package keep its labels' localization? | With itself. A plugin names the type whose locale files hold its labels through `LocaleSourceType`, and the composer reads a title from it before its own, so a shared group keeps the composer's word while the plugin's own commands carry theirs (§3.1). |
| C21 | Where does a plugin from another package keep its labels' localization? | With itself. A plugin names the type whose locale files hold its labels through `LocaleSourceType`, and the composer reads its titles from that type's locale alone. A group the composer provides, named in `ComposerGroups`, takes the composer's own title, as a standard row does, so a plugin joining one carries only its own commands' words, and a title read from one locale makes a missing one a miss the localization's checks report (§3.1). |
2 changes: 1 addition & 1 deletion docs/features-status.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
| Measure | Now |
| --- | --- |
| Components | 67 implemented and 7 in progress, as [the catalog](component-catalog.md) lists them, and 21 planned, as [the roadmap](component-roadmap.md) orders them |
| Packages | Every project under `src/` but the Showcase, released from `main` by `release.yml` to nuget.org and the organization's GitHub feed, the latest published release `1.0.0-preview.9` |
| Packages | Every project under `src/` but the Showcase, released from `main` by `release.yml` to nuget.org and the organization's GitHub feed, the latest published release `1.0.0-preview.10` |
| Render modes | Interactive Server, WebAssembly and Auto implemented: every call a component makes to a script and every call back checked in each, and on the Server in WebKit, the engine of Safari and of Apple's web views, every runtime on a page following its culture coordinator, a client reading its host's own strings, and a host setting either arrangement up as the README says; static rendering implemented, every check page rendered statically with no enabled control that needs interactivity; Blazor Hybrid implemented on WPF, Windows Forms and MAUI on Windows, every component checked in a web view and each host's application set up as the README says; an inventory holds every component to a check page in every render mode |

The gate runs every check [the verification design](verification-design.md#gates) sets out, each platform's where the machine can run it. It passes locally on Windows and in CI on Linux, on Windows and on an Android emulator.
Expand Down
25 changes: 15 additions & 10 deletions docs/localization-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -239,10 +239,13 @@ its own. As the server builds, it asks each project it references whether that p
application that embedded locale files, and records each one that did with
`LocaleReferenceAttribute`, naming its assembly; the server reads them before its own.

The runtime finds the application by its entry assembly or, where the runtime names none, as a
native host such as .NET for Android's or iOS's names none, among the loaded assemblies: the one its
build marked as the application, which only an application's build does. After the application's
own files it reads the folder beside the running application, which
The runtime finds the application by its entry assembly where the entry assembly's build marked it
as the application, which only an application's build does. Where the entry assembly is unmarked,
as a test runner's is while it hosts the application under test, or absent, as under a native host
such as .NET for Android's or iOS's, it finds the application among the loaded assemblies as each
one its build marked, and reads what an unmarked entry assembly recorded after them.

After the application's own files it reads the folder beside the running application, which
`LocalizationOptions.LocalesPath` names, `.locales` beside the application by default. No build
fills that folder; a host places files in it to change a string without building again, and it has
the last word. The folder is read by the same rule, its names paths as an assembly's are. A
Expand Down Expand Up @@ -330,14 +333,15 @@ install: a pack carries as many assemblies' strings as it has files for.
### An application names its packs, not a library

The attribute that records a pack is written into the project holding the reference, and the packs
that are read are the ones the application names, its entry assembly or, where the runtime names
none, the assembly its build marked. Which languages ship is therefore the application's decision
and cannot be made for it by a library it installs, so a library never references a pack.
that are read are the ones the application names, found as
[the application's files](#the-applications-files) describe. Which languages ship is therefore the
application's decision and cannot be made for it by a library it installs, so a library never
references a pack.

A class library that references a pack is stamped itself rather than stamping the application, so
its pack is not found from the application. A host arranged that way names its packs through
`LocalizationOptions`, which is also how a test reaches a pack without depending on what its runner
made the entry assembly.
`LocalizationOptions`, which is also how a test that renders components without hosting an
application reaches a pack.

### Finding a pack

Expand Down Expand Up @@ -498,7 +502,7 @@ host wanting Forma's strings registers the adapter in its place or before it.
| L16 | Does the runtime read anything out of a pack's name? | No. A pack is loaded by name and read by its resources, neither of which is parsed, so any assembly can be a pack whatever it is called, for whichever assemblies its files name, published by anyone. `Forma.Blazor.Locales.{Language}` is this repository's convention for its own. |
| L17 | What does a project write to embed its locale files? | Nothing. The build finds them by the `$localization` entry every locale file carries and embeds each once, under the name its path forms, so configuration stays in `.locale.json` and `LocalizationOptions` and no fact about a locale file lives in a project file; a file a project embeds through an item of its own keeps that item's name. |
| L18 | Where does an application keep its strings for other assemblies, and how do they reach a runtime with no file system? | Among its locale files, in names starting with the assembly's name. The build embeds them as it embeds every locale file, so a WebAssembly client, a MAUI application and a server read them from the application's assembly. |
| L19 | How does a Web App's server read its client's files? | Through `LocaleReferenceAttribute`, which the server's build writes for each referenced application that embedded locale files, naming its assembly; the server reads them before its own. The runtime finds the application by its entry assembly or, with none, by the mark its build writes into the application alone. |
| L19 | How does a Web App's server read its client's files? | Through `LocaleReferenceAttribute`, which the server's build writes for each referenced application that embedded locale files, naming its assembly; the server reads them before its own. The runtime finds the application by the mark its build writes into the application alone (L36). |
| L20 | What decides which text a reader sees? | The culture first, then the source, and nothing about a file's place or name. A more specific culture wins over a later source, and a later source over an earlier one. |
| L21 | What happens when one source gives an entry two texts? | It is a conflict: the linter reports it as an error, and the runtime keeps the text from the file whose name sorts last, ordinally, so the outcome is fixed while the error stands, and logs the conflict once as a warning naming both files, since a host that runs no linter would otherwise show one of two texts without knowing. The same text twice isn't a conflict. |
| L22 | Can a culture be a folder? | Yes. A folder named for a culture holds files for it, a file per namespace or per type named with dots, and the root's file named for the culture again, `.locales/es/es.json`, so a project keeps each language in one folder instead of a `.locales` folder per namespace. |
Expand All @@ -515,3 +519,4 @@ host wanting Forma's strings registers the adapter in its place or before it.
| L33 | Does a check resolve a key its own way? | No. It asks the lookup's own resolution of another culture, without changing the reader's culture or rendering text, so a check and a lookup never disagree about what is found. |
| L34 | How broad is a reported miss? | As broad as the resolver establishes: the assembly where no source holds an entry for any of its types in the culture or a culture it falls back to, the type where the assembly holds some and the type doesn't, and the key otherwise. The broader report stands for the narrower ones beneath it. |
| L35 | What does `RequireMatchingLocalization` guarantee? | That a lookup finds its text: an entry in the UI culture or a culture it falls back to, or, in the source language and the invariant culture, the key itself. |
| L36 | How does the runtime find the application? | By the mark its build writes into the application alone. The entry assembly is read alone where its build marked it; where it is unmarked, as a test runner's is, or absent, as under a native host, every loaded assembly its build marked is read, then what an unmarked entry assembly recorded, so a test hosting the application reads the packs and files the application recorded without referencing them itself. |
Loading
Loading