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
6 changes: 4 additions & 2 deletions .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,14 @@ body:
label: Package
description: >
Which package is affected? ResXLocalization.Core is the shared engine both UI packages depend on;
pick it when the problem shows in a lookup made from code rather than from markup. "Not sure" is a
real answer and is fine.
pick it when the problem shows in a lookup made from code rather than from markup. Pick
ResXLocalization.MessageFormat when the problem shows only after Localizer.Current.UseMessageFormat().
"Not sure" is a real answer and is fine.
options:
- ResXLocalization.Avalonia
- ResXLocalization.WPF
- ResXLocalization.Core
- ResXLocalization.MessageFormat
- More than one, or not sure
validations:
required: true
Expand Down
58 changes: 42 additions & 16 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,34 +9,40 @@ together.
## What this is

ResXLocalization is a .NET library that gives XAML applications type-safe `.resx` localization with live
language switching. It ships as two NuGet packages — `ResXLocalization.Avalonia` and `ResXLocalization.WPF` —
over one shared, UI-agnostic engine. Consumers keep the `.resx` files and editors they already have.
language switching. It ships as two UI packages — `ResXLocalization.Avalonia` and `ResXLocalization.WPF` —
over one shared, UI-agnostic engine, `ResXLocalization.Core`, plus the opt-in package
`ResXLocalization.MessageFormat`, which formats every localized text as ICU MessageFormat. Consumers keep
the `.resx` files and editors they already have.

Two things separate it from plain `.resx`:

- **Compile-checked keys.** A source generator turns every eligible `.resx` into a `<FileName>Keys` class of
`ResourceKey` fields, each carrying both its key name and the `ResourceManager` it belongs to. A renamed or
deleted resource becomes a build error instead of a runtime surprise.
- **Compile-checked keys.** A source generator turns every neutral `.resx`, with or without a `.Designer.cs`,
into a `<FileName>Keys` class with its own `ResourceManager` property and one `ResourceKey` field per string
entry, each carrying both its key name and that `ResourceManager`. A renamed or deleted resource becomes a
build error instead of a runtime surprise.
- **Live culture switching.** Assigning `Localizer.Current.CurrentCulture` re-resolves every `{l:Localize}`
binding in place — no window reload, no view rebuild, no restart.

Around those: three lookup modes (typed, scoped, and search-all across registered resource managers) over
.NET's own culture fallback chain, enum localization by naming convention, format arguments in code and in
XAML, a `!key!` failure text plus a `TranslationNotFound` event for missing translations, and Native AOT and
trimming support on the Avalonia side (WPF supports neither).
.NET's own culture fallback chain, enum localization by naming convention, format arguments in code
(`MessageArguments`) and in XAML (`<l:Argument>` children of `{l:Localize}` and `{l:LocalizeEnum}`), one
replaceable message formatter for every lookup, a `!key!` failure text plus a `LookupFailed` event for
missing translations and formatting failures, and Native AOT and trimming support on the Avalonia side (WPF
supports neither).

[`README.md`](README.md) is the user-facing version of the same story, with the quick start and the examples.

## Project map

| Path | What it is |
| --- | --- |
| `src/ResXLocalization.Core` | The UI-agnostic engine: `ILocalizer`, `Localizer`, `ResourceKey`, the events. Both UI packages depend on it, and one copy satisfies both |
| `src/ResXLocalization.SourceGenerators` | The incremental generator that emits the typed `…Keys` classes. `netstandard2.0`. Ships **inside** the UI packages as an analyzer; it is not a package of its own |
| `src/ResXLocalization.Core` | The UI-agnostic engine: `ILocalizer`, `Localizer`, `ResourceKey`, `MessageArguments`, the message formatter, the events. Both UI packages depend on it, and one copy satisfies both |
| `src/ResXLocalization.MessageFormat` | The opt-in ICU MessageFormat formatter, installed with `Localizer.Current.UseMessageFormat()`. Depends on Core and the `MessageFormat` library, not on a UI package |
| `src/ResXLocalization.SourceGenerators` | The incremental generator that emits the typed `…Keys` classes. It reads each `.resx` and the MSBuild resource name the build wiring passes for it, and needs no `.Designer.cs`. `netstandard2.0`. Ships **inside** the UI packages as an analyzer; it is not a package of its own |
| `src/ResXLocalization.Avalonia` | The Avalonia markup extensions and converter, plus the packaged generator and resx wiring |
| `src/ResXLocalization.WPF` | The same for WPF. Windows-only, no Native AOT |
| `samples/` | Two runnable showcases, one per UI framework. Excluded from coverage |
| `tests/` | Four suites: Core (both frameworks), the generator, and one sample-test suite per UI framework |
| `tests/` | Five suites: Core and `tests/ResXLocalization.MessageFormat.Tests` (both on both frameworks), the generator, and one sample-test suite per UI framework |
| `tests/package-consumption/` | Package-only consumers. The repository's `Directory.Build.*` deliberately does **not** apply there |
| `build/` | The shared resx and packaging targets, and the DocFX configuration |
| `scripts/` | Every check and workflow, as PowerShell 7 |
Expand Down Expand Up @@ -103,8 +109,8 @@ change rendering rather than layout, are in
`<Name>_<random>_wpftmp` name, and `_TargetAssemblyProjectName` carries the real one. The root
`Directory.Build.props` resolves `_ConventionProjectName` from it, and every condition that has to hold in
that pass tests that property rather than `MSBuildProjectName`.
- **Native AOT covers Core and Avalonia only.** WPF has no AOT support, and `src/Directory.Build.props`
excludes it from `IsAotCompatible` deliberately.
- **Native AOT covers Core, Avalonia and MessageFormat only.** WPF has no AOT support, and
`src/Directory.Build.props` excludes it from `IsAotCompatible` deliberately.
- **The package consumers are outside everything.** `tests/package-consumption/` carries empty
`Directory.Build.props` and `Directory.Build.targets` files that stop MSBuild's upward search, so those
projects receive the library only from the packed packages. Do not add a project reference, a repository
Expand All @@ -122,15 +128,15 @@ The .NET 8 SDK step needs an 8.0 SDK installed next to the pinned one. It exists
more than their compiler - for example in WPF's temporary markup-compile pass, see the comment "WPF's temporary markup-compile pass" in `build/ResXLocalization.Resx.targets`.

