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
34 changes: 22 additions & 12 deletions .agents/references/reviews/aot-package-compat.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,9 @@

Use this whenever a change touches resource lookup, culture fallback, satellite discovery, the source
generator's output, or the analyzer and `buildTransitive` wiring the packages carry. This is a
**standing** checklist: `ResXLocalization.Avalonia` and `ResXLocalization.Core` advertise Native AOT
support, and everything here exists to keep it from regressing.
**standing** checklist: `ResXLocalization.Core`, `ResXLocalization.Avalonia` and
`ResXLocalization.MessageFormat` advertise Native AOT support, and everything here exists to keep it
from regressing.

Read [docs/guides/native-aot.md](../../../docs/guides/native-aot.md) before reviewing.

Expand All @@ -13,11 +14,12 @@ This is a **review**: report findings, cite file and line, do not edit files.

Trimming damage does not announce itself. A resource that is no longer found, a satellite assembly
that is no longer loaded, a typed key whose `ResourceManager` was trimmed away — each produces a
binary that builds, starts, and answers with the `!key!` sentinel or the wrong language. Nothing is
binary that builds, starts, and answers with the `!key!` failure text or the wrong language. Nothing is
trimmed on the just-in-time compiler, so **every test suite in this repository passes throughout**.

The only check that can see it is `scripts/verify-package-aot.ps1`, which publishes a package-only
consumer natively and runs it. A green test run is not evidence here. Neither is a native binary that
The only check that can see it is `scripts/verify-package-aot.ps1`, which publishes two package-only
consumers natively and runs them: `AvaloniaConsumer`, and `MessageFormatConsumer` for the ICU formatter
of `ResXLocalization.MessageFormat`. A green test run is not evidence here. Neither is a native binary that
exists: the gate runs it and asserts exact strings for exactly this reason.

## Blocking findings
Expand All @@ -31,9 +33,16 @@ exists: the gate runs it and asserts exact strings for exactly this reason.
the requirement to the caller. But adding either to a public member is its own blocking finding —
it changes what a consumer sees when they publish, and the packages promise they see nothing.

- **`IsAotCompatible` removed from `ResXLocalization.Core` or `ResXLocalization.Avalonia`**, or added
to `ResXLocalization.WPF`. The first two set it through `src/Directory.Build.props`; WPF is
excluded there deliberately, because WPF has no Native AOT.
- **`IsAotCompatible` removed from `ResXLocalization.Core`, `ResXLocalization.Avalonia` or
`ResXLocalization.MessageFormat`**, or added to `ResXLocalization.WPF`. The first three set it
through `src/Directory.Build.props`; WPF is excluded there deliberately, because WPF has no Native
AOT.

- **A call to an `object args` overload of the `MessageFormat` library** in
`src/ResXLocalization.MessageFormat` - the extension `MessageFormatterExtensions.FormatMessage` or the
static `MessageFormatter.Format(string, object, CultureInfo?)`. Both read properties by reflection,
carry `[RequiresUnreferencedCode]` and lose every argument in a Native AOT binary. The package calls
only the `IReadOnlyDictionary` overload of `FormatMessage`.

- **A new reflection call** — `Type.GetType`, `Assembly.Load`, `Activator.CreateInstance`,
`GetMethod`, `GetProperty`, `MakeGenericType` — reachable from a public entry point without a
Expand All @@ -42,8 +51,9 @@ exists: the gate runs it and asserts exact strings for exactly this reason.
reflection site is a change of kind rather than of degree.

- **Anything that makes a satellite assembly optional.** The German satellite is what the AOT gate
asserts on: a change that stops the consumer producing `de/AvaloniaConsumer.resources.dll`, or
stops the library finding it, is the exact failure this gate exists for.
asserts on: a change that stops a consumer producing `de/AvaloniaConsumer.resources.dll` or
`de/MessageFormatConsumer.resources.dll`, or stops the library finding it, is the exact failure this
gate exists for.

## The generator's output

Expand Down Expand Up @@ -106,8 +116,8 @@ check would have caught it. Where the answer needs a build, a pack or the AOT ga
name the command:

```text
pwsh -File scripts/verify-package-aot.ps1 -Pack # both frameworks, from a fresh pack
pwsh -File scripts/verify-package-aot.ps1 -Framework net8.0 # the LTS floor alone
pwsh -File scripts/verify-package-aot.ps1 -Pack # both consumers on net10.0, from a fresh pack
pwsh -File scripts/verify-package-aot.ps1 -Framework net8.0 # both consumers on the LTS floor
pwsh -File scripts/pre-release-gate.ps1 -SkipNativeAot -SkipDocumentation # every consumer, pinned SDK and .NET 8 SDK
```

