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
297 changes: 292 additions & 5 deletions .github/workflows/ci.yml

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@ supports neither).
| `src/ResXLocalization.WPF` | The same for WPF. Windows-only, no Native AOT |
| `samples/` | Two runnable showcases, one per UI framework. Excluded from coverage |
| `tests/` | Five suites: Core and `tests/ResXLocalization.MessageFormat.Tests` (both on both frameworks), the generator, and one sample-test suite per UI framework |
| `benchmarks/` | Three BenchmarkDotNet suites - Core with MessageFormat, Avalonia headless, WPF - each against the code an application writes without the library, and `Shared/`, compiled into all three. Not test projects; CI runs them and gates on allocations |
| `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
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,14 @@ this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added

- A BenchmarkDotNet suite under `benchmarks/` that measures code lookups, ICU MessageFormat and the Avalonia
and WPF markup extensions against the `.resx` designer class.
- A [benchmark results page](https://rent-a-developer.github.io/ResXLocalization/guides/benchmarks.html) in
the documentation: what each lookup, markup extension and culture switch costs compared with the `.resx`
designer class, with the latest results and their history on `main`.

## [2.0.0] - 2026-10-20

### Added
Expand Down
30 changes: 30 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -179,6 +179,36 @@ starts and answers wrongly. `scripts/verify-package-aot.ps1` publishes the packa

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

## Running the benchmarks

`benchmarks/` holds three BenchmarkDotNet suites: `ResXLocalization.Core.Benchmarks` (Core and
MessageFormat), `ResXLocalization.Avalonia.Benchmarks` (headless) and `ResXLocalization.WPF.Benchmarks`
(Windows only). Each compares the library with the code an application writes without it, see
[`docs/guides/benchmarks.md`](docs/guides/benchmarks.md). Run one suite from the repository root, all of its
benchmarks or the classes `--filter` selects:

```shell
dotnet run --project benchmarks/ResXLocalization.Core.Benchmarks -c Release
dotnet run --project benchmarks/ResXLocalization.Core.Benchmarks -c Release -- --filter "*CodeLookup*"
```

The reports land in `artifacts/benchmarks/<project>/results`. Every class checks once, before it measures,
that each benchmark produces the expected text, and stops with an error naming the benchmark when it does
not.

CI runs the three suites on every pull request and every push to `main` that changes code, and compares
them with the latest results from `main`:

- **More allocations fail the check**: a benchmark that allocates more than 125% of its bytes on `main`, or
anything at all where it allocated nothing.
- **A slower time is an alert, not a failure**: above 150% of the time on `main` it is listed in the job
summary and commented on the pull request. Shared CI machines vary too much in speed to fail on time.

When an allocation increase is deliberate - a feature that has to allocate - a maintainer reviews it and adds
the label `accept-allocation-increase` to the pull request. The check then reports the increase and passes,
and the merged values become the baseline for every later pull request. Removing the label makes the check
fail again.

## Public API

The four runtime projects track their public surface with
Expand Down
4 changes: 4 additions & 0 deletions Directory.Packages.props
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,10 @@
<PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.10.1" />
<PackageVersion Include="xunit.runner.visualstudio" Version="3.1.5" />
<PackageVersion Include="xunit.v3" Version="3.2.2" />

<!-- Benchmark stack, referenced only by the projects under benchmarks/. -->
<PackageVersion Include="Avalonia.Headless" Version="12.1.2" />
<PackageVersion Include="BenchmarkDotNet" Version="0.15.8" />
</ItemGroup>

<!-- ==================================================================================================
Expand Down
4 changes: 3 additions & 1 deletion ResXLocalization.NonWindows.slnf
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,9 @@
"tests\\ResXLocalization.Avalonia.Sample.Tests\\ResXLocalization.Avalonia.Sample.Tests.csproj",
"tests\\ResXLocalization.Core.Tests\\ResXLocalization.Core.Tests.csproj",
"tests\\ResXLocalization.MessageFormat.Tests\\ResXLocalization.MessageFormat.Tests.csproj",
"tests\\ResXLocalization.SourceGenerators.Tests\\ResXLocalization.SourceGenerators.Tests.csproj"
"tests\\ResXLocalization.SourceGenerators.Tests\\ResXLocalization.SourceGenerators.Tests.csproj",
"benchmarks\\ResXLocalization.Core.Benchmarks\\ResXLocalization.Core.Benchmarks.csproj",
"benchmarks\\ResXLocalization.Avalonia.Benchmarks\\ResXLocalization.Avalonia.Benchmarks.csproj"
]
}
}
5 changes: 5 additions & 0 deletions ResXLocalization.slnx
Original file line number Diff line number Diff line change
Expand Up @@ -17,4 +17,9 @@
<Project Path="tests/ResXLocalization.SourceGenerators.Tests/ResXLocalization.SourceGenerators.Tests.csproj" />
<Project Path="tests/ResXLocalization.WPF.Sample.Tests/ResXLocalization.WPF.Sample.Tests.csproj" />
</Folder>
<Folder Name="/04_benchmarks/">
<Project Path="benchmarks/ResXLocalization.Avalonia.Benchmarks/ResXLocalization.Avalonia.Benchmarks.csproj" />
<Project Path="benchmarks/ResXLocalization.Core.Benchmarks/ResXLocalization.Core.Benchmarks.csproj" />
<Project Path="benchmarks/ResXLocalization.WPF.Benchmarks/ResXLocalization.WPF.Benchmarks.csproj" />
</Folder>
</Solution>
82 changes: 82 additions & 0 deletions benchmarks/Directory.Build.props
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
<Project>

<!--
Shared build properties for the benchmark projects.

MSBuild uses the NEAREST Directory.Build.props and stops there, so this file imports the repository
root one explicitly, like tests/Directory.Build.props does - without that import the benchmarks would lose
the language settings, the style analyzers and the style gate. They do not import tests/: a BenchmarkDotNet
console app must not carry the test SDK, xUnit or the coverage collector.

What belongs here is what every benchmark project needs: BenchmarkDotNet, and the code under Shared/ (the
configuration, the self-check and the entry point), compiled into each project rather than copied.
-->

<Import Project="$(MSBuildThisFileDirectory)../Directory.Build.props" />

<PropertyGroup>
<OutputType>Exe</OutputType>
</PropertyGroup>

<PropertyGroup>
<!-- CS1591 (missing XML comment) and CS1574 (unresolvable cref) are only reported because every
project generates a documentation file, which is what makes IDE0005 work - see the comment in
the repository-root Directory.Build.props. Nothing consumes the benchmarks as an API, and the typed
key classes the source generator emits are public and deliberately carry no per-member
documentation.

This is NoWarn rather than an .editorconfig severity because .editorconfig cannot reach a
source-generated document: Roslyn resolves analyzer configuration from a syntax tree's path,
and a generated tree has none, so no section - not even [*] - applies to it. Under src/ both
diagnostics stay errors, which is what keeps the public API documented. -->
<NoWarn>$(NoWarn);CS1574;CS1591</NoWarn>
</PropertyGroup>

<ItemGroup>
<PackageReference Include="BenchmarkDotNet" />
</ItemGroup>

<ItemGroup>
<!-- The tiered JIT promotes a method to optimized code only after 30 calls and once no new method was
compiled for 100 ms. One UI operation keeps compiling new methods, so with the delay its methods stayed
unoptimized through a whole class: the first UI class's first row measured up to three times as slow
as the same operation later in the process. Without the delay the methods are promoted as soon as they
have their calls; dynamic PGO still runs, so the code and its allocations are the ones a long-running
application has. The benchmarks run in-process, so this has to be the host's own configuration. -->
<RuntimeHostConfigurationOption Include="System.Runtime.TieredCompilation.CallCountingDelayMs" Value="0" />
</ItemGroup>

<ItemGroup>
<Compile Include="$(MSBuildThisFileDirectory)Shared\*.cs" Link="Shared\%(Filename)%(Extension)" />
</ItemGroup>

<!-- The texts every benchmark looks up: one resx with the keys of all three suites, linked into each
project like the code under Shared/. The neutral file embeds into the project's assembly and the .de
file builds the project's de satellite. A suite carrying keys it does not use changes no number:
ResourceManager finds a key in a dictionary.

BenchmarkStrings.Designer.cs is hand-authored to mirror exactly what PublicResXFileCodeGenerator emits
(that generator only runs inside Visual Studio); its properties are the baselines. Its namespace is the
one of the code under Shared/, so every benchmark file reaches BenchmarkStrings and the generated
BenchmarkStringsKeys through the using of that namespace it already has. The LogicalName is that
class's base name: a linked file would otherwise be named after the project's RootNamespace and its
link path, which the designer class does not match. The resx and Designer.cs files are handed to the
typed-key generator by the repo-level Directory.Build.targets. -->
<ItemGroup>
<EmbeddedResource Include="$(MSBuildThisFileDirectory)Shared\Resources\BenchmarkStrings.resx"
Link="Shared\Resources\BenchmarkStrings.resx"
LogicalName="RentADeveloper.ResXLocalization.Benchmarks.BenchmarkStrings.resources"
Generator="PublicResXFileCodeGenerator"
LastGenOutput="BenchmarkStrings.Designer.cs" />
<EmbeddedResource Include="$(MSBuildThisFileDirectory)Shared\Resources\BenchmarkStrings.de.resx"
Link="Shared\Resources\BenchmarkStrings.de.resx"
LogicalName="RentADeveloper.ResXLocalization.Benchmarks.BenchmarkStrings.de.resources"
DependentUpon="BenchmarkStrings.resx" />
<Compile Include="$(MSBuildThisFileDirectory)Shared\Resources\BenchmarkStrings.Designer.cs"
Link="Shared\Resources\BenchmarkStrings.Designer.cs"
DependentUpon="BenchmarkStrings.resx"
DesignTime="True"
AutoGen="True" />
</ItemGroup>

</Project>
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
using Avalonia.Controls;
using BenchmarkDotNet.Attributes;
using RentADeveloper.ResXLocalization.Avalonia.Benchmarks.Views;
using RentADeveloper.ResXLocalization.Benchmarks;

namespace RentADeveloper.ResXLocalization.Avalonia.Benchmarks;

/// <summary>
/// Opening 100 text elements that all use one form - 10 instances of a 10-element view as a headless window's
/// content - against the same layout with <c>{x:Static}</c> of the designer class's properties.
/// </summary>
/// <remarks>
/// 50 warmup iterations instead of the configuration's 3: an iteration here is one operation, and the tiered JIT
/// promotes a method only after 30 calls, so with fewer warmups the measured rows ran partly unoptimized code
/// and the first rows looked slower than the later ones (see also the call-counting delay in
/// benchmarks/Directory.Build.props).
/// </remarks>
[Config(typeof(BenchmarkConfig))]
[WarmupCount(50)]
public class AvaloniaFormsBenchmarks
{
private const int ViewCount = 10;

private Window window = null!;

[GlobalCleanup]
public void Cleanup() => AvaloniaSession.Run(this.window.Close);

[IterationCleanup]
public void Idle() => AvaloniaSession.EmptyWindow(this.window);

[Benchmark]
public StackPanel Localize() => this.Open(static () => new LocalizeView());

[Benchmark]
public StackPanel LocalizeEnum() => this.Open(static () => new EnumView());

[Benchmark]
public StackPanel LocalizeWithArguments() => this.Open(static () => new ArgumentsView());

[GlobalSetup]
public void Setup()
{
AvaloniaSession.Start();
Localizer.Current.ClearResourceManagers();
Localizer.Current.RegisterResourceManager(BenchmarkStringsKeys.ResourceManager);
BenchmarkCulture.Use(BenchmarkCulture.German);
this.window = AvaloniaSession.Run(AvaloniaSession.ShowWindow);

SelfCheck.Verify<StackPanel>(
this,
static name =>
ExpectedViewTexts.Repeat(
name switch
{
nameof(LocalizeWithArguments) => ExpectedViewTexts.GermanWithArguments,
nameof(LocalizeEnum) => ExpectedViewTexts.GermanEnum,
_ => ExpectedViewTexts.German,
},
ViewCount
),
AvaloniaSession.GetTextsOfAllTextBlocks
);
}

[Benchmark(Baseline = true)]
public StackPanel Static() => this.Open(static () => new StaticView());

private StackPanel Open(Func<Control> createView) =>
AvaloniaSession.Run(() => AvaloniaSession.Open(this.window, ViewCount, createView));
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
using Avalonia.Controls;
using Avalonia.Threading;
using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Configs;
using RentADeveloper.ResXLocalization.Avalonia.Benchmarks.Views;
using RentADeveloper.ResXLocalization.Benchmarks;

namespace RentADeveloper.ResXLocalization.Avalonia.Benchmarks;

/// <summary>
/// Opening a view with <see cref="ElementCount" /> <c>{l:Localize}</c> elements, against <c>{x:Static}</c>, and
/// switching the culture while they are live, against the hand-written <see cref="TranslationSource" />. The
/// elements are <see cref="ElementCount" /> / 10 instances of a 10-element view in one headless window.
/// </summary>
/// <remarks>
/// Every iteration is one operation (<c>InvocationCount = 1</c>), which the culture switch needs for its
/// <c>[IterationSetup]</c> and which keeps the 10,000-element rows short. 5 measured iterations instead of the
/// configuration's 15, because an iteration of a 10,000-element row takes up to a second plus its setup and
/// cleanup.
/// </remarks>
[Config(typeof(BenchmarkConfig))]
[CategoriesColumn]
[GroupBenchmarksBy(BenchmarkLogicalGroupRule.ByCategory)]
[InvocationCount(1)]
[IterationCount(5)]
public class AvaloniaScalingBenchmarks
{
private const string OpenCategory = "Open";

private const string SwitchCategory = "Switch";

private Window window = null!;

[Params(100, 10_000)]
public int ElementCount { get; set; }

private int ViewCount => this.ElementCount / 10;

[GlobalCleanup]
public void Cleanup() => AvaloniaSession.Run(this.window.Close);

[IterationCleanup]
public void Idle() => AvaloniaSession.EmptyWindow(this.window);

[Benchmark]
[BenchmarkCategory(OpenCategory)]
public StackPanel OpenLocalize() => this.Open(static () => new LocalizeView());

[Benchmark(Baseline = true)]
[BenchmarkCategory(OpenCategory)]
public StackPanel OpenStatic() => this.Open(static () => new StaticView());

[GlobalSetup]
public void Setup()
{
AvaloniaSession.Start();
Localizer.Current.ClearResourceManagers();
BenchmarkCulture.Use(BenchmarkCulture.German);
this.window = AvaloniaSession.Run(AvaloniaSession.ShowWindow);

SelfCheck.Verify<StackPanel>(
this,
name =>
ExpectedViewTexts.Repeat(
name.StartsWith(SwitchCategory, StringComparison.Ordinal)
? ExpectedViewTexts.English
: ExpectedViewTexts.German,
this.ViewCount
),
AvaloniaSession.GetTextsOfAllTextBlocks
);
}

[IterationSetup(Targets = [nameof(SwitchLocalize)])]
public void SetupLocalizeViews() => this.SetupViews(static () => new LocalizeView());

[IterationSetup(Targets = [nameof(SwitchTranslationSource)])]
public void SetupTranslationSourceViews() => this.SetupViews(static () => new TranslationSourceView());

[Benchmark]
[BenchmarkCategory(SwitchCategory)]
public StackPanel SwitchLocalize() =>
this.Switch(static () => Localizer.Current.CurrentCulture = BenchmarkCulture.English);

[Benchmark(Baseline = true)]
[BenchmarkCategory(SwitchCategory)]
public StackPanel SwitchTranslationSource() =>
this.Switch(static () => TranslationSource.Instance.Culture = BenchmarkCulture.English);

private StackPanel Open(Func<Control> createView) =>
AvaloniaSession.Run(() => AvaloniaSession.Open(this.window, this.ViewCount, createView));

/// <summary>
/// Builds the views of a culture switch in German, outside the measurement. The previous iteration's views
/// are removed first, so that only these views are live when BenchmarkDotNet collects garbage before the
/// iteration. The culture is set on the UI thread, because views an earlier benchmark left may still be
/// subscribed and update their texts; the <c>CurrentUICulture</c> it sets there ends with the call, and none
/// of these views reads it.
/// </summary>
/// <param name="createView">Creates one view.</param>
private void SetupViews(Func<Control> createView) =>
AvaloniaSession.Run(() =>
{
this.window.Content = null;
BenchmarkCulture.Use(BenchmarkCulture.German);
_ = AvaloniaSession.Open(this.window, this.ViewCount, createView);
});

/// <summary>
/// Switches the culture and processes the dispatcher's pending binding work, down to
/// <see cref="DispatcherPriority.Normal" />, which is above layout and rendering, as in WPF. Avalonia updates
/// a binding on the UI thread as soon as its source raises <c>PropertyChanged</c>, so every element shows the
/// new text when this returns; the self-check confirms it for all of them.
/// </summary>
/// <param name="switchCulture">Switches the culture.</param>
/// <returns>The panel with the views.</returns>
private StackPanel Switch(Action switchCulture) =>
AvaloniaSession.Run(() =>
{
switchCulture();
Dispatcher.UIThread.RunJobs(DispatcherPriority.Normal);
return (StackPanel)this.window.Content!;
});
}
Loading
Loading