Nothing is trimmed on the just-in-time compiler, so **no test suite in this repository can see trimming
damage**. The AOT gate publishes a package-only consumer natively and runs it; that is the only check that
can. See [`docs/guides/native-aot.md`](docs/guides/native-aot.md).
damage**. The AOT gate publishes the package-only consumers `AvaloniaConsumer` and `MessageFormatConsumer`
natively and runs them; that is the only check that can. See [`docs/guides/native-aot.md`](docs/guides/native-aot.md).

Invoke a reviewer only when its scope applies. Both are read-only by construction — see
[`.agents/README.md`](.agents/README.md).

## Public API

The three runtime projects declare their public surface in `PublicAPI.Shipped.txt` and
The four runtime projects declare their public surface in `PublicAPI.Shipped.txt` and
`PublicAPI.Unshipped.txt`. An undeclared public member is `RS0016`; a declared one that is gone is `RS0017`.
Both are build errors.

Expand All @@ -145,6 +151,26 @@ equivalent is analyzer release tracking in `AnalyzerReleases.*.md`.
`Directory.Build.props`, the release date, promoting `Unshipped` to `Shipped`, and the tag are the
maintainer's, at release time.

## Pending maintainer tasks for the release after 2.0.0

The package validation is set up for the 2.0.0 release: its baseline is 1.1.0, and
`ResXLocalization.MessageFormat`, which has no 1.1.0 version, is excluded from the baseline. When the
maintainer prepares the next release after 2.0.0 - a `<Version>` bump, a dated changelog section, or a
question about releasing - remind them of these steps, as part of `CONTRIBUTING.md`'s release step 3. Do
not do them yourself; they are the maintainer's, like the version.

1. Set `PackageValidationBaselineVersion` in `src/Directory.Build.props` to `2.0.0`.
2. In the same file, remove `AND '$(_ConventionProjectName)' != 'ResXLocalization.MessageFormat'` from the
condition of the `PropertyGroup` that sets `PackageValidationBaselineVersion`, and remove the comment
about `ResXLocalization.MessageFormat` in it. Keep the group and the property: the condition becomes
`'$(_IsShippingPackage)' == 'true'`, so the MessageFormat package is validated against 2.0.0 like the
others.
3. Delete `CompatibilitySuppressions.xml` in `src/ResXLocalization.Core`, `src/ResXLocalization.Avalonia`
and `src/ResXLocalization.WPF`: they accept breaks against the 1.1.0 baseline only. Then run
`dotnet pack ResXLocalization.slnx -c Release` once to confirm that package validation passes without
them.
4. Remove this section from `AGENTS.md`.

## Commits and branches