Expand Down
18 changes: 12 additions & 6 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ env:
DOTNET_CLI_TELEMETRY_OPTOUT: true
DOTNET_NOLOGO: true
DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true
MESSAGEFORMAT_CONSUMER_PROJECT: tests/package-consumption/MessageFormatConsumer/MessageFormatConsumer.csproj
NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages
NUGET_CONFIG: NuGet.config
PACKAGE_OUTPUT: artifacts/packages
Expand Down Expand Up @@ -414,6 +415,10 @@ jobs:
working-directory: ${{ env.CONSUMER_DIRECTORY }}
run: dotnet run --project AvaloniaConsumer/AvaloniaConsumer.csproj --framework net8.0 -p:TargetFrameworks=net8.0 --configuration ${{ env.CONFIGURATION }} -p:ResXLocalizationVersion=${{ needs.package-and-docs.outputs.version }}

- name: Run MessageFormat package consumer (net8.0 SDK)
working-directory: ${{ env.CONSUMER_DIRECTORY }}
run: dotnet run --project MessageFormatConsumer/MessageFormatConsumer.csproj --framework net8.0 -p:TargetFrameworks=net8.0 --configuration ${{ env.CONFIGURATION }} -p:ResXLocalizationVersion=${{ needs.package-and-docs.outputs.version }}

- name: Run WPF package consumer (net8.0 SDK)
if: runner.os == 'Windows'
working-directory: ${{ env.CONSUMER_DIRECTORY }}
Expand All @@ -438,10 +443,10 @@ jobs:
shell: bash
run: rm -f "${CONSUMER_DIRECTORY}/global.json"

# The packed-package Native AOT gate. It publishes the Avalonia consumer with PublishAot, requires zero
# IL2xxx/IL3xxx diagnostics, and RUNS the native binary - a file that exists proves nothing, because
# everything trimming can break (a satellite that is no longer loaded, a resource name that no longer
# resolves) produces a binary that starts and answers wrongly.
# The packed-package Native AOT gate. It publishes AvaloniaConsumer and MessageFormatConsumer with
# PublishAot, requires zero IL2xxx/IL3xxx diagnostics, and RUNS each native binary - a file that exists
# proves nothing, because everything trimming can break (a satellite that is no longer loaded, a
# resource name that no longer resolves) produces a binary that starts and answers wrongly.
#
# Three runs. The trimming behaviour under test belongs to the ILC compiler and does not vary by host,
# so net8.0 - the LTS floor the packages promise - is exercised on Linux, and net10.0 on both.
Expand Down Expand Up @@ -529,7 +534,8 @@ jobs:
path: ${{ env.PACKAGE_OUTPUT }}

# The script is the gate, not this job: it validates the artifact set from each nuspec, isolates the
# consumer package cache, publishes, requires zero IL diagnostics, and runs the binary.
# consumer package cache, then publishes both consumers, requires zero IL diagnostics, and runs each
# binary.
- name: Native AOT gate
run: pwsh -NoProfile -NonInteractive -File scripts/verify-package-aot.ps1 -Framework ${{ matrix.framework }} -Runtime ${{ matrix.runtime }} -PackageVersion ${{ needs.package-and-docs.outputs.version }} -Configuration ${{ env.CONFIGURATION }}

Expand Down Expand Up @@ -618,7 +624,7 @@ jobs:
run: |
tag_version="${GITHUB_REF_NAME#v}"
status=0
for id in ResXLocalization.Core ResXLocalization.Avalonia ResXLocalization.WPF; do
for id in ResXLocalization.Core ResXLocalization.Avalonia ResXLocalization.MessageFormat ResXLocalization.WPF; do
if [[ ! -f "${PACKAGE_OUTPUT}/${id}.${tag_version}.nupkg" ]]; then
echo "::error title=Tag/version mismatch::Tag ${GITHUB_REF_NAME} expects ${id}.${tag_version}.nupkg, but the build produced:"
ls -1 "${PACKAGE_OUTPUT}"
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Two things separate it from plain `.resx`:

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!` sentinel plus a `TranslationNotFound` event for missing translations, and Native AOT and
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).

[`README.md`](README.md) is the user-facing version of the same story, with the quick start and the examples.
Expand Down
2 changes: 1 addition & 1 deletion PACKAGE_README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ you keep the `.resx` files and editors you already use, and get **compile-checke
- 🗂️ **First-class multiple `.resx` support** - look up by typed key, scope to one file, or search across all registered files.
- 🔤 **Enum localization built in** - localize enum members by naming convention.
- 🧮 **Format arguments** - `Get(key, args…)` formats in the active culture; in XAML, give `{l:Localize}` `<l:Argument>` children with constant or bound values.
- 🩺 **Missing-translation diagnostics** - a visible, configurable `!key!` sentinel plus a `TranslationNotFound` event.
- 🩺 **Missing-translation diagnostics** - a visible, configurable `!key!` failure text plus a `TranslationNotFound` event.
- 🌐 **Language-picker ready** - `GetAvailableCultures()` discovers the cultures your app actually ships.
- 🚀 **Native AOT & trim clean** (Avalonia package) - no reflection over your resources.

Expand Down
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ Localizer.Current.CurrentCulture = new CultureInfo("de");
- 🗂️ **First-class multiple `.resx`** - look up by **typed key**, **scope** to one file, or **search across all** registered files in a defined order.
- 🔤 **Enum localization built in** - localize enum members by naming convention, in item templates and as bound values.
- 🧮 **Format arguments** - `Get(key, args…)` formats the translation in the active culture; in XAML, give `{l:Localize}` `<l:Argument>` children with constant or bound values.
- 🩺 **Missing-translation diagnostics** - a visible `!key!` sentinel (configurable) plus a `TranslationNotFound` event for logging and coverage reports.
- 🩺 **Missing-translation diagnostics** - a visible `!key!` failure text (configurable) plus a `TranslationNotFound` event for logging and coverage reports.
- 🌐 **Language-picker ready** - `GetAvailableCultures()` discovers the cultures your app actually ships.
- 🧩 **MVVM-friendly** - an injectable `ILocalizer` service with `INotifyPropertyChanged`, markup extensions for XAML, and a clean code-behind API.
- 🪶 **Leak-safe** - discarded controls stay collectable (Avalonia uses weak events; WPF binds to the singleton through WPF's own weak binding-target references).
Expand Down Expand Up @@ -176,7 +176,7 @@ public partial class App : Application
Registration is only needed for **search-all** lookups; typed and scoped lookups need no registration.

> [!TIP]
> In Avalonia, put the registration (and the initial `CurrentCulture`) inside **`BuildAvaloniaApp()`** rather than `Main`. `BuildAvaloniaApp` runs at runtime *and* under the XAML previewer, so search-all lookups like `{l:Localize Greeting}` resolve at design time too instead of showing the `!Greeting!` sentinel.
> In Avalonia, put the registration (and the initial `CurrentCulture`) inside **`BuildAvaloniaApp()`** rather than `Main`. `BuildAvaloniaApp` runs at runtime *and* under the XAML previewer, so search-all lookups like `{l:Localize Greeting}` resolve at design time too instead of showing the `!Greeting!` failure text.

### 4. Use it in XAML

Expand Down Expand Up @@ -232,7 +232,7 @@ Localizer.Current.Get("Greeting"); // search-al
```

Fallback is .NET's own: a missing `de-DE` entry falls back to `de`, then to the neutral resources. A
key that cannot be resolved anywhere renders the configurable `!key!` sentinel and raises
key that cannot be resolved anywhere renders the configurable `!key!` failure text and raises
`TranslationNotFound`. Because fallback runs first, a key that resolves from a parent or neutral
value is not reported as missing.

Expand Down
37 changes: 28 additions & 9 deletions docs/guides/native-aot.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Native AOT and trimming

`ResXLocalization.Avalonia` and `ResXLocalization.Core` publish with `PublishAot=true` and produce no
IL2xxx or IL3xxx diagnostic — not from the library, not from a package in the closure, and not at
your own call sites. There is no `[RequiresUnreferencedCode]` or `[RequiresDynamicCode]` on any
`ResXLocalization.Avalonia`, `ResXLocalization.Core` and `ResXLocalization.MessageFormat` publish with
`PublishAot=true` and produce no IL2xxx or IL3xxx diagnostic — not from the library, not from a package
in the closure, and not at your own call sites. There is no `[RequiresUnreferencedCode]` or `[RequiresDynamicCode]` on any
public member, so nothing about a trimmed publish is a warning you have to read and dismiss.