[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) with a lowercase, imperative summary:
Expand Down
1 change: 0 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,6 @@ this project adheres to [Semantic Versioning](https://semver.org/).
- **BREAKING:** Two neutral `.resx` files that produce the same keys class report `RXLGEN004` and
generate neither class, instead of merging into one partial class. See the
[migration guide](docs/guides/migration-2.0.md).

- **BREAKING:** `Localizer.RegisterResourceManager` throws `ArgumentException` naming the base name for a
plain `ResourceManager` for which no resources exist under its base name, instead of registering it and
letting every search-all lookup that reaches it throw `MissingManifestResourceException`. Fix the base
Expand Down
22 changes: 11 additions & 11 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ This project has a [Code of Conduct](CODE_OF_CONDUCT.md); by participating, you
| You need | For |
| --- | --- |
| **.NET 10 SDK** | Everything. It is pinned in `global.json` |
| **.NET 8 SDK** | Running the Core tests on `net8.0`, and reproducing the minimum-SDK consumer checks |
| **.NET 8 SDK** | Running the Core and MessageFormat tests on `net8.0`, and reproducing the minimum-SDK consumer checks |
| **PowerShell 7** (`pwsh`) | Every script in `scripts/`. They declare `#requires -Version 7.0` and stop on the first line under an older host |
| **Windows** | The WPF projects, the WPF tests, and the full package and documentation build |
| **A C++ toolchain** | The Native AOT gate only. MSVC and the Windows SDK on Windows; `clang` and `zlib1g-dev` on Linux |
Expand All @@ -45,14 +45,14 @@ dotnet build ResXLocalization.NonWindows.slnf -c Release
```

```shell
# Test. One command; dotnet test discovers the suites and every target framework, so the Core suite
# runs on net8.0 and net10.0 from here.
# Test. One command; dotnet test discovers the suites and every target framework, so the Core and
# MessageFormat suites run on net8.0 and net10.0 from here.
dotnet test ResXLocalization.slnx -c Release # Windows
dotnet test ResXLocalization.NonWindows.slnf -c Release # Linux/macOS, without the WPF suite
```

There are four suites: the Core engine (on both target frameworks), the source generator, and one
sample-driven suite per UI framework. The Avalonia suite runs headless; the WPF suite drives a real
There are five suites: the Core engine and the ICU MessageFormat formatter (each on both target
frameworks), the source generator, and one sample-driven suite per UI framework. The Avalonia suite runs headless; the WPF suite drives a real
dispatcher on its own thread and is Windows-only.

### One optional per-clone setting
Expand Down Expand Up @@ -88,7 +88,7 @@ The script names them, with their trigger and their command, in its own summary
| Run it when the change touches | Command |
| --- | --- |
| Resource lookup, culture fallback, satellite discovery, the generated keys, or the packaging that carries them | `pwsh -File scripts/verify-package-aot.ps1 -Pack` |
| What the packages contain, the `buildTransitive` wiring, the generated keys, or a dependency version | `pwsh -File scripts/pre-release-gate.ps1 -SkipNativeAot -SkipDocumentation`, which packs and then runs every consumer on the pinned SDK, on both of AvaloniaConsumer's target frameworks, and again on the .NET 8 SDK, on net8.0 |
| What the packages contain, the `buildTransitive` wiring, the generated keys, or a dependency version | `pwsh -File scripts/pre-release-gate.ps1 -SkipNativeAot -SkipDocumentation`, which packs and then runs every consumer on the pinned SDK, on both target frameworks of AvaloniaConsumer and MessageFormatConsumer, and again on the .NET 8 SDK, on net8.0 |

**`pre-release-gate.ps1`** is everything CI checks that can honestly be checked on your machine, in CI's
order, stopping at the first failure: the ignored-revision check, line endings, tidiness, a Release build,
Expand Down Expand Up @@ -168,20 +168,20 @@ Anything that is not framework-specific belongs in `ResXLocalization.Core`, wher

## Native AOT

`ResXLocalization.Avalonia` and `ResXLocalization.Core` publish with `PublishAot=true` and produce no IL2xxx
or IL3xxx diagnostic, from anywhere. Keep it that way: no reflection over resources, no new suppressed IL
`ResXLocalization.Avalonia`, `ResXLocalization.Core` and `ResXLocalization.MessageFormat` publish with
`PublishAot=true` and produce no IL2xxx or IL3xxx diagnostic, from anywhere. Keep it that way: no reflection over resources, no new suppressed IL
diagnostic, and no `[RequiresUnreferencedCode]` or `[RequiresDynamicCode]` on a public member.

**Nothing is trimmed on the just-in-time compiler, so no test suite here can see trimming damage.** A
satellite that is no longer loaded or a resource name that no longer resolves produces a binary that builds,
starts and answers wrongly. `scripts/verify-package-aot.ps1` publishes a package-only consumer natively and
**runs** it, asserting exact strings; that is the only check that can see it.
starts and answers wrongly. `scripts/verify-package-aot.ps1` publishes the package-only consumers
`AvaloniaConsumer` and `MessageFormatConsumer` natively and **runs** them, asserting exact strings; that is the only check that can see it.

The WPF package is exempt — WPF does not support Native AOT.

## Public API

The three runtime projects track their public surface with
The four runtime projects track their public surface with
[PublicApiAnalyzers](https://github.com/dotnet/roslyn/tree/main/src/RoslynAnalyzers/PublicApiAnalyzers). An
undeclared public member is `RS0016` and a declared one that is gone is `RS0017` — both build errors here.

Expand Down
Loading
Loading