One annotation reaches your code: `MessageArguments.FromObject<T>` reads the public properties of `T`,
Expand Down Expand Up @@ -41,6 +41,24 @@ Two more are worth setting for an Avalonia application in general:
</PropertyGroup>
```

Format arguments in XAML are trim safe when their bindings are compiled bindings: in Avalonia,
`Value="{Binding ...}"` of an `<l:Argument>` is a compiled binding under
`AvaloniaUseCompiledBindingsByDefault` or `x:CompileBindings="True"`, and a reflection binding
otherwise. See [Dynamic format arguments](format-arguments.md#worth-knowing).

## ICU MessageFormat

The opt-in package `ResXLocalization.MessageFormat` adds about 160 KB to a Native AOT binary, the
`MessageFormat` library included. It produces no IL diagnostic on `net8.0` or `net10.0`, because it
calls only the `IReadOnlyDictionary` overload of the library's `FormatMessage`; the library's overloads
that take an `object` read the properties of that object by reflection and are not called. See
[ICU MessageFormat](message-format.md).

`InvariantGlobalization=true` is often recommended for a small Native AOT binary, but it leaves a
localized application with the invariant culture only — with `PredefinedCulturesOnly=false` as well,
with named cultures whose numbers and dates format invariantly. See
[Globalization-invariant mode](message-format.md#globalization-invariant-mode).

## Publishing

```shell
Expand All @@ -58,14 +76,15 @@ longer loaded, a typed key whose resource manager was trimmed away — each of t
that builds, starts, and answers wrongly. Nothing is trimmed on the just-in-time compiler, so a test
suite passes throughout.

This repository's own gate therefore publishes a package-only consumer natively and **runs** it,
asserting exact strings before and after a culture change, through the typed, scoped and search-all
lookups, the enum convention, composite formatting, named arguments built by reflection with
`MessageArguments.FromObject`, and the fallback to the neutral culture. See
`scripts/verify-package-aot.ps1`. A check that only asserts the executable exists proves that the
This repository's own gate therefore publishes two package-only consumers natively and **runs** them,
asserting exact strings before and after a culture change. The first covers the typed, scoped and
search-all lookups, the enum convention, composite formatting, named arguments built by reflection with
`MessageArguments.FromObject`, and the fallback to the neutral culture. The second covers the ICU
formatter: `plural` patterns with a named argument from a compiled binding, in code and in XAML, and
the invariant culture formatted with English plural rules. See `scripts/verify-package-aot.ps1`. A check that only asserts the executable exists proves that the
linker ran, and nothing else.

## If a lookup returns the sentinel only after publishing
## If a lookup returns the failure text only after publishing

In order of likelihood:

Expand Down
3 changes: 2 additions & 1 deletion scripts/pre-commit-gate.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,8 @@
the way a stranger would, which a project-referenced test cannot.
Run: pwsh -File scripts/pre-release-gate.ps1 -SkipNativeAot -SkipDocumentation
which packs and then runs all of them on the pinned SDK, on both of
AvaloniaConsumer's target frameworks, and again on the .NET 8 SDK.
the target frameworks of AvaloniaConsumer and MessageFormatConsumer,
and again on the .NET 8 SDK.

.PARAMETER Fix
Apply style, formatting and member ordering to the working tree before the checks, instead of only
Expand Down
13 changes: 9 additions & 4 deletions scripts/pre-release-gate.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -585,12 +585,14 @@ Invoke-Step 'Package consumers' {
return
}

# AvaloniaConsumer targets net8.0 and net10.0, and `dotnet run` runs a project with several target
# frameworks only when one is named, so the consumer runs once per framework with `--framework`. That
# way both of the packages' target frameworks are exercised.
# AvaloniaConsumer and MessageFormatConsumer target net8.0 and net10.0, and `dotnet run` runs a project
# with several target frameworks only when one is named, so each consumer runs once per framework with
# `--framework`. That way both of the packages' target frameworks are exercised.
$consumers = @(
@{ Name = 'AvaloniaConsumer'; Arguments = @('--framework', 'net8.0') }
@{ Name = 'AvaloniaConsumer'; Arguments = @('--framework', 'net10.0') }
@{ Name = 'MessageFormatConsumer'; Arguments = @('--framework', 'net8.0') }
@{ Name = 'MessageFormatConsumer'; Arguments = @('--framework', 'net10.0') }
)

if ($onWindows)
Expand Down Expand Up @@ -659,7 +661,10 @@ Invoke-Step 'Package consumers (.NET 8 SDK)' {

# -p:TargetFrameworks as well as --framework: restore evaluates every entry in TargetFrameworks, and
# an 8.0 SDK cannot evaluate net10.0 (NETSDK1045).
$consumers = @(@{ Name = 'AvaloniaConsumer'; Arguments = @('--framework', 'net8.0', '-p:TargetFrameworks=net8.0') })
$consumers = @(
@{ Name = 'AvaloniaConsumer'; Arguments = @('--framework', 'net8.0', '-p:TargetFrameworks=net8.0') }
@{ Name = 'MessageFormatConsumer'; Arguments = @('--framework', 'net8.0', '-p:TargetFrameworks=net8.0') }
)

if ($onWindows)
{
Expand Down
Loading
Loading